Documentation

Docker Installation

Version v2.5.0 · Updated
Interactive docs View on GitHub

Docker Installation#

Docker Compose is the fastest way to run IncidentRelay for testing, demos and simple self-hosted deployments.

The default Compose setup starts:

incidentrelay             # HTTP API, UI, incoming webhooks
incidentrelay-scheduler   # reminders, escalations, periodic jobs
incidentrelay-telegram    # Telegram callbacks / polling worker
incidentrelay-slack       # Slack Socket Mode worker

The Telegram and Slack workers are harmless when the corresponding integrations are not configured. PostgreSQL is optional. SQLite is suitable for small installations and quick starts.

Default architecture#

Docker Compose
├── incidentrelay
│   └── Gunicorn + Flask application
├── incidentrelay-scheduler
│   └── standalone scheduler worker
├── incidentrelay-telegram
│   └── Telegram callbacks / polling
├── incidentrelay-slack
│   └── Slack Socket Mode interactions
└── incidentrelay-data
    └── SQLite database volume

Default SQLite path inside the container:

/var/lib/incidentrelay/incidentrelay.db

Default config path inside the container:

/etc/incidentrelay/incidentrelay.conf

The config file is selected by:

INCIDENTRELAY_CONFIG_FILE

Non-root services (2.3.1 and later)#

The Docker image retains root only for entrypoint initialization. After rebuilding the runtime config and reconciling permissions, the entrypoint uses setpriv to start web, scheduler, Telegram, Slack, migrations and shell as the incidentrelay user (UID/GID 10001). Gunicorn uses the writable home /home/incidentrelay. Verify the running main process after startup:

docker compose exec incidentrelay grep ^Uid: /proc/1/status

Important: the image still starts with root as its Docker image default, so a plain docker compose exec can launch new commands as root even though PID 1 is unprivileged. Always pass --user 10001:10001 for admin commands (migrations, user creation, etc.) to avoid creating new root-owned SQLite or log files.

On the first startup after upgrading a Docker Compose named-volume deployment, the entrypoint repairs ownership of /var/lib/incidentrelay (including SQLite, its journal/WAL and the 0600 generated config) and /var/log/incidentrelay. It skips already-correct files and never follows symlinks outside these volumes. Existing secrets are retained by the normal runtime-config logic. The entrypoint must start as root for this one-time repair; do not set user: "10001:10001" on the Compose services unless the volumes have already been made writable for that UID.

When using docker run --user 12345 or OpenShift-style arbitrary UIDs, the entrypoint does not change ownership or attempt privilege escalation. Mounts, config and log directories must already be accessible to that UID. If the image home is not writable, HOME falls back to /tmp to avoid Gunicorn trying to write under /. Read-only external config files must be readable by the runtime user.

If an external bind mount, NFS share or unusual filesystem blocks the ownership repair, prepare its permissions using the volume owner's trusted administrative procedure before starting the upgraded container. Make a backup of the SQLite database before changing volume permissions.

Quick start with SQLite#

docker compose up -d

Open the UI:

http://SERVER_IP:8080/login

Show logs:

docker compose logs -f incidentrelay
docker compose logs -f incidentrelay-scheduler

Run migrations#

If migrations are not run automatically by your container entrypoint, run:

docker compose exec --user 10001:10001 incidentrelay python manage.py migrate

Create the first admin user#

docker compose exec --user 10001:10001 incidentrelay \
  python manage.py create-admin \
    --username admin \
    --password 'change-me-123' \
    --email admin@example.com

Change the password and email before production use.

Default SQLite config#

File:

docker/incidentrelay.docker.conf

Example:

[main]
log_level = INFO
log_file = /var/log/incidentrelay/incidentrelay.log

[server]
host = 0.0.0.0
port = 8080
public_base_url = http://localhost:8080

[database]
type = sqlite
name = /var/lib/incidentrelay/incidentrelay.db

[sqlite]
wal = true
busy_timeout = 5000

[voice]
provider = stub
providers_dir = /usr/local/lib/incidentrelay/voice_providers
callback_secret =

PostgreSQL variant#

Use PostgreSQL for:

  • larger teams;
  • higher alert volume;
  • multiple web workers;
  • longer-term production installations.

Start with PostgreSQL if the repository provides a PostgreSQL Compose override:

docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  up -d

PostgreSQL config example:

[database]
type = postgresql
host = postgres
port = 5432
name = incidentrelay
user = incidentrelay
password = incidentrelay-change-me

External access#

With this mapping:

ports:
  - "8080:8080"

IncidentRelay is available on:

http://SERVER_IP:8080

if the firewall allows port 8080.

For production, it is better to expose IncidentRelay through Nginx or HAProxy with HTTPS:

Internet -> Nginx/HAProxy :443 -> IncidentRelay :8080

Set the public URL correctly:

[server]
public_base_url = https://incidentrelay.example.com

public_base_url is used for generated links and callbacks.

Custom voice providers#

Custom voice providers can be mounted into:

/usr/local/lib/incidentrelay/voice_providers

Example Compose mount:

volumes:
  - ./custom_voice_providers:/usr/local/lib/incidentrelay/voice_providers:ro

After changing provider files, restart the containers:

docker compose restart incidentrelay incidentrelay-scheduler