130 lines
2.6 KiB
Markdown
130 lines
2.6 KiB
Markdown
# ntfy - Simple Notification Service
|
|
|
|
Deploys [ntfy](https://ntfy.sh/) - a simple HTTP-based pub-sub notification service.
|
|
|
|
## Security Model
|
|
|
|
**Secure by default:**
|
|
- `auth-default-access: deny-all` - No anonymous access
|
|
- `enable-signup: false` - No public registration
|
|
- `enable-login: true` - Authentication required
|
|
- `enable-reservations: true` - Only authenticated users can reserve topics
|
|
|
|
All notifications require authentication to send or receive.
|
|
|
|
## Configuration
|
|
|
|
### Required Variables
|
|
|
|
Set in inventory or vault:
|
|
|
|
```yaml
|
|
ntfy_admin_password: "your-secure-password-here" # Min 12 chars
|
|
```
|
|
|
|
### Optional Variables
|
|
|
|
See [defaults/main.yml](defaults/main.yml) for all configuration options.
|
|
|
|
Key settings:
|
|
|
|
```yaml
|
|
ntfy_version: latest
|
|
ntfy_port: 8080
|
|
ntfy_base_url: http://localhost:8080
|
|
ntfy_admin_user: admin
|
|
|
|
# Nginx reverse proxy
|
|
ntfy_nginx_enabled: false
|
|
ntfy_nginx_hostname: ntfy.nas.local
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Managing Users
|
|
|
|
List users:
|
|
```bash
|
|
podman exec ntfy ntfy user list
|
|
```
|
|
|
|
Add user:
|
|
```bash
|
|
podman exec ntfy ntfy user add <username>
|
|
```
|
|
|
|
Change password:
|
|
```bash
|
|
podman exec -i ntfy ntfy user change-pass <username>
|
|
```
|
|
|
|
Remove user:
|
|
```bash
|
|
podman exec ntfy ntfy user remove <username>
|
|
```
|
|
|
|
### Managing Topic Access
|
|
|
|
Grant access to topic:
|
|
```bash
|
|
podman exec ntfy ntfy access <username> <topic> <permission>
|
|
```
|
|
|
|
Permissions: `read-write`, `read-only`, `write-only`, `deny`
|
|
|
|
Example:
|
|
```bash
|
|
# Allow user to publish and subscribe to "alerts" topic
|
|
podman exec ntfy ntfy access alice alerts read-write
|
|
|
|
# Allow user to only publish to "monitoring" topic
|
|
podman exec ntfy ntfy access bob monitoring write-only
|
|
```
|
|
|
|
List access control:
|
|
```bash
|
|
podman exec ntfy ntfy access
|
|
```
|
|
|
|
### Publishing Notifications
|
|
|
|
Using curl with authentication:
|
|
```bash
|
|
curl -u admin:password -d "Backup completed" http://localhost:8080/backups
|
|
```
|
|
|
|
Using ntfy CLI:
|
|
```bash
|
|
ntfy publish --token <access-token> ntfy.nas.local mytopic "Hello World"
|
|
```
|
|
|
|
### Subscribing to Notifications
|
|
|
|
Web UI: https://ntfy.nas.local (if nginx enabled)
|
|
|
|
CLI:
|
|
```bash
|
|
ntfy subscribe --token <access-token> ntfy.nas.local mytopic
|
|
```
|
|
|
|
Mobile apps available for iOS and Android.
|
|
|
|
## Architecture
|
|
|
|
- **Container**: Podman-based deployment
|
|
- **Storage**: Persistent cache and user database
|
|
- **Networking**: Localhost binding by default
|
|
- **Reverse Proxy**: Optional nginx with HTTPS
|
|
|
|
## File Locations
|
|
|
|
- Configuration: `{{ podman_projects_dir }}/ntfy/server.yml`
|
|
- User database: `{{ ntfy_data_dir }}/user.db`
|
|
- Cache database: `{{ ntfy_cache_dir }}/cache.db`
|
|
- Attachments: `{{ ntfy_cache_dir }}/attachments/`
|
|
|
|
## Dependencies
|
|
|
|
- podman
|
|
- nginx (if `ntfy_nginx_enabled: true`)
|