Deploying ntfy

Introduction

ntfy (pronounced “notify”) is a simple HTTP-based pub-sub notification service that allows you to send notifications to your phone or desktop via scripts from any computer, entirely without signup or cost. With a self-hosted instance, you have complete control over your notification infrastructure.

Built with Go, ntfy is lightweight, fast, and easy to deploy. It supports multiple clients including web, Android, iOS, and command-line interfaces. The simple HTTP API makes it trivial to integrate notifications into any script, cron job, or application.

Key highlights of ntfy:

• Simple HTTP API: Send notifications with a simple curl command
• No Signup Required: Start sending notifications immediately
• Topic-Based: Organize notifications into topics for different purposes
• Cross-Platform: Web, Android, iOS, and CLI clients available
• File Attachments: Send files along with notifications
• Actions: Add clickable actions to notifications
• Scheduled Delivery: Send notifications at a specific time
• Authentication: Optional user authentication and ACLs
• UnifiedPush Support: Works as a UnifiedPush distributor
• Open Source: Licensed under Apache 2.0

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

Why Deploy ntfy on Klutch.sh

Deploying ntfy on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds ntfy. Push to GitHub, and your notification service deploys automatically.

Persistent Storage: Attach persistent volumes for message cache and attachments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure notifications.

GitHub Integration: Connect your configuration repository directly from GitHub for automatic updates.

Custom Domains: Assign a custom domain for your notification service.

Always-On Availability: Your notification service remains accessible 24/7 for critical alerts.

Privacy: Keep your notifications private on your own infrastructure.

Prerequisites

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

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

Understanding ntfy Architecture

ntfy has a simple, efficient architecture:

Go Backend: Single binary server written in Go for performance.

SQLite Cache: Optional persistent message cache.

HTTP API: RESTful API for publishing and subscribing.

WebSocket: Real-time notification delivery to clients.

Attachment Storage: Optional file storage for attachments.

Preparing Your Repository

To deploy ntfy on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM binwiederhier/ntfy:latest

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

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

# Expose HTTP port
EXPOSE 80

# Start ntfy server
CMD ["serve"]

Creating the Configuration File

Create a server.yml configuration file:

# ntfy server configuration

# Base URL for the server
base-url: "https://your-app-name.klutch.sh"

# Listen address
listen-http: ":80"

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

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

# Optional: Enable web UI
enable-web: true

# Optional: Rate limiting
visitor-request-limit-burst: 60
visitor-request-limit-replenish: "5s"

Advanced Configuration with Authentication

For secured instances:

# ntfy server configuration

base-url: "https://your-app-name.klutch.sh"
listen-http: ":80"

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

# Attachments
attachment-cache-dir: "/var/lib/ntfy/attachments"
attachment-total-size-limit: "5G"
attachment-file-size-limit: "15M"

# Web UI
enable-web: true

# Authentication
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"

# Behind reverse proxy
behind-proxy: true

Creating the .dockerignore File

Create a .dockerignore file:

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

Deploying ntfy on Klutch.sh

Once your repository is prepared, follow these steps to deploy ntfy:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile server.yml .dockerignore README.md
git commit -m "Initial ntfy deployment configuration"
git remote add origin https://github.com/yourusername/ntfy-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “ntfy” or “notifications”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your ntfy Dockerfile.

Configure HTTP Traffic

ntfy serves its API over HTTP. In the deployment settings:

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

Attach Persistent Volumes

Persistent storage enables message caching and attachments:

Mount Path	Recommended Size	Purpose
/var/cache/ntfy	1 GB	Message cache database
/var/lib/ntfy	5 GB	Attachments and user database

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the ntfy container
• Provision an HTTPS certificate

Access ntfy

Once deployment completes, access your ntfy web interface at https://your-app-name.klutch.sh. You can immediately start sending notifications.

Sending Notifications

Simple Notification

Send a basic notification with curl:

curl -d "Backup completed successfully" https://your-app-name.klutch.sh/my-topic

Notification with Title

Add a title to your notification:

curl \
  -H "Title: Backup Complete" \
  -d "Your database backup finished at $(date)" \
  https://your-app-name.klutch.sh/my-topic

Priority and Tags

Set priority and add tags:

curl \
  -H "Title: Server Alert" \
  -H "Priority: urgent" \
  -H "Tags: warning,skull" \
  -d "CPU usage exceeded 90%" \
  https://your-app-name.klutch.sh/alerts

With Actions

Add clickable actions:

curl \
  -H "Actions: view, Open Dashboard, https://example.com/dashboard" \
  -d "New user registered" \
  https://your-app-name.klutch.sh/my-topic

With Attachments

Send files:

curl \
  -T backup.log \
  -H "Filename: backup.log" \
  https://your-app-name.klutch.sh/my-topic

Subscribing to Notifications

Web Interface

1. Go to your ntfy URL
2. Subscribe to a topic
3. Notifications appear in real-time

Mobile Apps

1. Install ntfy app (Android/iOS)
2. Add your server URL
3. Subscribe to topics

Command Line

Subscribe via curl:

curl -s https://your-app-name.klutch.sh/my-topic/json

WebSocket

Real-time subscription:

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

Integration Examples

Shell Script

#!/bin/bash
# notify.sh - Send notification on script completion

TOPIC="scripts"
SERVER="https://your-app-name.klutch.sh"

send_notification() {
  curl -s \
    -H "Title: $1" \
    -d "$2" \
    "$SERVER/$TOPIC"
}

# Your script logic here
./backup.sh

if [ $? -eq 0 ]; then
  send_notification "Backup Success" "Backup completed successfully"
else
  send_notification "Backup Failed" "Backup script encountered an error"
fi

Python

import requests

def notify(topic, message, title=None, priority=None):
    url = f"https://your-app-name.klutch.sh/{topic}"
    headers = {}
    if title:
        headers["Title"] = title
    if priority:
        headers["Priority"] = priority

    response = requests.post(url, data=message, headers=headers)
    return response.status_code == 200

# Usage
notify("alerts", "Server restart complete", title="Server Status", priority="high")

GitHub Actions Integration

.github/workflows/notify.yml

name: Notify on Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        run: echo "Deploying..."

      - name: Send Notification
        run: |
          curl \
            -H "Title: Deployment Complete" \
            -H "Tags: rocket" \
            -d "Successfully deployed to production" \
            https://your-app-name.klutch.sh/deployments

Cron Job Monitoring

/etc/cron.d/backup-notify

0 2 * * * root /usr/local/bin/backup.sh && curl -d "Backup completed" https://your-app-name.klutch.sh/cron || curl -H "Priority: high" -d "Backup FAILED" https://your-app-name.klutch.sh/cron

User Authentication

Creating Users

With authentication enabled:

# Access container and create user
ntfy user add --role=admin admin
ntfy user add user1

Access Control

Grant topic access:

# Allow user1 to read and write to topic
ntfy access user1 my-topic rw

# Allow everyone to read alerts
ntfy access '*' alerts ro

Authenticated Requests

Send with authentication:

curl -u user1:password \
  -d "Private notification" \
  https://your-app-name.klutch.sh/my-topic

UnifiedPush

ntfy can serve as a UnifiedPush distributor:

1. Install UnifiedPush-compatible apps
2. Point them to your ntfy server
3. Receive notifications through ntfy

Production Best Practices

Security Recommendations

• Authentication: Enable for production use
• Rate Limiting: Configure to prevent abuse
• HTTPS: Always use HTTPS (provided by Klutch.sh)
• Topic Names: Use non-guessable topic names for sensitive notifications

Monitoring

Monitor your ntfy instance:

• Check cache size
• Monitor request rates
• Review error logs

Backup Strategy

Protect your configuration:

1. Back up user database if using authentication
2. Configuration can be restored from repository

Troubleshooting Common Issues

Notifications Not Received

Solutions:

• Verify topic name matches
• Check client is connected
• Review server logs
• Ensure network connectivity

Authentication Errors

Solutions:

• Verify credentials
• Check access permissions
• Review auth configuration

Cache Full

Solutions:

• Increase cache-duration
• Expand storage volume
• Clean old attachments

Additional Resources

• Official ntfy Website
• ntfy Documentation
• ntfy GitHub Repository
• ntfy Docker Hub
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying ntfy on Klutch.sh gives you a private, powerful notification service with automatic builds and secure HTTPS access. The combination of ntfy’s simple API and Klutch.sh’s deployment simplicity means you can have push notifications running in minutes.

With support for multiple platforms, file attachments, and actions, ntfy provides everything you need for application and script notifications. Whether you’re monitoring server health, CI/CD pipelines, or any automated process, ntfy on Klutch.sh delivers reliable notifications while keeping your data private.