Day 19: Apprise API – The Ultimate Notification Gateway – 7 Days of Docker

In today’s fast-paced digital environment, having a reliable notification system is crucial for monitoring applications, services, and infrastructure. Enter Apprise API – a powerful, lightweight REST framework that wraps the popular Apprise notification library, allowing you to send notifications to over 100+ services through a single, unified interface.

What is Apprise API?

Apprise API is a microservice that provides a RESTful interface to the Apprise notification library. It enables you to:

• Send notifications to 100+ different services through a consistent API
• Store notification configurations for easy reuse
• Tag and group notification endpoints
• Attach files to your notifications
• Create a centralized notification gateway for your entire infrastructure

The API was designed to seamlessly integrate into existing ecosystems, making it an ideal solution for DevOps teams, system administrators, and developers looking for a unified notification service.

Key Features

• Wide Service Support: Send notifications to Telegram, Discord, Slack, Email, SMS services, and many more
• Simple REST Interface: Easy-to-use API endpoints for sending notifications
• Stateful or Stateless: Use it with persistent storage or as a simple pass-through service
• Configuration Manager: Built-in web UI for managing configurations
• File Attachments: Support for sending files with your notifications
• Tagging System: Group services together with customizable tags
• Docker Ready: Quick and easy deployment using containers

Installation with Docker

Installing Apprise API with Docker is straightforward using the LinuxServer.io image. Here’s how to get started:

Basic Installation

The simplest way to run Apprise API is to pull the LinuxServer.io image from Docker Hub:

# Pull the latest LinuxServer.io Apprise API image
docker pull lscr.io/linuxserver/apprise-api:latest

# Run the container with basic settings
docker run -d \
  --name=apprise-api \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -p 8000:8000 \
  -v /path/to/apprise-api/config:/config \
  --restart unless-stopped \
  lscr.io/linuxserver/apprise-api:latest

Once running, you can access the web interface at http://localhost:8000.

Advanced Installation with Attachments Support

If you want to enable file attachment support in notifications:

# Create directories for persistent storage
mkdir -p /path/to/apprise-api/config
mkdir -p /path/to/apprise-api/attachments

# Run with attachment support
docker run -d \
  --name=apprise-api \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e APPRISE_ATTACH_SIZE=200 \
  -p 8000:8000 \
  -v /path/to/apprise-api/config:/config \
  -v /path/to/apprise-api/attachments:/attachments \
  --restart unless-stopped \
  lscr.io/linuxserver/apprise-api:latest

Using Docker Compose

For easier management, you can use Docker Compose. Create a docker-compose.yml file:

---
services:
  apprise-api:
    image: lscr.io/linuxserver/apprise-api:latest
    container_name: apprise-api
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - APPRISE_ATTACH_SIZE=200 #optional
    volumes:
      - /path/to/apprise-api/config:/config
      - /path/to/apprise-api/attachments:/attachments #optional
    ports:
      - 8000:8000
    restart: unless-stopped

Then start the service:

docker-compose up -d

Environment Variables

The LinuxServer.io Apprise API container offers customization options through environment variables:

Variable	Description
PUID & PGID	User and group ID the container runs as (default: 1000)
TZ	Specify a timezone (e.g., Etc/UTC, America/New_York)
APPRISE_ATTACH_SIZE	Max attachment size in MB (set to 0 to disable attachments)

Volume Mappings

The container uses these volume mappings:

Volume	Function
/config	Persistent configuration files
/attachments	Temporary storage for files sent with notifications

For additional container configuration details, refer to the LinuxServer.io documentation.

Using the API

Sending a Simple Notification

Once your Apprise API is running, you can send notifications with a simple HTTP request:

# Send a notification to a specified service
curl -X POST -d 'urls=tgram://bottoken/ChatID&body=Hello from Apprise API!' \
  http://localhost:8000/notify

With Configuration Files

For a more organized approach, you can save configurations:

# Save a configuration with the key "myservices"
curl -X POST -d 'urls=discord://webhook_id/webhook_token,slack://TokenA/TokenB/TokenC' \
  http://localhost:8000/add/myservices

# Send a notification using the saved configuration
curl -X POST -d 'body=Alert: Server CPU usage high!' \
  http://localhost:8000/notify/myservices

Using Tags

Tags allow you to group services:

# Configure services with tags
# YAML configuration with tags for different teams
curl -X POST -F 'config=
urls:
  - discord://webhook_id/webhook_token:
      tag: devops alerts
  - slack://TokenA/TokenB/TokenC:
      tag: devops management
  - mailto://user:pass@gmail.com:
      tag: management
' -F 'format=yaml' http://localhost:8000/add/company-alerts

# Notify only DevOps team
curl -X POST -d 'tag=devops&body=Deployment completed successfully' \
  http://localhost:8000/notify/company-alerts

Supported Notification Services

Apprise supports an impressive list of over 100 notification services, including:

• Chat Platforms: Discord, Slack, Telegram, Microsoft Teams, Google Chat
• Email Services: SMTP, Gmail, Office 365, SendGrid, Mailgun
• SMS Services: Twilio, Vonage, MessageBird, AWS SNS
• Push Notifications: Pushover, PushBullet, Gotify
• Social Media: Twitter, Mastodon, Reddit
• Ticketing Systems: Jira, PagerDuty
• Desktop Notifications: Windows, MacOS, Linux (GNOME, KDE)

The complete list of supported services can be found in the Apprise Wiki.

Security Considerations

By default, Apprise API does not include authentication. For production use, consider:

1. Restricting access using a reverse proxy with authentication
2. Using the built-in authentication option with NginX configuration
3. Running the API on an internal network only
4. Setting up environment variables like APPRISE_CONFIG_LOCK for a read-only configuration

Thoughts

Apprise API offers a powerful, unified way to handle notifications across your entire infrastructure. With its Docker-based installation, you can be up and running in minutes, sending notifications to any of the 100+ supported services through a consistent, easy-to-use interface.

Whether you’re building a monitoring system, need alerts for your CI/CD pipeline, or want to consolidate all your notification needs into a single service, Apprise API has you covered.

Useful Links

• Apprise API GitHub Repository
• Apprise Core Library
• Supported Notification Services
• LinuxServer.io Apprise API Image
• Docker Hub – LinuxServer Apprise API