Sanitized mirror from private repository - 2026-03-30 00:10:29 UTC
This commit is contained in:
Gitea Mirror Bot
355
docs/services/admin/ntfy-notification-system.md
Normal file
355
docs/services/admin/ntfy-notification-system.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# 📱 NTFY Notification System
|
||||
|
||||
*Centralized push notification system for homelab monitoring and alerts*
|
||||
|
||||
## Overview
|
||||
NTFY provides a simple, reliable push notification service for the homelab infrastructure, enabling real-time alerts and notifications across all monitoring systems and services.
|
||||
|
||||
## System Architecture
|
||||
|
||||
### Deployment Locations
|
||||
- **Primary**: `homelab_vm/ntfy.yaml`
|
||||
- **Status**: ✅ Active
|
||||
- **Access**: `https://ntfy.vish.gg`
|
||||
|
||||
### Container Configuration
|
||||
```yaml
|
||||
services:
|
||||
ntfy:
|
||||
image: binwiederhier/ntfy:latest
|
||||
container_name: ntfy-homelab
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- TZ=America/New_York
|
||||
volumes:
|
||||
- ntfy-data:/var/lib/ntfy
|
||||
- ./ntfy.yml:/etc/ntfy/server.yml:ro
|
||||
ports:
|
||||
- "8080:80"
|
||||
command: serve
|
||||
```
|
||||
|
||||
## Configuration Management
|
||||
|
||||
### Server Configuration (`ntfy.yml`)
|
||||
```yaml
|
||||
# Base URL and listening
|
||||
base-url: "https://ntfy.vish.gg"
|
||||
listen-http: ":80"
|
||||
|
||||
# Authentication and access control
|
||||
auth-default-access: "deny-all"
|
||||
auth-file: "/var/lib/ntfy/user.db"
|
||||
|
||||
# Rate limiting
|
||||
visitor-request-limit-burst: 60
|
||||
visitor-request-limit-replenish: "5s"
|
||||
|
||||
# Message retention
|
||||
cache-file: "/var/lib/ntfy/cache.db"
|
||||
cache-duration: "12h"
|
||||
keepalive-interval: "45s"
|
||||
|
||||
# Attachments
|
||||
attachment-cache-dir: "/var/lib/ntfy/attachments"
|
||||
attachment-total-size-limit: "5G"
|
||||
attachment-file-size-limit: "15M"
|
||||
|
||||
# Web app
|
||||
enable-signup: false
|
||||
enable-login: true
|
||||
enable-reservations: true
|
||||
```
|
||||
|
||||
### User Management
|
||||
```bash
|
||||
# Create admin user
|
||||
docker exec ntfy-homelab ntfy user add --role=admin admin
|
||||
|
||||
# Create service users
|
||||
docker exec ntfy-homelab ntfy user add monitoring
|
||||
docker exec ntfy-homelab ntfy user add alerts
|
||||
docker exec ntfy-homelab ntfy user add backup-system
|
||||
|
||||
# Grant topic permissions
|
||||
docker exec ntfy-homelab ntfy access monitoring homelab-monitoring rw
|
||||
docker exec ntfy-homelab ntfy access alerts homelab-alerts rw
|
||||
docker exec ntfy-homelab ntfy access backup-system homelab-backups rw
|
||||
```
|
||||
|
||||
## Topic Organization
|
||||
|
||||
### System Topics
|
||||
- **`homelab-alerts`** - Critical system alerts
|
||||
- **`homelab-monitoring`** - Monitoring notifications
|
||||
- **`homelab-backups`** - Backup status notifications
|
||||
- **`homelab-updates`** - System update notifications
|
||||
- **`homelab-security`** - Security-related alerts
|
||||
|
||||
### Service-Specific Topics
|
||||
- **`plex-notifications`** - Plex Media Server alerts
|
||||
- **`arr-suite-alerts`** - Sonarr/Radarr/Lidarr notifications
|
||||
- **`gitea-notifications`** - Git repository notifications
|
||||
- **`portainer-alerts`** - Container management alerts
|
||||
|
||||
### Personal Topics
|
||||
- **`admin-alerts`** - Administrator-specific notifications
|
||||
- **`maintenance-reminders`** - Scheduled maintenance reminders
|
||||
- **`capacity-warnings`** - Storage and resource warnings
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Prometheus AlertManager
|
||||
```yaml
|
||||
# alertmanager.yml
|
||||
route:
|
||||
group_by: ['alertname']
|
||||
group_wait: 10s
|
||||
group_interval: 10s
|
||||
repeat_interval: 1h
|
||||
receiver: 'ntfy-alerts'
|
||||
|
||||
receivers:
|
||||
- name: 'ntfy-alerts'
|
||||
webhook_configs:
|
||||
- url: 'https://ntfy.vish.gg/REDACTED_NTFY_TOPIC'
|
||||
http_config:
|
||||
basic_auth:
|
||||
username: 'alerts'
|
||||
password: "REDACTED_PASSWORD"
|
||||
```
|
||||
|
||||
### Uptime Kuma Integration
|
||||
```javascript
|
||||
// Custom notification webhook
|
||||
{
|
||||
"url": "https://ntfy.vish.gg/homelab-monitoring",
|
||||
"method": "POST",
|
||||
"headers": {
|
||||
"Authorization": "Basic bW9uaXRvcmluZzpwYXNzd29yZA=="
|
||||
},
|
||||
"body": {
|
||||
"topic": "homelab-monitoring",
|
||||
"title": "Service Alert: {{NAME}}",
|
||||
"message": "{{STATUS}}: {{MSG}}",
|
||||
"priority": "{{PRIORITY}}",
|
||||
"tags": ["{{STATUS_EMOJI}}", "monitoring"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Backup System Integration
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# backup-notification.sh
|
||||
NTFY_URL="https://ntfy.vish.gg/homelab-backups"
|
||||
NTFY_AUTH="backup-system:backup-password"
|
||||
|
||||
notify_backup_status() {
|
||||
local status=$1
|
||||
local message=$2
|
||||
local priority=${3:-3}
|
||||
|
||||
curl -u "$NTFY_AUTH" \
|
||||
-H "Title: Backup Status: $status" \
|
||||
-H "Priority: $priority" \
|
||||
-H "Tags: backup,$(echo $status | tr '[:upper:]' '[:lower:]')" \
|
||||
-d "$message" \
|
||||
"$NTFY_URL"
|
||||
}
|
||||
|
||||
# Usage examples
|
||||
notify_backup_status "SUCCESS" "Daily backup completed successfully" 3
|
||||
notify_backup_status "FAILED" "Backup failed: disk full" 5
|
||||
```
|
||||
|
||||
### Home Assistant Integration
|
||||
```yaml
|
||||
# configuration.yaml
|
||||
notify:
|
||||
- name: ntfy_homelab
|
||||
platform: rest
|
||||
resource: https://ntfy.vish.gg/REDACTED_NTFY_TOPIC
|
||||
method: POST_JSON
|
||||
authentication: basic
|
||||
username: !secret ntfy_username
|
||||
password: "REDACTED_PASSWORD" ntfy_password
|
||||
title_param_name: title
|
||||
message_param_name: message
|
||||
data:
|
||||
priority: 3
|
||||
tags: ["home-assistant"]
|
||||
```
|
||||
|
||||
## Client Applications
|
||||
|
||||
### Mobile Apps
|
||||
- **Android**: NTFY app from F-Droid or Google Play
|
||||
- **iOS**: NTFY app from App Store
|
||||
- **Configuration**: Add server `https://ntfy.vish.gg`
|
||||
|
||||
### Desktop Clients
|
||||
- **Linux**: `ntfy subscribe` command-line client
|
||||
- **Windows**: PowerShell scripts with curl
|
||||
- **macOS**: Terminal with curl or dedicated apps
|
||||
|
||||
### Web Interface
|
||||
- **URL**: `https://ntfy.vish.gg`
|
||||
- **Features**: Subscribe to topics, view message history
|
||||
- **Authentication**: Username/password login
|
||||
|
||||
## Message Formatting
|
||||
|
||||
### Priority Levels
|
||||
- **1 (Min)**: Debugging, low-priority info
|
||||
- **2 (Low)**: Routine notifications
|
||||
- **3 (Default)**: Normal notifications
|
||||
- **4 (High)**: Important alerts
|
||||
- **5 (Max)**: Critical emergencies
|
||||
|
||||
### Tags and Emojis
|
||||
```bash
|
||||
# Common tags
|
||||
curl -d "Backup completed successfully" \
|
||||
-H "Tags: white_check_mark,backup" \
|
||||
https://ntfy.vish.gg/homelab-backups
|
||||
|
||||
# Priority with emoji
|
||||
curl -d "Critical: Service down!" \
|
||||
-H "Priority: 5" \
|
||||
-H "Tags: rotating_light,critical" \
|
||||
https://ntfy.vish.gg/REDACTED_NTFY_TOPIC
|
||||
```
|
||||
|
||||
### Rich Formatting
|
||||
```bash
|
||||
# With title and actions
|
||||
curl -X POST https://ntfy.vish.gg/REDACTED_NTFY_TOPIC \
|
||||
-H "Title: Service Alert" \
|
||||
-H "Priority: 4" \
|
||||
-H "Tags: warning" \
|
||||
-H "Actions: view, Open Dashboard, https://grafana.local" \
|
||||
-d "Plex Media Server is experiencing high CPU usage"
|
||||
```
|
||||
|
||||
## Monitoring & Maintenance
|
||||
|
||||
### Health Monitoring
|
||||
- **Uptime Kuma**: Monitor NTFY service availability
|
||||
- **Prometheus**: Collect NTFY metrics (if enabled)
|
||||
- **Log monitoring**: Track message delivery rates
|
||||
|
||||
### Performance Metrics
|
||||
- **Message throughput**: Messages per minute/hour
|
||||
- **Delivery success rate**: Successful vs failed deliveries
|
||||
- **Client connections**: Active subscriber count
|
||||
- **Storage usage**: Cache and attachment storage
|
||||
|
||||
### Maintenance Tasks
|
||||
```bash
|
||||
# Database maintenance
|
||||
docker exec ntfy-homelab ntfy user list
|
||||
docker exec ntfy-homelab ntfy access list
|
||||
|
||||
# Clear old messages
|
||||
docker exec ntfy-homelab ntfy publish --clear homelab-alerts
|
||||
|
||||
# Backup user database
|
||||
docker exec ntfy-homelab cp /var/lib/ntfy/user.db /backup/ntfy-users-$(date +%Y%m%d).db
|
||||
```
|
||||
|
||||
## Security Configuration
|
||||
|
||||
### Authentication
|
||||
- **User accounts**: Individual accounts for each service
|
||||
- **Topic permissions**: Granular read/write access control
|
||||
- **Password policies**: Strong passwords required
|
||||
- **Session management**: Automatic session expiration
|
||||
|
||||
### Network Security
|
||||
- **HTTPS only**: All communications encrypted
|
||||
- **Reverse proxy**: Behind Nginx Proxy Manager
|
||||
- **Rate limiting**: Prevent abuse and spam
|
||||
- **IP restrictions**: Limit access to known networks (optional)
|
||||
|
||||
### Access Control
|
||||
```bash
|
||||
# Topic-level permissions
|
||||
docker exec ntfy-homelab ntfy access grant monitoring homelab-monitoring rw
|
||||
docker exec ntfy-homelab ntfy access grant alerts homelab-alerts rw
|
||||
docker exec ntfy-homelab ntfy access revoke user topic-name
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Message Delivery Failures
|
||||
```bash
|
||||
# Check service status
|
||||
docker logs ntfy-homelab
|
||||
|
||||
# Test message delivery
|
||||
curl -d "Test message" https://ntfy.vish.gg/test-topic
|
||||
|
||||
# Verify authentication
|
||||
curl -u username:password -d "Auth test" https://ntfy.vish.gg/test-topic
|
||||
```
|
||||
|
||||
#### Client Connection Issues
|
||||
```bash
|
||||
# Check network connectivity
|
||||
curl -I https://ntfy.vish.gg
|
||||
|
||||
# Test WebSocket connection
|
||||
curl -N -H "Accept: text/event-stream" https://ntfy.vish.gg/test-topic/sse
|
||||
```
|
||||
|
||||
#### Performance Issues
|
||||
```bash
|
||||
# Monitor resource usage
|
||||
docker stats ntfy-homelab
|
||||
|
||||
# Check database size
|
||||
docker exec ntfy-homelab du -sh /var/lib/ntfy/
|
||||
|
||||
# Clear cache if needed
|
||||
docker exec ntfy-homelab rm -f /var/lib/ntfy/cache.db
|
||||
```
|
||||
|
||||
## Backup and Recovery
|
||||
|
||||
### Configuration Backup
|
||||
```bash
|
||||
# Backup configuration and data
|
||||
docker exec ntfy-homelab tar -czf /backup/ntfy-backup-$(date +%Y%m%d).tar.gz \
|
||||
/etc/ntfy/server.yml \
|
||||
/var/lib/ntfy/user.db \
|
||||
/var/lib/ntfy/cache.db
|
||||
```
|
||||
|
||||
### Disaster Recovery
|
||||
```bash
|
||||
# Restore from backup
|
||||
docker exec ntfy-homelab tar -xzf /backup/ntfy-backup-YYYYMMDD.tar.gz -C /
|
||||
|
||||
# Restart service
|
||||
docker restart ntfy-homelab
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Features
|
||||
- **Message encryption**: End-to-end encryption for sensitive alerts
|
||||
- **Message scheduling**: Delayed message delivery
|
||||
- **Advanced filtering**: Client-side message filtering
|
||||
- **Integration expansion**: More service integrations
|
||||
|
||||
### Scaling Considerations
|
||||
- **High availability**: Multi-instance deployment
|
||||
- **Load balancing**: Distribute client connections
|
||||
- **Database optimization**: Performance tuning for high volume
|
||||
- **Caching strategy**: Improve message delivery performance
|
||||
|
||||
---
|
||||
**Status**: ✅ NTFY notification system operational with comprehensive monitoring integration
|
||||
Reference in New Issue
Block a user