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_64oramd64armv7orarmhfarm64(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
Verify Status:
sudo systemctl status ntfy
Reload Systemd and Start the Service:
sudo systemctl daemon-reload
sudo systemctl enable ntfy
sudo systemctl start ntfy
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
3. Install as a System Service (OpenRC)
For systems using OpenRC (e.g., Alpine Linux, Gentoo).
Steps
Add to Default Runlevel (to start at boot):
sudo rc-update add ntfy default
Start the Service:
sudo rc-service ntfy start
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
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.nixand runnixos-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
- Download the ZIP from GitHub Releases.
- Extract and place
ntfy.exein your%Path%(e.g.,C:\Program Files\).
Run commands like:
ntfy.exe -h
As a Windows Service
- Open an elevated Command Prompt.
Start the service:
sc start ntfy
Create the service:
sc create ntfy binPath="C:\path\to\ntfy.exe serve" start=auto
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) orsudo 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.ymlor Docker run command (-p 8080:80).
Configuration Files
- Client Config:
/etc/ntfy/client.yml(or~/.config/ntfy/client.ymlfor 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
userflag 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.

