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

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)

# 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

# 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

# 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

// 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

#!/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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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