Sanitized mirror from private repository - 2026-03-21 06:37:51 UTC

2026-03-21 06:37:51 +00:00
commit f273b940ad
1235 changed files with 306105 additions and 0 deletions
--- a/docs/services/admin/ntfy-notification-system.md
+++ b/docs/services/admin/ntfy-notification-system.md
@@ -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
--- a/docs/services/admin/ntfy-quick-reference.md
+++ b/docs/services/admin/ntfy-quick-reference.md
@@ -0,0 +1,247 @@
+# 📱 NTFY Quick Reference
+
+*Quick reference guide for NTFY notification system usage*
+
+## Basic Usage
+
+### Send Simple Message
+```bash
+curl -d "Hello World" https://ntfy.vish.gg/topic-name
+```
+
+### Send with Authentication
+```bash
+curl -u username:password -d "Authenticated message" https://ntfy.vish.gg/topic-name
+```
+
+### Send with Title
+```bash
+curl -H "Title: Alert Title" -d "Message body" https://ntfy.vish.gg/topic-name
+```
+
+## Priority Levels
+
+### Set Message Priority
+```bash
+# Low priority (1-2)
+curl -H "Priority: 1" -d "Debug message" https://ntfy.vish.gg/topic-name
+
+# Normal priority (3) - default
+curl -d "Normal message" https://ntfy.vish.gg/topic-name
+
+# High priority (4-5)
+curl -H "Priority: 5" -d "CRITICAL ALERT" https://ntfy.vish.gg/topic-name
+```
+
+### Priority Reference
+- **1 (Min)**: 🔕 Silent, debugging
+- **2 (Low)**: 🔔 Quiet notification
+- **3 (Default)**: 🔔 Normal notification
+- **4 (High)**: 📢 Important, loud
+- **5 (Max)**: 🚨 Critical, emergency
+
+## Tags and Emojis
+
+### Common Tags
+```bash
+# Success notifications
+curl -H "Tags: white_check_mark,success" -d "Backup completed" https://ntfy.vish.gg/backups
+
+# Warning notifications
+curl -H "Tags: warning,yellow_circle" -d "High CPU usage" https://ntfy.vish.gg/alerts
+
+# Error notifications
+curl -H "Tags: x,red_circle" -d "Service failed" https://ntfy.vish.gg/alerts
+
+# Info notifications
+curl -H "Tags: information_source,blue_circle" -d "System update" https://ntfy.vish.gg/info
+```
+
+### Popular Emoji Tags
+- **✅ Success**: `white_check_mark`, `heavy_check_mark`
+- **⚠️ Warning**: `warning`, `yellow_circle`
+- **❌ Error**: `x`, `red_circle`, `no_entry`
+- **🔥 Critical**: `fire`, `rotating_light`
+- **📊 Monitoring**: `bar_chart`, `chart_with_upwards_trend`
+- **🔧 Maintenance**: `wrench`, `hammer_and_wrench`
+- **💾 Backup**: `floppy_disk`, `package`
+
+## Actions and Buttons
+
+### Add Action Buttons
+```bash
+curl -H "Actions: view, Open Dashboard, https://grafana.local" \
+     -d "Check system metrics" \
+     https://ntfy.vish.gg/monitoring
+```
+
+### Multiple Actions
+```bash
+curl -H "Actions: view, Dashboard, https://grafana.local; http, Restart, https://portainer.local/restart" \
+     -d "Service needs attention" \
+     https://ntfy.vish.gg/alerts
+```
+
+## Common Homelab Topics
+
+### System Topics
+- **`homelab-alerts`** - Critical system alerts
+- **`homelab-monitoring`** - Monitoring notifications
+- **`homelab-backups`** - Backup status
+- **`homelab-updates`** - System updates
+- **`homelab-security`** - Security alerts
+
+### Service Topics
+- **`plex-alerts`** - Plex Media Server
+- **`arr-suite`** - Sonarr/Radarr/Lidarr
+- **`gitea-notifications`** - Git events
+- **`portainer-alerts`** - Container alerts
+
+## Authentication
+
+### User Credentials
+```bash
+# Set credentials for session
+export NTFY_USER="monitoring"
+export NTFY_PASS="REDACTED_PASSWORD"
+
+# Use in curl commands
+curl -u "$NTFY_USER:$NTFY_PASS" -d "Message" https://ntfy.vish.gg/topic
+```
+
+### Topic Permissions
+- **Read (r)**: Subscribe and receive messages
+- **Write (w)**: Publish messages to topic
+- **Read-Write (rw)**: Full access to topic
+
+## Scheduling and Delays
+
+### Delayed Messages
+```bash
+# Send in 30 minutes
+curl -H "At: $(date -d '+30 minutes' '+%Y-%m-%dT%H:%M:%S')" \
+     -d "Scheduled maintenance reminder" \
+     https://ntfy.vish.gg/maintenance
+```
+
+### Recurring Reminders
+```bash
+# Daily backup reminder (use with cron)
+0 9 * * * curl -d "Daily backup check" https://ntfy.vish.gg/reminders
+```
+
+## Monitoring Integration Examples
+
+### Prometheus AlertManager
+```bash
+# In alertmanager webhook
+curl -u alerts:password \
+     -H "Title: {{ .GroupLabels.alertname }}" \
+     -H "Priority: 4" \
+     -H "Tags: fire,prometheus" \
+     -d "{{ range .Alerts }}{{ .Annotations.summary }}{{ end }}" \
+     https://ntfy.vish.gg/REDACTED_NTFY_TOPIC
+```
+
+### Uptime Kuma
+```bash
+# Service down notification
+curl -u monitoring:password \
+     -H "Title: Service Down: Plex" \
+     -H "Priority: 5" \
+     -H "Tags: rotating_light,down" \
+     -d "Plex Media Server is not responding" \
+     https://ntfy.vish.gg/homelab-monitoring
+```
+
+### Backup Scripts
+```bash
+#!/bin/bash
+# backup-notify.sh
+if [ "$1" = "success" ]; then
+    curl -u backup:password \
+         -H "Title: Backup Completed" \
+         -H "Tags: white_check_mark,backup" \
+         -d "Daily backup completed successfully at $(date)" \
+         https://ntfy.vish.gg/homelab-backups
+else
+    curl -u backup:password \
+         -H "Title: Backup Failed" \
+         -H "Priority: 4" \
+         -H "Tags: x,backup,warning" \
+         -d "Daily backup failed: $2" \
+         https://ntfy.vish.gg/homelab-backups
+fi
+```
+
+## Client Subscription
+
+### Command Line
+```bash
+# Subscribe to topic
+ntfy subscribe https://ntfy.vish.gg/REDACTED_NTFY_TOPIC
+
+# Subscribe with authentication
+ntfy subscribe --user monitoring:password https://ntfy.vish.gg/REDACTED_NTFY_TOPIC
+
+# Subscribe to multiple topics
+ntfy subscribe https://ntfy.vish.gg/REDACTED_NTFY_TOPIC,homelab-backups
+```
+
+### Mobile Apps
+1. **Install NTFY app** (Android/iOS)
+2. **Add server**: `https://ntfy.vish.gg`
+3. **Subscribe to topics**: Enter topic names
+4. **Set credentials**: Username/password if required
+
+## Troubleshooting
+
+### Test Connectivity
+```bash
+# Basic connectivity test
+curl -I https://ntfy.vish.gg
+
+# Test topic publishing
+curl -d "Test message" https://ntfy.vish.gg/test
+
+# Test authentication
+curl -u username:password -d "Auth test" https://ntfy.vish.gg/test
+```
+
+### Debug Message Delivery
+```bash
+# Check message history
+curl -s https://ntfy.vish.gg/topic-name/json
+
+# Monitor real-time messages
+curl -N -H "Accept: text/event-stream" https://ntfy.vish.gg/topic-name/sse
+```
+
+### Common Error Codes
+- **401 Unauthorized**: Invalid credentials
+- **403 Forbidden**: No permission for topic
+- **404 Not Found**: Topic doesn't exist
+- **429 Too Many Requests**: Rate limit exceeded
+
+## Best Practices
+
+### Topic Naming
+- Use **kebab-case**: `homelab-alerts`
+- Be **descriptive**: `plex-transcoding-alerts`
+- Group by **service**: `arr-suite-downloads`
+- Include **environment**: `prod-database-alerts`
+
+### Message Content
+- **Clear titles**: Describe the issue/event
+- **Actionable messages**: Include next steps
+- **Consistent formatting**: Use templates
+- **Appropriate priority**: Don't overuse high priority
+
+### Security
+- **Unique credentials**: Different users for different services
+- **Minimal permissions**: Grant only necessary access
+- **Regular rotation**: Change passwords periodically
+- **Monitor usage**: Track message patterns
+
+---
+**Quick Access**: `https://ntfy.vish.gg` | **Admin**: monitoring:password | **Critical**: homelab-alerts