Self-hosting

Run it on your own box. Keep the alerts there.

One container, one SQLite file, nothing else to install. Runs on a VPS, a Raspberry Pi, or your homelab.

Quickstart guide GitHub repository Configuration reference

Quickstart

Docker or Docker Compose.

Option 1

Single Docker command

Run the pre-built container image from GitHub Container Registry. Mount a local directory to persist SQLite data.

docker run -d --name critalarm \
  -p 8080:8080 \
  -v ./data:/data \
  -e CA_BASE_URL=https://alerts.example.net \
  -e CA_RELAY_URL=https://relay.critalarm.app \
  ghcr.io/critalarm/server:1

Option 2

Docker Compose

Add Crit Alarm to your homelab compose stack with automatic container restarts.

services:
  critalarm:
    image: ghcr.io/critalarm/server:1
    container_name: critalarm
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/data
    environment:
      - CA_BASE_URL=https://alerts.example.net
      - CA_DATA_DIR=/data
      - CA_RELAY_URL=https://relay.critalarm.app

What it needs to run

The thing that pages you has to stay up when everything else does not. So there is one process, one file, and no other services.

Single SQLite file

Topics, tokens, incidents and audit rows live in one SQLite file. Copy the file and you have a backup.

Durable timers

Repeat, escalation and desk timers are rows in the database. A reboot or a container restart never drops an open incident.

Zero external services

No Redis, no PostgreSQL, no Kafka, no RabbitMQ. It uses under 25 megabytes of memory under full load.

Push on your own box

How your server reaches your phone without handing your alert text to anyone.

critical

The relay (default)

Apple and Google only accept pushes signed by a registered developer key. We run a relay that holds that key, so you do not need your own.

Your server sends an opaque hash of the topic ID and the incident number to the relay. The relay signals Apple APNs. Your phone wakes up, contacts your self-hosted server directly, and fetches the alert text. The relay never sees your alert titles, bodies, or hostnames.

topic

Bring your own APNs keys

If you have an Apple Developer account, skip the relay.

Provide your APNs authentication key file directly to the container:

CA_APNS_KEY_FILE=/data/apns.p8
CA_APNS_KEY_ID=ABC1234XYZ
CA_APNS_TEAM_ID=DEF5678UVW

Connect the mobile app in three steps

Use the official Crit Alarm app on iOS and Android. Point it at your server in Settings.

STEP 1

Install the app

Install Crit Alarm from the Apple App Store or Google Play Store.

STEP 2

Set server address

Open Settings, tap the Server field, and type your domain: https://alerts.example.net.

STEP 3

Receive alarms

Create your topics and publish alerts. Sirens, acknowledgments, and logs stream directly to your server.

Reverse proxy configurations

Production examples for Caddy and Nginx with WebSocket streaming and header forwarding.

Caddy (Automatic HTTPS)

alerts.example.net {
    reverse_proxy localhost:8080
}

Nginx

server {
    server_name alerts.example.net;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Backups and maintenance

Safe live backups without stopping your container.

# Safely back up SQLite while the container runs
docker exec critalarm sqlite3 /data/critalarm.db ".backup /data/backup-$(date +%Y%m%d).db"

Run it yourself

Crit Alarm is open source under AGPL-3.0. Pull the container and point the app at it.

View on GitHub Read the docs