homelab-optimized/docs/services/admin/ntfy-notification-system.md

# 📱 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