Installation

NotifyHero can be self-hosted for complete control over your notification infrastructure. This guide covers various installation methods.

Note: Self-hosting gives you full control but requires managing your own infrastructure. For most users, the hosted app.notifyhero.com service is recommended.

Docker (Recommended)

The easiest way to run your own server:

docker run -p 80:80 ghcr.io/badgeherocorp/notifyhero serve

With persistent storage:

docker run -d \
  -v /var/cache/notifyhero:/var/cache/ntfy \
  -v /etc/notifyhero:/etc/ntfy \
  -p 80:80 \
  --name notifyhero \
  ghcr.io/badgeherocorp/notifyhero serve

Docker Compose

version: "3"
services:
  notifyhero:
    image: ghcr.io/badgeherocorp/notifyhero
    container_name: notifyhero
    command: serve
    volumes:
      - ./cache:/var/cache/ntfy
      - ./etc:/etc/ntfy
    ports:
      - "80:80"
    restart: unless-stopped

Building from Source

For advanced users who want to build from source:

# Clone the repository
git clone https://github.com/badgeherocorp/notifyhero.git
cd notifyhero

# Build
make build

# Run
./ntfy serve

See the Development page for more details.

Configuration

Create a config file at /etc/notifyhero/server.yml:

base-url: "https://ntfy.example.com"
listen-http: ":80"
cache-file: "/var/cache/ntfy/cache.db"
attachment-cache-dir: "/var/cache/ntfy/attachments"

See the Configuration page for all options.

Reverse Proxy Setup

nginx

server {
    listen 443 ssl;
    server_name ntfy.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:2586;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # SSE support
        proxy_buffering off;
        proxy_cache off;
    }
}

Traefik

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.ntfy.rule=Host(`ntfy.example.com`)"
  - "traefik.http.routers.ntfy.tls.certresolver=letsencrypt"
  - "traefik.http.services.ntfy.loadbalancer.server.port=80"

Caddy

ntfy.example.com {
    reverse_proxy localhost:2586
}

Systemd Service

Create /etc/systemd/system/ntfy.service:

[Unit]
Description=ntfy server
After=network.target

[Service]
ExecStart=/usr/local/bin/ntfy serve
Restart=always
User=ntfy
Group=ntfy

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable ntfy
sudo systemctl start ntfy

Verification

Test your installation:

# Publish a test message
curl -d "Test message" http://localhost/test

# Subscribe
curl http://localhost/test/json?poll=1