# ntfy — Simple Push Notifications via HTTP PUT/POST

> ntfy (notify) lets you send push notifications to your phone or desktop using simple HTTP requests. No app registration, no API keys — just curl a URL.

## Install

Save as a script file and run:

## Quick Use

```bash
# Send a notification (no setup needed!)
curl -d "Backup completed successfully" ntfy.sh/mytopic

# Or self-host
docker run -d --name ntfy -p 80:80 binwiederhier/ntfy serve
```

Install the ntfy app on your phone, subscribe to "mytopic", and receive notifications instantly.

## Intro

**ntfy** (pronounced "notify") is a simple HTTP-based push notification service. It lets you send notifications to your phone or desktop from any script, cron job, or application using a simple HTTP PUT/POST request — no signup, no API keys, no app registration required. Just pick a topic name and start sending.

With 29.7K+ GitHub stars and Apache-2.0 license, ntfy has become the favorite notification tool for developers, sysadmins, and homelab enthusiasts who need a dead-simple way to get alerts from their scripts and servers.

## What ntfy Does

- **HTTP Notifications**: Send notifications with a single curl command
- **Mobile Apps**: Native Android and iOS apps with push notifications
- **Web App**: PWA for desktop notifications in the browser
- **No Signup**: Use ntfy.sh for free or self-host — no account needed
- **Attachments**: Send files and images with notifications
- **Actions**: Add clickable buttons and URLs to notifications
- **Priority Levels**: 5 priority levels from min to urgent (with different sounds)
- **Scheduled Delivery**: Schedule notifications for future delivery
- **Authentication**: Optional auth for private self-hosted instances
- **UnifiedPush**: Acts as UnifiedPush distributor for other apps

## How It Works

```
Your Script                    ntfy Server              Your Phone
──────────                    ───────────              ──────────
curl -d "msg" ntfy.sh/topic ──▶ Store & Forward ──▶ Push notification
                                                       📱 *ding*
```

That's it. No OAuth, no webhooks to configure, no SDK to install.

## Usage Examples

### Basic Notification

```bash
# Simple message
curl -d "Deployment complete" ntfy.sh/my-alerts

# With title
curl -H "Title: Server Alert" -d "Disk usage above 90%" ntfy.sh/my-alerts

# With priority
curl -H "Priority: urgent" -H "Title: 🔴 DB Down" 
  -d "PostgreSQL is not responding" ntfy.sh/my-alerts

# With tags/emojis
curl -H "Tags: warning,rotating_light" 
  -d "CPU temperature 95°C" ntfy.sh/my-alerts
```

### In Scripts

```bash
# Backup script
#!/bin/bash
if pg_dump mydb > backup.sql; then
  curl -d "✅ Database backup completed ($(du -h backup.sql | cut -f1))" ntfy.sh/backups
else
  curl -H "Priority: high" -H "Tags: x" 
    -d "❌ Database backup failed!" ntfy.sh/backups
fi
```

```bash
# Cron job monitoring
0 2 * * * /usr/local/bin/backup.sh && curl -d "Nightly backup OK" ntfy.sh/cron-alerts
```

```bash
# Long-running process
./train-model.py && curl -d "Model training complete! Accuracy: 94.2%" ntfy.sh/ml-alerts
```

### With Actions (Clickable Buttons)

```bash
curl -H "Actions: view, Open Dashboard, https://grafana.example.com; 
  http, Restart Service, https://api.example.com/restart, method=POST" 
  -d "Service health check failed" ntfy.sh/my-alerts
```

### With Attachments

```bash
# Send image
curl -T screenshot.png -H "Filename: error-screenshot.png" ntfy.sh/my-alerts

# Send with message and attachment URL
curl -H "Attach: https://example.com/report.pdf" 
  -d "Monthly report is ready" ntfy.sh/my-alerts
```

### From Any Language

```python
# Python
import requests
requests.post("https://ntfy.sh/my-alerts",
  data="Build #456 passed ✅",
  headers={"Title": "CI/CD", "Priority": "default"})
```

```javascript
// JavaScript
fetch('https://ntfy.sh/my-alerts', {
  method: 'POST',
  body: 'Deployment to production complete',
  headers: { 'Title': 'Deploy', 'Priority': 'high' }
});
```

## Self-Hosting

### Docker

```bash
docker run -d --name ntfy 
  -p 80:80 
  -v ntfy-cache:/var/cache/ntfy 
  -v ntfy-etc:/etc/ntfy 
  binwiederhier/ntfy serve 
  --cache-file /var/cache/ntfy/cache.db
```

### Docker Compose

```yaml
services:
  ntfy:
    image: binwiederhier/ntfy
    command: serve
    ports:
      - "80:80"
    volumes:
      - ntfy-cache:/var/cache/ntfy
      - ./server.yml:/etc/ntfy/server.yml
    environment:
      TZ: Asia/Shanghai
    restart: unless-stopped

volumes:
  ntfy-cache:
```

### Configuration

```yaml
# server.yml
base-url: https://ntfy.yourdomain.com
cache-file: /var/cache/ntfy/cache.db
auth-file: /var/lib/ntfy/user.db
auth-default-access: deny-all  # Require auth
behind-proxy: true
attachment-cache-dir: /var/cache/ntfy/attachments
```

### Authentication

```bash
# Add user
ntfy user add --role=admin admin
ntfy user add phil

# Grant access
ntfy access phil my-alerts rw    # read-write to "my-alerts"
ntfy access phil alerts ro       # read-only to "alerts"

# Use with auth
curl -u phil:password -d "Secret alert" ntfy.yourdomain.com/my-alerts
```

## Priority Levels

| Priority | Emoji | Sound | Use Case |
|----------|-------|-------|----------|
| 1 (min) | — | None | Low-priority logs |
| 2 (low) | — | None | FYI notifications |
| 3 (default) | — | Default | Normal alerts |
| 4 (high) | ⚡ | Persistent | Important warnings |
| 5 (urgent) | 🔴 | Alarm | Critical incidents |

## ntfy vs Alternatives

| Feature | ntfy | Pushover | Gotify | Telegram Bot |
|---------|------|----------|--------|-------------|
| Open Source | Yes (Apache-2.0) | No | Yes (MIT) | N/A |
| Self-hosted | Yes | No | Yes | N/A |
| No signup | Yes | No | N/A | Needs bot token |
| HTTP API | curl-simple | REST | REST | REST |
| Mobile app | iOS + Android | iOS + Android | Android | Telegram |
| Free tier | Unlimited | 10K/mo | Unlimited | Unlimited |
| Attachments | Yes | Yes | No | Yes |
| Actions/Buttons | Yes | No | No | Inline keyboard |
| UnifiedPush | Yes | No | No | No |

## 常见问题

**Q: ntfy.sh 公共服务安全吗？**
A: ntfy.sh 的 topic 名称就是"密码"——任何知道 topic 名的人都能收到通知。对于敏感通知，建议使用长随机 topic 名或自托管并配置认证。

**Q: 消息会被存储多久？**
A: ntfy.sh 公共服务保存消息 12 小时。自托管可以通过 `cache-duration` 配置自定义保留时间。

**Q: 可以用于生产环境的告警吗？**
A: 可以。ntfy 支持与 Grafana、Prometheus Alertmanager、Uptime Kuma 等监控工具集成。通过 webhook 或直接 HTTP 调用即可发送告警通知到手机。

## 来源与致谢

- GitHub: [binwiederhier/ntfy](https://github.com/binwiederhier/ntfy) — 29.7K+ ⭐ | Apache-2.0
- 官网: [ntfy.sh](https://ntfy.sh)

---
Source: https://tokrepo.com/en/workflows/2d5b57ec-34c8-11f1-9bc6-00163e2b0d79
Author: Script Depot