How to Self-Host ntfy.sh: Send Linux System Alerts Effortlessly to iOS/Android via Curl

Introduction: The Challenge of Real-Time Infrastructure Monitoring

In the world of system administration and DevOps, staying ahead of infrastructure anomalies is critical. Whether it is a critical server running out of disk space, a failed automated backup, or an unauthorized SSH login attempt, immediate notification can mean the difference between a minor blip and catastrophic downtime. Traditionally, setting up reliable alerting systems involved complex integrations with external APIs, configuring heavy SMTP servers for email alerts, or relying on restrictive, expensive third-party notification services.

Enter ntfy.sh (pronounced notify), an open-source, HTTP-based pub-sub notification service that revolutionizes how we handle system alerts. By leveraging ntfy, you can send push notifications from your Linux terminal directly to your smartphone using a simple curl command. Best of all, by self-hosting ntfy on your own infrastructure, you retain absolute ownership of your data, eliminate reliance on external vendor limits, and build a robust, private alerting pipeline. This guide provides a comprehensive, step-by-step blueprint to deploying and utilizing a self-hosted ntfy instance for Linux system alerts.

Why Choose a Self-Hosted ntfy.sh Solution?

While the public ntfy.sh service is excellent, self-hosting offers distinct advantages tailored to enterprise security and engineering workflows:

• Complete Data Privacy: System logs and alert payloads often contain sensitive metadata, usernames, or internal IP addresses. Self-hosting ensures this data never leaves your private network perimeter.
• No Rate Limits: Public tiers impose strict quotas on notification frequency and attachment sizes. A self-hosted instance operates entirely under your control and resource limits.
• Zero Dependencies: No accounts, registration, or complex API keys are strictly required to start publishing messages, greatly reducing configuration overhead on remote servers.
• Lightweight Resource Footprint: Written in Go, ntfy is incredibly efficient, requiring minimal CPU and memory, making it perfect for small VPS instances or private homelab servers.

Step 1: Deploying ntfy via Docker Compose

The most reliable and maintainable method to self-host ntfy is utilizing Docker and Docker Compose. This ensures your configuration is declarative, isolated, and easy to upgrade.

1. Create the Directory Structure

First, access your server via SSH and establish a dedicated directory for your ntfy deployment:

mkdir -p /opt/ntfy/config /opt/ntfy/cache
cd /opt/ntfy

2. Configure the ntfy Server (server.yml)

Create a configuration file to define your server settings. Create /opt/ntfy/config/server.yml and add the following parameters:

# /opt/ntfy/config/server.yml
base-url: "[https://ntfy.yourdomain.com](https://ntfy.yourdomain.com)"
listen-http: ":8080"
cache-file: "/var/cache/ntfy/cache.db"
attachment-cache-dir: "/var/cache/ntfy/attachments"
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"

Note: Setting auth-default-access: "deny-all" is a security best practice for self-hosted instances to prevent unauthorized users from utilizing your server as a notification relay.

3. Define the Docker Compose File

Next, create the docker-compose.yml file in the /opt/ntfy directory:

version: '3.8'

services:
  ntfy:
    image: binwiederhier/ntfy:latest
    container_name: ntfy
    command: serve
    environment:
      - NTFY_BASE_URL=[https://ntfy.yourdomain.com](https://ntfy.yourdomain.com)
    volumes:
      - ./cache:/var/cache/ntfy
      - ./config:/etc/ntfy
      - ./lib:/var/lib/ntfy
    ports:
      - "8080:8080"
    restart: unless-stopped

Launch the container using the following command:

docker-compose up -d

Step 2: Connecting Mobile Devices (iOS and Android)

With the backend infrastructure operational, the next step is establishing the receiving end on your mobile devices.

1. Download the official ntfy application from the Apple App Store or Google Play Store.
2. Open the application, navigate to settings, and add your custom server URL: [https://ntfy.yourdomain.com](https://ntfy.yourdomain.com).
3. Tap the + (Plus) icon to subscribe to a new topic. Choose a unique, unguessable name for security purposes, such as srv-prod-alerts-99x.

Your device is now listening for incoming HTTP POST requests directed to that specific topic string.

Step 3: Triggering Alerts via Linux Command Line (Curl)

The beauty of ntfy lies in its minimalist API. You do not need dedicated SDKs; standard system tools like curl or wget are completely sufficient.

Basic Text Notification

To send a quick message from any Linux terminal, execute:

curl -d "Backup successfully completed on Production-01." [https://ntfy.yourdomain.com/srv-prod-alerts-99x](https://ntfy.yourdomain.com/srv-prod-alerts-99x)

Advanced Alerts with Priorities and Tags

ntfy supports extensive metadata modification via HTTP headers. You can define urgency categories, emojis, and titles to make notifications highly scannable on your phone's lock screen:

curl \
  -H "Title: Critical System Alert" \
  -H "Priority: high" \
  -H "Tags: warning,skull" \
  -d "Disk space on /dev/sda1 has exceeded 90% capacity!" \
  [https://ntfy.yourdomain.com/srv-prod-alerts-99x](https://ntfy.yourdomain.com/srv-prod-alerts-99x)

Available priorities range from min, low, default, high, to max. High and max priorities override Android Do Not Disturb settings and trigger immediate sound alerts on iOS devices.

Step 4: Practical Automation Scripts for Sysadmins

Integrating ntfy into production workflows maximizes its value. Below are two practical scripts you can deploy immediately.

1. Real-Time SSH Login Alert

To receive an instant push notification whenever a user successfully authenticates via SSH into your server, append the following script to /etc/pam.d/sshd or add it as a PAM execution script:

#!/bin/bash
if [ "$PAM_TYPE" = "open_session" ]; then
  curl -H "Title: SSH Access Detected" \
       -H "Priority: high" \
       -H "Tags: key,security" \
       -d "User $PAM_USER logged into $(hostname) from $PAM_RHOST via SSH." \
       [https://ntfy.yourdomain.com/srv-prod-alerts-99x](https://ntfy.yourdomain.com/srv-prod-alerts-99x)
fi

2. Automated Disk Monitoring Cronjob

Save this script as /usr/local/bin/disk_monitor.sh and configure it to run daily via cron to prevent silent storage exhaustion:

#!/bin/bash
THRESHOLD=90
CURRENT_USAGE=$(df / | grep / | awk '{ print $5 }' | sed 's/%//g')

if [ "$CURRENT_USAGE" -gt "$THRESHOLD" ]; then
  curl -H "Title: Storage Warning" \
       -H "Priority: max" \
       -H "Tags: fire,floppy_disk" \
       -d "Server storage is critical! Current usage: ${CURRENT_USAGE}%" \
       [https://ntfy.yourdomain.com/srv-prod-alerts-99x](https://ntfy.yourdomain.com/srv-prod-alerts-99x)
fi

Conclusion: Elevating DevOps Observability

By self-hosting ntfy.sh, you unlock a robust, streamlined, and private communication channel between your headless Linux servers and your mobile device. Eliminating heavy notification architectures in favor of simple HTTP and curl mechanisms dramatically lowers the barrier to comprehensive infrastructure visibility. Implement these scripts today to ensure you are always the first to know when your systems require manual intervention.