Configuration
Configure your self-hosted server using a YAML config file or command-line flags.
Config File Location
Default locations:
/etc/ntfy/server.yml(Linux)~/.config/ntfy/server.yml(User)
Or specify with --config:
ntfy serve --config /path/to/server.yml
Basic Configuration
# Base URL (required for attachments, web app)
base-url: "https://ntfy.example.com"
# HTTP listener
listen-http: ":80"
# Cache settings
cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "12h"
# Attachment settings
attachment-cache-dir: "/var/cache/ntfy/attachments"
attachment-total-size-limit: "5G"
attachment-file-size-limit: "15M"
attachment-expiry-duration: "3h"
Authentication
Enable Authentication
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
Manage Users
# Add user
ntfy user add --role=admin phil
# List users
ntfy user list
# Delete user
ntfy user del phil
# Change password
ntfy user change-pass phil
Access Control
# Allow user to read/write topic
ntfy access phil mytopic rw
# Allow user to read topic
ntfy access phil alerts ro
# Allow everyone to read topic
ntfy access everyone announcements ro
User Roles
| Role | Description |
|------|-------------|
| admin | Full access to all topics, can manage users |
| user | Access based on ACL rules |
| anonymous | Unauthenticated users |
HTTPS
Direct HTTPS
listen-https: ":443"
key-file: "/path/to/key.pem"
cert-file: "/path/to/cert.pem"
Behind Proxy
listen-http: ":80"
behind-proxy: true
Rate Limiting
# Per-visitor limits
visitor-request-limit-burst: 60
visitor-request-limit-replenish: "5s"
visitor-request-limit-exempt-hosts: "localhost"
# Message limits
visitor-message-daily-limit: 0 # 0 = unlimited
visitor-email-limit-burst: 16
visitor-email-limit-replenish: "1h"
# Attachment limits
visitor-attachment-total-size-limit: "100M"
visitor-attachment-daily-bandwidth-limit: "500M"
Message Settings
# Message cache
cache-duration: "12h"
cache-startup-queries: "pragma journal_mode = WAL; pragma synchronous = normal"
# Message limits
message-size-limit: "4K"
message-delay-limit: "3d"
Firebase (Push Notifications)
For Android app push notifications:
firebase-key-file: "/path/to/firebase-key.json"
Web App
# Enable web app
web-root: "/"
# Disable web app
web-root: "disable"
Logging
log-level: "info" # trace, debug, info, warn, error
log-format: "text" # text or json
log-file: "/var/log/ntfy/ntfy.log"
Metrics
# Enable Prometheus metrics
enable-metrics: true
metrics-listen-http: ":9090"
SMTP (Email Notifications)
# Incoming email
smtp-server-listen: ":25"
smtp-server-domain: "ntfy.example.com"
smtp-server-addr-prefix: ""
# Outgoing email
smtp-sender-addr: "smtp.example.com:587"
smtp-sender-user: "ntfy@example.com"
smtp-sender-pass: "password"
smtp-sender-from: "ntfy@example.com"
WebSocket
keepalive-interval: "45s"
manager-interval: "1m"
Full Example
# Server settings
base-url: "https://ntfy.example.com"
listen-http: ":80"
behind-proxy: true
# Cache
cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "24h"
# Attachments
attachment-cache-dir: "/var/cache/ntfy/attachments"
attachment-total-size-limit: "10G"
attachment-file-size-limit: "50M"
attachment-expiry-duration: "6h"
# Authentication
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
# Rate limiting
visitor-request-limit-burst: 60
visitor-request-limit-replenish: "5s"
visitor-attachment-total-size-limit: "100M"
# Logging
log-level: "info"
log-file: "/var/log/ntfy/ntfy.log"
# Metrics
enable-metrics: true
metrics-listen-http: ":9090"
Environment Variables
All config options can be set via environment variables:
NTFY_BASE_URL="https://ntfy.example.com"
NTFY_LISTEN_HTTP=":80"
NTFY_CACHE_FILE="/var/cache/ntfy/cache.db"
Pattern: NTFY_<OPTION> where option is uppercase with underscores.
Command Line Flags
All options can also be passed as flags:
ntfy serve \
--base-url="https://ntfy.example.com" \
--listen-http=":80" \
--cache-file="/var/cache/ntfy/cache.db"
Validation
Check your configuration:
ntfy serve --help
This displays all available options with descriptions and defaults.