Ntfy Push Notification Service¶

ntfy is a simple HTTP-based pub-sub notification service that allows you to send push notifications to your phone or desktop via scripts, cURL, or webhooks.

Service Overview¶

Attribute	Details
Service Name	`ntfy`
Public URL	`https://ntfy.kamitbrains.fr`
Health Check	`https://ntfy.kamitbrains.fr/v1/health`
Docker Image	`binwiederhier/ntfy:v2.11.0`
Internal Port	`80`
Reverse Proxy	Traefik (`websecure` + Let's Encrypt TLS)
Security	CrowdSec ForwardAuth Bouncer
Storage Volumes	`ntfy-cache`, `ntfy-etc`

Quick Start: Sending Push Notifications¶

🔒 Topic Security: Since ntfy topic authorization without login permits public subscription, topics used for system alerts are protected by appending a high-entropy random string (stored in .secrets/ntfy-topic).

1. Publish a Message via cURL¶

curl -d "Disk usage alert on Contabo server" https://ntfy.kamitbrains.fr/$(cat .secrets/ntfy-topic)

2. Publish with Title, Tags, and Priority¶

curl \
  -H "Title: Backup Successful" \
  -H "Tags: white_check_mark,database" \
  -H "Priority: high" \
  -d "Database backup completed successfully in 45 seconds." \
  https://ntfy.kamitbrains.fr/$(cat .secrets/ntfy-topic)

Android / iOS App: Open the official ntfy mobile application, add custom server https://ntfy.kamitbrains.fr, and subscribe to the secret topic configured in .secrets/ntfy-topic.
Web Interface: Open https://ntfy.kamitbrains.fr in any browser to view live topics.

Automated Analytics & Monitoring Push Integrations¶

Umami Web Analytics Push Reports¶

The Umami analytics reporting pipeline uses ntfy push notifications to transmit automated 7-day traffic summaries (pageviews, unique visitors, sessions, average time, bounce rate) directly to subscribers. - Trigger: Ofelia Job Scheduler (0 20 * * * daily, 0 9 * * 1 weekly). - Documentation: Umami Analytics Documentation

Architecture & Docker Compose Configuration¶

The service is managed via Ansible in ansible/roles/ntfy/.

services:
  ntfy:
    image: binwiederhier/ntfy:v2.11.0
    container_name: ntfy
    restart: unless-stopped
    command:
      - serve
    environment:
      - NTFY_BASE_URL=https://ntfy.kamitbrains.fr
      - NTFY_CACHE_FILE=/var/cache/ntfy/cache.db
      - NTFY_BEHIND_PROXY=true
    volumes:
      - ntfy-cache:/var/cache/ntfy
      - ntfy-etc:/etc/ntfy
    networks:
      - traefik-public
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.ntfy.rule=Host(`ntfy.kamitbrains.fr`)"
      - "traefik.http.routers.ntfy.entrypoints=websecure"
      - "traefik.http.routers.ntfy.tls.certresolver=letsencrypt"
      - "traefik.http.routers.ntfy.middlewares=crowdsec-bouncer@file"
      - "traefik.http.services.ntfy.loadbalancer.server.port=80"

Monitoring & Systemd Integration¶

Uptime Kuma: Automatically monitored at https://ntfy.kamitbrains.fr/v1/health.
Systemd Service: Managed via ntfy.service for automatic boot startup.

Secret Topic Rotation Procedure¶

To rotate the secret alert topic name:

Update the secret file .secrets/ntfy-topic with a new pronounceable code:
```
echo "alerts-<new-pronounceable-code>" > .secrets/ntfy-topic
```
Update the CSV entry Ntfy Push Secret Topic in .secrets/passbolt_import_secrets.csv.

Re-run Ansible deployment to seed the new notification topic into Uptime Kuma:

ansible-playbook -i ansible/inventory.yml ansible/site.yml --tags "ntfy,uptime-kuma"

Resubscribe the Ntfy mobile app or subscribers to the new topic name.