Deploying Apprise API

Introduction

Apprise API is a lightweight REST API that wraps the powerful Apprise notification library. It provides a unified gateway to send push notifications to over 100+ services including Slack, Discord, Telegram, Microsoft Teams, email, SMS, and many more—all through a single, consistent API.

Apprise API is ideal for:

DevOps & Infrastructure - Send alerts from monitoring systems, CI/CD pipelines, and automation scripts
Application Notifications - Integrate push notifications into your apps without managing multiple SDKs
Home Automation - Connect smart home systems to notification services
Microservices Architecture - Centralize notification handling across distributed systems
Alert Aggregation - Route different types of alerts to different channels based on tags

Key Features

100+ Services

Send notifications to Slack, Discord, Telegram, Teams, email, SMS, and more

Unified API

One consistent API to rule all notification services

Configuration Manager

Built-in web UI for managing notification configurations

Stateless & Stateful

Use on-demand notifications or save configurations for reuse

Why Deploy Apprise API on Klutch.sh?

Deploying Apprise API on Klutch.sh provides several advantages:

Instant deployment - Push your configuration and Apprise API is live in minutes
Persistent storage - Save notification configurations that persist across deployments
Automatic HTTPS - Secure all API calls with SSL certificates
Custom domains - Use your own domain for a professional notification endpoint
Always available - Your notification gateway is always online

Prerequisites

Before deploying Apprise API on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account
API credentials for the notification services you want to use (Slack webhooks, Discord webhooks, Telegram bot tokens, etc.)

Supported Notification Services

Apprise supports a vast array of notification services. Here are some popular ones:

Category	Services
Chat & Messaging	Slack, Discord, Microsoft Teams, Telegram, Matrix, Mattermost, Rocket.Chat
Email	SMTP, Gmail, Outlook, SendGrid, Mailgun, AWS SES
SMS	Twilio, AWS SNS, Vonage, Clickatell, BulkSMS
Push Notifications	Pushover, Pushbullet, Gotify, ntfy, Join
DevOps	PagerDuty, Opsgenie, Splunk, Prometheus Alertmanager
Social	Twitter, Reddit, Mastodon

For a complete list, visit the Apprise Wiki.

Project Structure

Create a new directory for your Apprise API deployment:

apprise-server/
├── Dockerfile
├── config/
│   └── (saved configurations)
├── plugin/
│   └── (custom plugins)
└── attach/
    └── (file attachments)

Creating the Dockerfile

Klutch.sh automatically detects Dockerfiles in your repository’s root directory. You can use the official Apprise image directly or create a custom Dockerfile:

Option 1: Simple Dockerfile (Recommended)

FROM caronc/apprise:latest

# Set labels
LABEL name="apprise-api" \
      description="Apprise Push Notification API Gateway" \
      maintainer="Your Name"

# Configure environment variables
ENV APPRISE_STATEFUL_MODE=simple
ENV APPRISE_WORKER_COUNT=2
ENV APPRISE_DEFAULT_THEME=light

# Create directories for persistent data
RUN mkdir -p /config /plugin /attach

# Expose the API port
EXPOSE 8000

# The base image handles the CMD

Option 2: Custom Dockerfile with Additional Configuration

FROM caronc/apprise:latest

# Set labels
LABEL name="apprise-api" \
      description="Apprise Push Notification API Gateway" \
      maintainer="Your Name"

# Environment configuration
ENV APPRISE_STATEFUL_MODE=simple
ENV APPRISE_WORKER_COUNT=2
ENV APPRISE_DEFAULT_THEME=light
ENV APPRISE_ATTACH_SIZE=50
ENV APPRISE_CONFIG_LOCK=no
ENV LOG_LEVEL=INFO

# Create directories
RUN mkdir -p /config /plugin /attach

# Set proper permissions
RUN chown -R 1000:1000 /config /plugin /attach

# Expose the API port
EXPOSE 8000

Environment Variables

Apprise API supports extensive configuration through environment variables:

Core Configuration

Variable	Description	Default
`APPRISE_STATEFUL_MODE`	Storage mode: `simple`, `hash`, or `disabled`	`hash`
`APPRISE_WORKER_COUNT`	Number of Gunicorn workers	`(2 * CPUs) + 1`
`APPRISE_DEFAULT_THEME`	Web UI theme: `light` or `dark`	`light`
`APPRISE_DEFAULT_CONFIG_ID`	Default configuration key	`apprise`

Storage Configuration

Variable	Description	Default
`APPRISE_CONFIG_DIR`	Configuration storage path	`/config`
`APPRISE_ATTACH_DIR`	Attachment storage path	`/attach`
`APPRISE_ATTACH_SIZE`	Max attachment size in MB	`200`
`APPRISE_PLUGIN_PATHS`	Custom plugin directories	`/plugin`

Security Configuration

Variable	Description	Default
`APPRISE_CONFIG_LOCK`	Lock configuration (read-only mode)	`no`
`SECRET_KEY`	Django secret key for hashing	Auto-generated
`ALLOWED_HOSTS`	Allowed host headers	`*`
`APPRISE_DENY_SERVICES`	Comma-separated services to block	`windows,dbus,gnome,macosx,syslog`

Stateless Configuration

Variable	Description	Default
`APPRISE_STATELESS_URLS`	Default URLs for stateless `/notify` calls	None

Local Development

Test your Apprise API setup locally before deploying to Klutch.sh:

Using Docker Compose

Create a docker-compose.yml for local development:

version: '3.8'

services:
  apprise:
    image: caronc/apprise:latest
    container_name: apprise
    ports:
      - "8000:8000"
    environment:
      - APPRISE_STATEFUL_MODE=simple
      - APPRISE_WORKER_COUNT=1
      - APPRISE_DEFAULT_THEME=light
    volumes:
      - ./config:/config
      - ./plugin:/plugin
      - ./attach:/attach
    restart: unless-stopped

Build and Run Locally

# Create directories
mkdir -p config plugin attach

# Start the container
docker compose up -d

# Check the logs
docker compose logs -f apprise

# Test the API
curl http://localhost:8000/status

Visit http://localhost:8000 to access the web-based Configuration Manager.

Deploying to Klutch.sh

Push your code to GitHub

Initialize a Git repository and push to GitHub:

cd apprise-server
git init
git add .
git commit -m "Initial Apprise API setup"
git remote add origin https://github.com/yourusername/apprise-server.git
git push -u origin main

Create a new project on Klutch.sh
Navigate to klutch.sh/app and create a new project. Give your project a descriptive name like “apprise-api” or “notification-gateway”.
Connect your GitHub repository
Select GitHub as your git source and authorize Klutch.sh to access your repositories. Select the repository containing your Apprise API project.
Configure the deployment
Klutch.sh will automatically detect your Dockerfile. Configure the following settings:
- Traffic Type: HTTP
- Internal Port: 8000
Configure environment variables
Add the following environment variables in the Klutch.sh dashboard:

Variable Value
APPRISE_STATEFUL_MODE simple
APPRISE_WORKER_COUNT 2
APPRISE_DEFAULT_THEME light
Optional: Add APPRISE_STATELESS_URLS if you want default notification targets:
```
APPRISE_STATELESS_URLS=slack://tokenA/tokenB/tokenC,discord://webhook_id/webhook_token
```
Add persistent volumes
To persist your notification configurations across deployments, add a persistent volume:
- Mount Path: /config
- Size: 1 GB (sufficient for most use cases)
Optionally, add another volume for attachments:
- Mount Path: /attach
- Size: 5 GB (adjust based on attachment needs)
Deploy your application
Click the deploy button to start the build process. Klutch.sh will:
1. Clone your repository
2. Build the Docker image
3. Deploy the container
4. Configure networking and SSL
Access your Apprise API
Once deployed, your Apprise API will be available at:
```
https://your-app-name.klutch.sh
```
The Configuration Manager web UI is accessible at the root URL. The API endpoints are:
- GET /status - Health check
- POST /notify/ - Stateless notifications
- POST /notify/{KEY} - Stateful notifications
- POST /add/{KEY} - Save configuration
- GET /get/{KEY} - Retrieve configuration
- POST /del/{KEY} - Delete configuration

Variable	Value
`APPRISE_STATEFUL_MODE`	`simple`
`APPRISE_WORKER_COUNT`	`2`
`APPRISE_DEFAULT_THEME`	`light`

API Usage Examples

Health Check

# Check API status
curl https://your-app-name.klutch.sh/status

# JSON response
curl -H "Accept: application/json" https://your-app-name.klutch.sh/status

Stateless Notifications

Send notifications without saving configuration:

# Send to Slack
curl -X POST \
  -d "urls=slack://tokenA/tokenB/tokenC" \
  -d "title=Server Alert" \
  -d "body=CPU usage is at 95%" \
  -d "type=warning" \
  https://your-app-name.klutch.sh/notify/

# Send to multiple services
curl -X POST \
  -d "urls=slack://tokenA/tokenB/tokenC,discord://webhook_id/webhook_token" \
  -d "body=Deployment completed successfully" \
  -d "type=success" \
  https://your-app-name.klutch.sh/notify/

# Using JSON
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"urls":"tgram://bot_token/chat_id","title":"Alert","body":"Test message"}' \
  https://your-app-name.klutch.sh/notify/

Stateful Notifications (Saved Configurations)

Save configurations and reuse them:

# Save a configuration
curl -X POST \
  -d "urls=slack://tokenA/tokenB/tokenC,discord://webhook_id/webhook_token" \
  https://your-app-name.klutch.sh/add/devteam

# Send notification using saved config
curl -X POST \
  -d "title=Build Failed" \
  -d "body=Pipeline #1234 failed on staging" \
  -d "type=failure" \
  https://your-app-name.klutch.sh/notify/devteam

# Retrieve configuration
curl https://your-app-name.klutch.sh/get/devteam

# Delete configuration
curl -X POST https://your-app-name.klutch.sh/del/devteam

Using Tags

Tags allow you to target specific notification services:

# Save configuration with tags (YAML format)
curl -X POST \
  -d 'config=
urls:
  - slack://tokenA/tokenB/tokenC:
      - tag: devops
      - tag: urgent
  - discord://webhook_id/webhook_token:
      - tag: devops
  - mailto://user:pass@gmail.com:
      - tag: management
' \
  -d "format=yaml" \
  https://your-app-name.klutch.sh/add/myconfig

# Notify only devops tag
curl -X POST \
  -d "tag=devops" \
  -d "body=Server maintenance starting" \
  https://your-app-name.klutch.sh/notify/myconfig

# Notify devops AND urgent (space = AND)
curl -X POST \
  -d "tag=devops urgent" \
  -d "body=Critical issue detected!" \
  https://your-app-name.klutch.sh/notify/myconfig

Sending Attachments

# Send notification with attachment
curl -X POST \
  -F "urls=mailto://user:pass@gmail.com" \
  -F "body=Please see the attached report" \
  -F "attach=@/path/to/report.pdf" \
  https://your-app-name.klutch.sh/notify/

# Multiple attachments
curl -X POST \
  -F "urls=slack://tokenA/tokenB/tokenC" \
  -F "body=Latest screenshots" \
  -F "attach1=@screenshot1.png" \
  -F "attach2=@screenshot2.png" \
  https://your-app-name.klutch.sh/notify/

Notification URL Examples

Here are some common notification URL formats:

Chat Services

# Slack
slack://tokenA/tokenB/tokenC
slack://botname@tokenA/tokenB/tokenC/#channel

# Discord
discord://webhook_id/webhook_token

# Microsoft Teams
msteams://TokenA/TokenB/TokenC

# Telegram
tgram://bot_token/chat_id

# Matrix
matrixs://user:pass@hostname/#room

Email Services

# Generic SMTP
mailto://user:pass@smtp.example.com
mailtos://user:pass@smtp.example.com:587

# Gmail
mailto://user:app_password@gmail.com

# SendGrid
sendgrid://apikey:from_email/to_email

Push Services

# Pushover
pover://user_key@api_token

# Gotify
gotify://hostname/token

# ntfy
ntfy://topic
ntfys://ntfy.sh/mytopic

# Pushbullet
pbul://access_token

DevOps Services

# PagerDuty
pagerduty://integration_key@api_key

# Opsgenie
opsgenie://api_key

# Apprise (recursive to another Apprise server)
apprise://hostname/config_key

Web Configuration Manager

Apprise API includes a built-in web UI for managing configurations:

Accessing the UI

Navigate to https://your-app-name.klutch.sh in your browser.

Features

Configuration Keys - Create and manage multiple notification configurations
URL Editor - Add notification URLs with a visual editor
Tag Management - Organize URLs with tags for targeted notifications
Test Notifications - Send test messages directly from the UI
Preview - View configured URLs and their associated tags

Integration Examples

Python Integration

import requests

APPRISE_URL = "https://your-app-name.klutch.sh"

def send_notification(title, body, notification_type="info"):
    response = requests.post(
        f"{APPRISE_URL}/notify/devteam",
        json={
            "title": title,
            "body": body,
            "type": notification_type  # info, success, warning, failure
        }
    )
    return response.status_code == 200

# Usage
send_notification("Deployment", "v2.0.0 deployed to production", "success")

Node.js Integration

const axios = require('axios');

const APPRISE_URL = 'https://your-app-name.klutch.sh';

async function sendNotification(title, body, type = 'info') {
  try {
    const response = await axios.post(`${APPRISE_URL}/notify/devteam`, {
      title,
      body,
      type
    });
    return response.status === 200;
  } catch (error) {
    console.error('Notification failed:', error.message);
    return false;
  }
}

// Usage
sendNotification('Alert', 'Database backup completed', 'success');

Shell Script Integration

#!/bin/bash

APPRISE_URL="https://your-app-name.klutch.sh"

send_alert() {
    local title="$1"
    local body="$2"
    local type="${3:-info}"

    curl -s -X POST \
        -d "title=${title}" \
        -d "body=${body}" \
        -d "type=${type}" \
        "${APPRISE_URL}/notify/devteam"
}

# Usage in scripts
send_alert "Backup Complete" "Daily backup finished successfully" "success"

Webhook Integration

Use Apprise API as a webhook endpoint for other services:

# Generic webhook URL
https://your-app-name.klutch.sh/notify/alerts?:payload=body&:subject=title

# The :param syntax remaps incoming fields to Apprise expected fields

Custom Domain Setup

To use a custom domain with your Apprise API:

Navigate to your project settings in the Klutch.sh dashboard
Add your custom domain (e.g., notify.yourdomain.com)
Configure DNS by adding a CNAME record pointing to your Klutch.sh app URL
Wait for SSL provisioning - Klutch.sh automatically provisions SSL certificates

Update your integrations to use the new domain:

curl -X POST \
  -d "body=Test notification" \
  https://notify.yourdomain.com/notify/devteam

Security Best Practices

Lock Configuration

For production, consider locking configurations to prevent modifications:

APPRISE_CONFIG_LOCK=yes

This makes all saved configurations read-only through the API.

Restrict Services

Block potentially dangerous local services:

APPRISE_DENY_SERVICES=windows,dbus,gnome,macosx,syslog,file

Use Allowed Hosts

Restrict which hosts can access the API:

ALLOWED_HOSTS=your-app-name.klutch.sh,notify.yourdomain.com

Troubleshooting

Common Issues

Problem: Cannot connect to the Apprise API.

Solution: Verify the deployment is running and check the internal port is set to 8000:

# Test health endpoint
curl https://your-app-name.klutch.sh/status

Problem: Notifications are not being delivered.

Solution:

Verify the notification URL format is correct
Check service credentials (tokens, API keys)
Test with the web UI first
Check the response for error details:

curl -v -X POST \
  -d "urls=slack://invalid/token" \
  -d "body=test" \
  https://your-app-name.klutch.sh/notify/

Problem: Configurations are lost after redeployment.

Solution: Ensure you have a persistent volume mounted at /config:

Mount Path: /config
Size: 1 GB

Problem: Cannot write to config or attach directories.

Solution: Check the status endpoint for permission issues:

curl -H "Accept: application/json" https://your-app-name.klutch.sh/status

Look for CONFIG_PERMISSION_ISSUE or ATTACH_PERMISSION_ISSUE in the response.

Monitoring with Prometheus

Apprise API provides a /metrics endpoint for Prometheus:

scrape_configs:
  - job_name: 'apprise'
    static_configs:
      - targets: ['your-app-name.klutch.sh']
    metrics_path: /metrics
    scheme: https

Summary

You’ve successfully deployed Apprise API on Klutch.sh! Your notification gateway now provides:

✅ Unified API for 100+ notification services
✅ Web-based Configuration Manager
✅ Persistent configuration storage
✅ Stateless and stateful notification modes
✅ Tag-based notification routing
✅ Automatic HTTPS

Apprise API simplifies notification management by providing a single, consistent interface to send alerts across all your communication channels—from Slack and Discord to email and SMS.