Skip to content

Ntfy — Runbook

Routine Tasks

Send a test notification

curl -d "Test notification from homelab" https://ntfy.eva-00.network/test

Subscribe to the test topic on your phone to verify delivery.

Check health

curl http://192.168.1.119:2586/v1/health

Adding topics

No configuration is needed. Topics are created on the fly — just publish to a new topic name:

curl -d "Hello from new topic" https://ntfy.eva-00.network/my-new-topic

Then subscribe to my-new-topic in the Ntfy app or via any HTTP client.

Current topics

Topic Publisher Purpose
mediabot MediaManager Download completion notifications

Logs

Log Contents Location Loki query Format
Application Published messages, subscription events, upstream relay, errors Docker (LXC 119) stdout {job="infra-apps", container="ntfy"} Plain text

Notes: - SSH fallback: ssh [email protected] "pct exec 119 -- docker logs ntfy"

Troubleshooting

Notifications not arriving on phone

  1. Check health: curl http://192.168.1.119:2586/v1/health
  2. Verify the container is running: ssh [email protected] "pct exec 119 -- docker ps -f name=ntfy"
  3. Test publishing from the server itself: curl -d "debug test" http://192.168.1.119:2586/test
  4. Check logs for errors: {container="ntfy"} |= "error" in Grafana Loki
  5. Confirm the phone app is pointed at https://ntfy.eva-00.network (not the default ntfy.sh)
  6. Confirm you are subscribed to the correct topic name (case-sensitive)

iOS push notifications not working

iOS requires the upstream-base-url setting to relay through ntfy.sh (Apple Push Notification service only accepts connections from ntfy.sh servers).

  1. Verify upstream-base-url: https://ntfy.sh is set in services/ntfy/server.yml
  2. Check logs for upstream connection errors: {container="ntfy"} |= "upstream"
  3. Ensure the container can reach https://ntfy.sh (no firewall blocking outbound HTTPS)
  4. Restart the container and check again: ssh [email protected] "pct exec 119 -- docker restart ntfy"

Messages published but not showing in app

  1. Verify the topic name matches exactly (topic names are case-sensitive)
  2. Check if the app has background refresh enabled (iOS Settings → Ntfy → Background App Refresh)
  3. Try opening the app manually — cached messages should appear
  4. Publish with a title for easier visibility: curl -H "Title: Test" -d "Body here" https://ntfy.eva-00.network/mediabot