Skip to content
Klutch.sh Docs

Deploying ntfy

Introduction

ntfy (pronounced “notify”) is a simple, HTTP-based pub-sub notification service that lets you send push notifications to your phone or desktop from any script, application, or service. With no signup required and a simple curl command, ntfy makes it trivially easy to add notifications to any workflow.

Built with simplicity as a core principle, ntfy provides a refreshingly straightforward approach to notifications. Whether you want to know when a long-running script completes, receive alerts from your home automation system, or get notified about server events, ntfy handles it with minimal configuration.

Key highlights of ntfy:

  • Simple API: Send notifications with a single curl command or HTTP POST
  • No Signup Required: Start using immediately without registration
  • Mobile Apps: Native Android and iOS apps for push notifications
  • Web Interface: Browser-based notification viewing and subscription
  • Topic-Based: Subscribe to topics and receive all messages published to them
  • Attachments: Send files and images with your notifications
  • Actions: Include clickable buttons and actions in notifications
  • Priority Levels: Set urgency from min to max with different behaviors
  • Scheduled Delivery: Delay message delivery to a specific time
  • Message Caching: Messages are stored for later retrieval
  • Authentication: Optional access control for private topics
  • UnifiedPush: Acts as a UnifiedPush distributor for other apps
  • Open Source: Licensed under Apache 2.0

This guide walks through deploying ntfy on Klutch.sh using Docker, configuring the server, and integrating notifications into your workflows.

Why Deploy ntfy on Klutch.sh

Deploying ntfy on Klutch.sh provides several advantages:

Self-Hosted Privacy: Your notifications stay on your infrastructure with no third-party access.

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds ntfy without complex configuration.

Persistent Storage: Attach persistent volumes for message cache and user data.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, required for mobile app connections.

GitHub Integration: Connect your configuration repository for automatic redeployments.

Always Available: Your notification server runs 24/7, ready to receive and deliver messages.

Custom Domains: Use your own domain for a professional notification endpoint.

Prerequisites

Before deploying ntfy on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Basic familiarity with Docker and containerization concepts
  • (Optional) The ntfy mobile app for push notifications
  • (Optional) A custom domain for your ntfy instance

Understanding ntfy Architecture

ntfy uses a simple pub-sub model:

Topics: Named channels that messages are published to and subscribed from.

Publishers: Any HTTP client that sends messages to topics.

Subscribers: Apps, browsers, or services that receive messages from topics.

Message Cache: Temporary storage for messages to ensure delivery.

Authentication: Optional user system for access control.

Preparing Your Repository

Create a GitHub repository with your ntfy configuration.

Repository Structure

ntfy-deploy/
├── Dockerfile
├── server.yml
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in your repository root:

FROM binwiederhier/ntfy:latest


# Copy configuration
COPY server.yml /etc/ntfy/server.yml


# Create data directories
RUN mkdir -p /var/cache/ntfy /var/lib/ntfy


# Set environment variables
ENV NTFY_BASE_URL=${NTFY_BASE_URL}
ENV NTFY_CACHE_FILE=/var/cache/ntfy/cache.db
ENV NTFY_AUTH_FILE=/var/lib/ntfy/auth.db


# Expose HTTP port
EXPOSE 80


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:80/v1/health || exit 1


# Run ntfy
CMD ["serve"]

Creating the Configuration File

Create server.yml:

# ntfy Server Configuration


# Base URL of the server (required for attachments)
base-url: "${NTFY_BASE_URL}"


# Listen address
listen-http: ":80"


# Cache configuration
cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "12h"


# Attachment configuration
attachment-cache-dir: "/var/cache/ntfy/attachments"
attachment-total-size-limit: "5G"
attachment-file-size-limit: "15M"
attachment-expiry-duration: "3h"


# Authentication database
auth-file: "/var/lib/ntfy/auth.db"
auth-default-access: "read-write"


# Rate limiting
visitor-request-limit-burst: 60
visitor-request-limit-replenish: "5s"
visitor-attachment-total-size-limit: "100M"
visitor-attachment-daily-bandwidth-limit: "500M"


# Logging
log-level: "info"
log-format: "json"


# Enable web UI
enable-web: true


# Upstream server for UnifiedPush
# upstream-base-url: "https://ntfy.sh"


# Behind proxy settings
behind-proxy: true

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env

Environment Variables Reference

VariableRequiredDefaultDescription
NTFY_BASE_URLYes-Public URL of your ntfy instance
NTFY_AUTH_DEFAULT_ACCESSNoread-writeDefault access for unauthenticated users
NTFY_CACHE_DURATIONNo12hHow long to cache messages

Deploying ntfy on Klutch.sh

    Push Your Repository to GitHub

    Initialize and push your repository with the Dockerfile and configuration.

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project called “ntfy”.

    Create a New App

    Within your project, create a new app and connect your GitHub repository.

    Configure HTTP Traffic

    In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 80

    Set Environment Variables

    Configure the following environment variables:

    VariableValue
    NTFY_BASE_URLhttps://your-app-name.klutch.sh

    Attach Persistent Volumes

    Add the following volumes:

    Mount PathRecommended SizePurpose
    /var/cache/ntfy5 GBMessage cache and attachments
    /var/lib/ntfy1 GBAuthentication database

    Deploy Your Application

    Click Deploy to start the build process.

    Access ntfy

    Once deployment completes, access your instance at https://your-app-name.klutch.sh.

    Test Notifications

    Send a test notification to verify everything works.

Sending Notifications

Simple Message

Send a basic notification with curl:

Terminal window
curl -d "Backup completed successfully" https://your-app.klutch.sh/mytopic

With Title and Priority

Terminal window
curl \
  -H "Title: Server Alert" \
  -H "Priority: high" \
  -H "Tags: warning,server" \
  -d "CPU usage exceeded 90%" \
  https://your-app.klutch.sh/alerts

With Actions

Include clickable buttons:

Terminal window
curl \
  -H "Actions: view, Open Dashboard, https://example.com/dashboard; http, Acknowledge, https://example.com/ack" \
  -d "New deployment ready for review" \
  https://your-app.klutch.sh/deploys

With Attachments

Send a file with your notification:

Terminal window
curl \
  -H "Filename: report.pdf" \
  -T /path/to/report.pdf \
  https://your-app.klutch.sh/reports

Scheduled Delivery

Delay message delivery:

Terminal window
curl \
  -H "At: tomorrow, 9am" \
  -d "Time for your morning standup!" \
  https://your-app.klutch.sh/reminders

Using JSON

Send structured notifications:

Terminal window
curl \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "alerts",
    "title": "Build Failed",
    "message": "The nightly build failed with 3 errors",
    "priority": 4,
    "tags": ["x", "build"],
    "actions": [
      {"action": "view", "label": "View Logs", "url": "https://ci.example.com/logs"}
    ]
  }' \
  https://your-app.klutch.sh/

Subscribing to Notifications

Mobile Apps

  1. Download the ntfy app from Google Play or App Store
  2. Add your server URL in settings
  3. Subscribe to your topics
  4. Receive push notifications

Web Interface

Access https://your-app.klutch.sh in a browser to:

  • View recent notifications
  • Subscribe to topics
  • Send test messages
  • Manage subscriptions

Command Line

Subscribe and print messages:

Terminal window
curl -s https://your-app.klutch.sh/mytopic/json | while read line; do
  echo "$line" | jq .
done

WebSocket

For real-time subscriptions:

const ws = new WebSocket('wss://your-app.klutch.sh/mytopic/ws');
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data.message);
};

Common Use Cases

Script Completion Alerts

#!/bin/bash
# Your long-running script here
./backup.sh


# Notify when complete
curl -d "Backup finished at $(date)" https://your-app.klutch.sh/backups

Server Monitoring

Terminal window
# Send alert if disk usage exceeds 90%
USAGE=$(df -h / | awk 'NR==2 {print $5}' | tr -d '%')
if [ "$USAGE" -gt 90 ]; then
  curl -H "Priority: urgent" \
    -d "Disk usage at ${USAGE}%" \
    https://your-app.klutch.sh/server-alerts
fi

CI/CD Notifications

# In your CI/CD pipeline
- name: Notify on success
  run: |
    curl -H "Title: Build Successful" \
      -H "Tags: white_check_mark" \
      -d "Build ${{ github.run_number }} completed" \
      https://your-app.klutch.sh/builds

Home Automation

Integrate with Home Assistant, Node-RED, or other automation platforms to receive smart home alerts.

Authentication

Creating Users

Use the ntfy CLI to add users:

Terminal window
ntfy user add --role=admin admin
ntfy user add user1

Access Control

Restrict topic access:

Terminal window
ntfy access mytopic user1 read-write
ntfy access secret-topic everyone deny

Token-Based Auth

For scripts, use tokens:

Terminal window
curl -u "user:password" https://your-app.klutch.sh/private-topic
# Or with token
curl -H "Authorization: Bearer your_token" https://your-app.klutch.sh/private-topic

Troubleshooting

Notifications Not Arriving

  • Verify the topic name matches exactly
  • Check mobile app is connected to correct server
  • Ensure HTTPS is working (required for mobile)
  • Review message cache for undelivered messages

Attachments Failing

  • Check attachment size limits
  • Verify cache directory permissions
  • Ensure sufficient disk space

Authentication Issues

  • Verify auth file permissions
  • Check user credentials
  • Review default access settings

Rate Limiting

  • Adjust rate limit settings if needed
  • Check visitor limits in configuration

Additional Resources

Conclusion

Deploying ntfy on Klutch.sh gives you a powerful, self-hosted notification service that integrates with virtually any workflow. The simple HTTP API means you can add notifications to scripts, monitoring systems, and automation platforms with minimal effort.

With mobile apps for push notifications, a web interface for management, and support for attachments and actions, ntfy on Klutch.sh provides everything needed for a comprehensive notification system. Whether you’re monitoring servers, tracking build pipelines, or receiving smart home alerts, ntfy makes notifications simple and accessible.