Configuration Reference

Crit Alarm is configured using environment variables or a YAML configuration file.

Configuration Formats

Environment Variables

Environment variables are prefixed with CRITALARM_ and use uppercase snake_case:

CRITALARM_BASE_URL="https://alerts.example.com"
CRITALARM_RELAY_URL="https://relay.critalarm.app"
CRITALARM_RELAY_CONTENT="none"
CRITALARM_LISTEN=":8080"
CRITALARM_DATA_DIR="/data"
CRITALARM_BEHIND_PROXY="true"

YAML Configuration File

Alternatively, mount a configuration file at /etc/critalarm/config.yaml or pass --config /path/to/config.yaml:

base-url: https://alerts.example.com
relay-url: https://relay.critalarm.app
relay-content: none
listen: :8080
data-dir: /data
behind-proxy: true

Configuration Options

`base-url`

Environment Variable: CRITALARM_BASE_URL
Type: String (URL)
Required: Yes
Example: https://alerts.example.com

The public URL at which your server is accessible from the internet. Do not include a trailing slash.

This must match the app: The mobile app and push relay identify subscriptions by a cryptographic topic hash: sha256(base_url + "/" + topic). If base-url does not exactly match the server address entered in the mobile app, topic hashes will not align, and push notifications will not reach your phone.

`relay-url`

Environment Variable: CRITALARM_RELAY_URL
Type: String (URL)
Default: https://relay.critalarm.app

The endpoint of the push relay service responsible for delivering APNs (Apple) and FCM (Android) notifications to mobile devices.

`relay-content`

Environment Variable: CRITALARM_RELAY_CONTENT
Type: String enum (none or full)
Default: none

Controls how alert data is transmitted through the push relay.

none (the default): The push notification sent to the relay contains only an opaque topic hash, incident ID, and priority. No message title, body, or server URL is included. When the push arrives on an iOS device, the iOS Notification Service Extension (NSE) connects back to your server (GET /v1/incidents/:id) using your local credentials to fetch the title and body before displaying the alert. If the device cannot reach your server (for example, if your home internet is down), the alarm still rings with a generic fallback title: Critical alert on prod (open to see details).
full: The alert title and message body are included directly inside the push payload delivered through the relay. This eliminates the secondary network fetch from the phone, but transmits alert text through the relay infrastructure.

`listen`

Environment Variable: CRITALARM_LISTEN
Type: String ([host]:port)
Default: :8080

The interface address and TCP port the HTTP daemon binds to inside the container or host.

`data-dir`

Environment Variable: CRITALARM_DATA_DIR
Type: String (File path)
Default: /data

The local directory where SQLite database files, migration locks, and authentication state are stored. Ensure this directory is mounted to persistent storage.

`behind-proxy`

Environment Variable: CRITALARM_BEHIND_PROXY
Type: Boolean (true or false)
Default: true

Instructs the HTTP server to trust standard forwarding headers (X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host) supplied by reverse proxies.

With it on, rate limiting counts the client, not your proxy, and the server knows the request came in over HTTPS.

Startup Log Verification

Upon boot, Crit Alarm logs all effective settings in its opening output:

[INFO] critalarm v0.1.0 starting
[INFO] base_url:       https://alerts.example.com
[INFO] relay_url:      https://relay.critalarm.app
[INFO] relay_content:  none
[INFO] listen:         :8080
[INFO] data_dir:       /data
[INFO] behind_proxy:   true
[INFO] mode:           selfhosted
[INFO] server listening on :8080

Review this log line after starting your container to verify that reverse proxy configuration and environment variables were recognized correctly.