ntfy Push Notifications

beginner

ntfy self-hosted push notification server for alerts and updates.

Overview

ntfy is a simple HTTP-based pub-sub notification service that enables real-time push notifications without requiring complex setup or third-party dependencies. Created by Philipp Heckel, ntfy fills the gap between expensive commercial notification services and overly complex self-hosted alternatives by providing a lightweight, open-source solution that works through simple HTTP requests. The service supports both web-based notifications and dedicated mobile apps for iOS and Android, making it accessible across all major platforms. This Docker configuration deploys ntfy as a standalone notification server that handles message publishing, subscription management, and delivery through a single lightweight container. The setup includes persistent storage for caching messages and configuration files, ensuring that subscription topics and message history survive container restarts. The service exposes a web interface for topic management while simultaneously providing REST API endpoints for programmatic access. This stack is ideal for developers building microservices that need reliable notification capabilities, system administrators monitoring infrastructure health, and organizations wanting to replace expensive notification services with a self-hosted alternative. Home lab enthusiasts and privacy-conscious users particularly benefit from ntfy's ability to deliver notifications without routing through external services, maintaining complete control over message data and delivery infrastructure.

Key Features

HTTP-based pub-sub messaging with no client libraries required
Built-in web UI for subscribing to topics and viewing message history
Native mobile apps for iOS and Android with push notification support
Message persistence and caching for offline subscribers
Topic-based access control with authentication and authorization
Support for message attachments, scheduling, and priority levels
Webhook delivery for integrating with external systems
Rate limiting and anti-spam protection for public instances

Common Use Cases

1Infrastructure monitoring alerts from monitoring tools like Prometheus or Nagios
2CI/CD pipeline notifications for build successes, failures, and deployments
3Application error reporting and exception notifications for development teams
4Home automation system alerts for security cameras, sensors, and smart devices
5Personal reminder system for scheduled tasks and calendar events
6Multi-tenant SaaS application notifications without vendor lock-in
7Internal company announcements and team communication broadcasts

Prerequisites

Docker and Docker Compose installed on the host system
At least 512MB RAM available for message caching and web interface
Port 80 available on the host or alternative port configuration
TZ environment variable set to your local timezone
Basic understanding of HTTP REST APIs for publishing messages
Mobile device for testing push notifications (optional but recommended)

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  ntfy: 
3    image: binwiederhier/ntfy:latest
4    container_name: ntfy
5    command: 
6      - serve
7    environment: 
8      - TZ=${TZ}
9    volumes: 
10      - ntfy_cache:/var/cache/ntfy
11      - ntfy_etc:/etc/ntfy
12    ports: 
13      - "80:80"
14    restart: unless-stopped
15    networks: 
16      - ntfy-network
17
18volumes: 
19  ntfy_cache: 
20  ntfy_etc: 
21
22networks: 
23  ntfy-network: 
24    driver: bridge

.env Template

.env

1# ntfy
2TZ=UTC

Usage Notes

1Web UI at http://localhost
2Publish: curl -d 'Message' http://localhost/topic
3Subscribe: curl -s http://localhost/topic/json
4Mobile apps available
5Supports auth and ACLs

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  ntfy:
5    image: binwiederhier/ntfy:latest
6    container_name: ntfy
7    command:
8      - serve
9    environment:
10      - TZ=${TZ}
11    volumes:
12      - ntfy_cache:/var/cache/ntfy
13      - ntfy_etc:/etc/ntfy
14    ports:
15      - "80:80"
16    restart: unless-stopped
17    networks:
18      - ntfy-network
19
20volumes:
21  ntfy_cache:
22  ntfy_etc:
23
24networks:
25  ntfy-network:
26    driver: bridge
27EOF
28
29# 2. Create the .env file
30cat > .env << 'EOF'
31# ntfy
32TZ=UTC
33EOF
34
35# 3. Start the services
36docker compose up -d
37
38# 4. View logs
39docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/ntfy-notifications/run | bash

Troubleshooting

ntfy container fails to start: Check that port 80 is not already in use by another service or modify the port mapping
Messages not persisting between restarts: Verify that ntfy_cache and ntfy_etc volumes are properly mounted and have correct permissions
Cannot publish messages via curl: Ensure the topic name contains only alphanumeric characters and doesn't start with reserved prefixes
Mobile app not receiving notifications: Check that the server URL is accessible from the internet or configure proper firewall rules for local network access
Web interface shows blank page: Clear browser cache and verify the container is fully started by checking logs with docker logs ntfy
High memory usage with many topics: Configure message retention limits and cache size in the ntfy configuration file

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

ntfy

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download