Self-Hosted

Herald is available as a Docker image for teams that need to run it on their own infrastructure. The self-hosted version has the same features as the managed service.

Docker images

Herald uses compile-time feature flags to produce different images. Pick the one that matches the engines you need.

Quick start

docker run -d \
  --name herald \
  -p 4000:4000 \
  -e SHROUDB_MASTER_KEY=$(openssl rand -hex 32) \
  herald/social

Herald starts on port 4000. A default tenant is created on first boot. No external database — storage is an encrypted WAL on disk.

Docker Compose

services:
  herald:
    image: herald/social
    ports:
      - "4000:4000"
    environment:
      SHROUDB_MASTER_KEY: ${SHROUDB_MASTER_KEY}
    volumes:
      - herald_data:/data

volumes:
  herald_data:

Server configuration

Self-hosted Herald reads configuration from a TOML file (default herald.toml) and environment variables. The only required env var is SHROUDB_MASTER_KEY — a 32-byte hex string for WAL encryption.

Server

[server]
host = "0.0.0.0"
port = 4000
max_connections = 10000

Storage

[store]
path = "/data/herald"
event_ttl_days = 7

Authentication

[auth]
password = "admin-secret"     # admin API bearer token
token_ttl_secs = 3600
token_warning_secs = 60

Webhooks

[webhook]
url = "https://your-app.com/webhooks/herald"
secret = "webhook-signing-secret"
timeout_ms = 5000
max_retries = 3

TLS

[tls]
enabled = false
cert_path = "/certs/herald.crt"
key_path = "/certs/herald.key"

Presence

[presence]
linger_secs = 10
override_ttl_secs = 14400
heartbeat_interval = 30
heartbeat_timeout = 10

Health checks

Metrics

Prometheus metrics are exposed at /metrics (no auth).

Admin API

Self-hosted deployments expose an admin API for multi-tenant management. Authenticate with the auth.password bearer token.