Skip to content

ntfy

Docker Compose deployment guide for ntfy on Ubuntu.

ntfy is a lightweight self-hosted notification service that allows applications, scripts, and monitoring tools to send push notifications to your phone, desktop, or web browser.

I use ntfy throughout my homelab for:

  • Docker image update notifications (DIUN)
  • Change Detection alerts
  • Mind reminders and notifications
  • Backup notifications
  • General system alerts

Official project:

Create the Project

Create a directory for ntfy:

/opt/docker/ntfy

Move into it:

cd /opt/docker/ntfy

Create the Docker Compose File

Create:

/opt/docker/ntfy/docker-compose.yml

Paste:

services:
  ntfy:
    image: binwiederhier/ntfy:latest
    container_name: ntfy

    ports:
      - "6741:80"

    volumes:
      - ./cache:/var/cache/ntfy

    restart: unless-stopped

Start ntfy

Start the container:

docker compose up -d

Check the logs:

docker logs -f ntfy

Access the Web Interface

Open:

http://SERVER-IP:6741

Example:

http://192.168.1.100:6741

You should see the ntfy web interface.

Test a Notification

Send a test notification:

curl -d "Hello from ntfy" http://SERVER-IP:6741/test

If you have subscribed to the topic test, the notification should appear immediately.

Install the Mobile App

Install the ntfy mobile application:

Android

Available from:

  • Google Play Store
  • F-Droid

iPhone / iPad

Available from:

  • Apple App Store

After installation, subscribe to a topic such as:

test

Any messages sent to that topic will be delivered as push notifications.

Monitoring and Notifications

ntfy works well with many homelab applications, including:

  • DIUN (Docker Image Update Notifier)
  • Change Detection
  • Home Assistant
  • Custom shell scripts
  • Backup jobs
  • UPS monitoring
  • Scheduled reminders

A simple notification can be sent from a script:

curl -d "Backup completed successfully" http://SERVER-IP:6741/backups

Reverse Proxy (Optional)

If you already use a reverse proxy such as Caddy, you may prefer to publish ntfy using a subdomain.

Example:

https://ntfy.example.com

This allows notifications to be received from anywhere without exposing raw ports.

If you are new to reverse proxies, see:

What is a Reverse Proxy?

Advanced Example (Reference Only)

This is the configuration I currently use in my own homelab.

services:
  ntfy:
    image: binwiederhier/ntfy:latest
    container_name: ntfy
    stop_grace_period: 30s

    command:
      - serve
      - --config
      - /etc/ntfy/server.yml

    environment:
      - TZ=America/Santo_Domingo

    volumes:
      - ./cache:/var/cache/ntfy
      - ./auth:/var/lib/ntfy
      - ./config/server.yml:/etc/ntfy/server.yml

    ports:
      - 6741:80

    restart: unless-stopped

This configuration adds:

  • Persistent cache storage
  • User authentication
  • Custom server configuration
  • Timezone configuration
  • Additional security controls

Refer to the official ntfy documentation for advanced configuration options.

Updating ntfy

Pull the latest image:

docker compose pull

Restart the container:

docker compose up -d

Backups

Back up the following folders:

/opt/docker/ntfy/cache
/opt/docker/ntfy/auth
/opt/docker/ntfy/config

These contain your configuration, authentication settings, and cached data.

Final Thoughts

ntfy is one of the simplest and most useful services in a homelab. It allows virtually any application or script to send notifications to your phone in seconds and integrates easily with monitoring, backup, and automation workflows.