ntfy Server Installation Guide

This guide provides instructions for installing the ntfy server on various Linux distributions, as well as other operating systems. ntfy is a simple HTTP-based pub-sub notification service.

Prerequisites

• A Linux system (or another supported OS)
• Root access or sudo privileges
• An internet connection to download binaries and packages

---

1. Manual Installation from Source (Binary Tarballs)

This method works on any Linux distribution that supports the specific architecture of your system.

Step 1: Identify Your Architecture

Run uname -m to check your architecture:

• x86_64 or amd64
• armv7 or armhf
• arm64 (aarch64)
• armv6

Step 2: Download and Extract the Binary

Example for x86_64/amd64:

wget https://github.com/binwiederhier/ntfy/releases/download/v2.28.0/ntfy_2.28.0_linux_amd64.tar.gz
tar zxvf ntfy_2.28.0_linux_amd64.tar.gz

Example for armv7/armhf:

wget https://github.com/binwiederhier/ntfy/releases/download/v2.28.0/ntfy_2.28.0_linux_armv7.tar.gz
tar zxvf ntfy_2.28.0_linux_armv7.tar.gz

Example for arm64:

wget https://github.com/binwiederhier/ntfy/releases/download/v2.28.0/ntfy_2.28.0_linux_arm64.tar.gz
tar zxvf ntfy_2.28.0_linux_arm64.tar.gz

Step 3: Install the Binary and Configuration Files

# Copy the binary to /usr/bin
sudo cp -a <architecture>/ntfy /usr/bin/ntfy

# Create config directory and copy files
sudo mkdir -p /etc/ntfy
sudo cp <architecture>/client/client.yml /etc/ntfy/
sudo cp <architecture>/server/server.yml /etc/ntfy/

Step 4: Start the Server

sudo ntfy serve

---

2. Install as a System Service (Systemd)

If you want the server to start automatically at boot, use systemd.

Prerequisites

• Ensure your OS uses systemd (systemctl --version).
• You must have installed the binary and config files in Step 1 above.

Steps

1. Copy the Service Unit File:

   # Replace <architecture> with your system's architecture (e.g., amd64, armv7)
   sudo mv <architecture>/server/ntfy.service /etc/systemd/system/
   sudo chmod 644 /etc/systemd/system/ntfy.service
   

2. Reload Systemd and Start the Service:

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

3. Verify Status:

   sudo systemctl status ntfy
   

---

3. Install as a System Service (OpenRC)

For systems using OpenRC (e.g., Alpine Linux, Gentoo).

Steps

1. Copy the Service Script:

   # Replace <architecture> with your system's architecture
   sudo mv <architecture>/server/ntfy.openrc /etc/init.d/ntfy
   sudo chmod 755 /etc/init.d/ntfy
   

2. Start the Service:

   sudo rc-service ntfy start
   

3. Add to Default Runlevel (to start at boot):

   sudo rc-update add ntfy default
   

---

4. Installation via Package Repositories

Debian/Ubuntu

Note: As of late 2025, the official repository has moved to archive.ntfy.sh. The old one (heckel.io) is deprecated.

Using APT (Recommended)

# Add keyring
sudo mkdir -p /etc/apt/keyrings
sudo curl -L -o /etc/apt/keyrings/ntfy.gpg https://archive.ntfy.sh/apt/keyring.gpg
sudo apt install apt-transport-https

# Add repository
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/ntfy.gpg] https://archive.ntfy.sh/apt stable main" | sudo tee /etc/apt/sources.list.d/ntfy.list

# Update and Install
sudo apt update
sudo apt install ntfy

Manual .deb Installation

wget https://github.com/binwiederhier/ntfy/releases/download/v2.28.0/ntfy_2.28.0_linux_amd64.deb
sudo dpkg -i ntfy_*.deb
sudo systemctl enable ntfy
sudo systemctl start ntfy

Fedora/RHEL/CentOS

# Install RPM
sudo rpm -ivh https://github.com/binwiederhier/ntfy/releases/download/v2.28.0/ntfy_2.28.0_linux_amd64.rpm

# Enable and Start
sudo systemctl enable ntfy
sudo systemctl start ntfy

Arch Linux

Using AUR Helper (Recommended)

paru -S ntfysh-bin

Manual Installation

curl https://aur.archlinux.org/cgit/aur.git/snapshot/ntfysh-bin.tar.gz | tar xzv
cd ntfysh-bin
makepkg -si

NixOS / Nix

• NixOS Configuration: Add services.ntfy-sh.enable = true; to your /etc/nixos/configuration.nix and run nixos-rebuild switch.
• User Environment: nix-env -iA ntfy-sh

FreeBSD

pkg install go-ntfy

---

5. macOS Installation

macOS supports the CLI (ntfy publish, ntfy subscribe) but does not support the server via official packages.

Manual CLI Installation

curl -L https://github.com/binwiederhier/ntfy/releases/download/v2.28.0/ntfy_2.28.0_darwin_all.tar.gz > ntfy.tar.gz
tar zxvf ntfy.tar.gz
sudo cp -a ntfy_2.28.0_darwin_all/ntfy /usr/local/bin/ntfy
mkdir ~/Library/Application\ Support/ntfy
cp ntfy_2.28.0_darwin_all/client/client.yml ~/Library/Application\ Support/ntfy/client.yml

Note: To run the server on macOS, you must build it manually using Go (see Build Instructions).

---

6. Homebrew Installation

brew install ntfy

This installs the CLI only. Server installation requires manual steps.

---

7. Windows Installation

As a User Program

1. Download the ZIP from GitHub Releases.
2. Extract and place ntfy.exe in your %Path% (e.g., C:\Program Files\).
3. Run commands like:

   ntfy.exe -h
   

As a Windows Service

1. Open an elevated Command Prompt.
2. Create the service:

   sc create ntfy binPath="C:\path\to\ntfy.exe serve" start=auto
   

3. Start the service:

   sc start ntfy
   

---

8. Docker Installation

Basic Usage (No Persistent Cache)

docker run -p 80:80 -it binwiederhier/ntfy serve

With Persistent Cache

docker run \
  -v /var/cache/ntfy:/var/cache/ntfy \
  -p 80:80 \
  -it \
  binwiederhier/ntfy \
  serve \
  --cache-file /var/cache/ntfy/cache.db

With Custom Config (Non-root user)

docker run \
  -v /etc/ntfy:/etc/ntfy \
  -e TZ=UTC \
  -p 80:80 \
  -u UID:GID \
  -it \
  binwiederhier/ntfy \
  serve

Docker Compose Example

version: '3'
services:
  ntfy:
    image: binwiederhier/ntfy
    container_name: ntfy
    command: ["serve"]
    environment:
      - TZ=UTC
    user: "1000:1000" # Replace with your UID/GID
    volumes:
      - /var/cache/ntfy:/var/cache/ntfy
      - /etc/ntfy:/etc/ntfy
    ports:
      - "80:80"
    healthcheck:
      test: ["CMD-SHELL", "wget -q --tries=1 http://localhost:80/v1/health -O - | grep -Eo '\"healthy\"\\s*:\\s*true' || exit 1"]
      interval: 60s
      timeout: 10s
      retries: 3
      start_period: 40s
    restart: unless-stopped
    init: true

---

9. Kubernetes (K8s) Deployment

StatefulSet with Persistent Cache

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: ntfy
spec:
  serviceName: ntfy
  replicas: 1
  selector:
    matchLabels:
      app: ntfy
  template:
    metadata:
      labels:
        app: ntfy
    spec:
      containers:
        - name: ntfy
          image: binwiederhier/ntfy
          args: ["serve", "--cache-file", "/var/cache/ntfy/cache.db"]
          ports:
            - containerPort: 80
              name: http
          volumeMounts:
            - name: config
              mountPath: /etc/ntfy
              readOnly: true
            - name: cache
              mountPath: /var/cache/ntfy
      volumes:
        - name: config
          configMap:
            name: ntfy
        - name: cache
          persistentVolumeClaim:
            claimName: ntfy-cache
---
apiVersion: v1
kind: Service
metadata:
  name: ntfy
spec:
  selector:
    app: ntfy
  ports:
    - port: 80
      targetPort: 80
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: ntfy-cache
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

---

Troubleshooting

• Service Not Starting: Check logs with sudo journalctl -u ntfy (systemd) or sudo rc-service ntfy status (OpenRC).
• Permission Denied: Ensure the binary and config files are owned by root or a specific user if running as non-root.
• Port Already in Use: Change the port in server.yml or Docker run command (-p 8080:80).

---

Configuration Files

• Client Config: /etc/ntfy/client.yml (or ~/.config/ntfy/client.yml for non-root).
• Server Config: /etc/ntfy/server.yml.

Edit these files to customize settings like timezone, max message size, or retention policy.

---

Security Notes

• Always run ntfy as a non-root user in production if possible (configure via user flag in Docker or systemd service).
• Ensure the web UI is accessible only through trusted networks if exposed publicly.
• Regularly update your installation to patch security vulnerabilities.

---

For more details, visit the ntfy GitHub Repository.

Configuration Parameters

After purchasing this application on Esadax, you will be prompted to provide the configuration parameters below. Esadax adds the supplied variables to the deployment so the application can be launched with the configuration it requires.

Parameter	Description
ADMIN_USERNAME	Value supplied to the deployment for ADMIN_USERNAME.
ADMIN_PASSWORD	Value supplied to the deployment for ADMIN_PASSWORD.

Once the values are configured, click Deploy to launch the application. The purchased application will use the supplied configuration values, including credentials such as usernames and passwords when those parameters are provided.