elektrine-haraka/deployment/README.md

Deployment

Compose-based production deployment for the multi-role Haraka topology. This is the supported deployment path for this repository.

Services

• haraka-inbound: public MX listener on :25
• haraka-outbound: internal HTTP send/ops API on :8080
• haraka-worker: Redis consumer for inbound delivery to Phoenix
• haraka-submission: optional authenticated submission role, not published by default
• redis, clamav, spamassassin

Setup

cd deployment
cp .env.example .env
# edit .env
./start.sh

Same-server setup

For a single-host deployment beside the main Elektrine stack:

cp .env.same-server.example .env
# edit .env
../scripts/deploy/docker_deploy.sh

This uses docker-compose.same-server.yml, publishes MX on 25, binds the Haraka HTTP API to 127.0.0.1:18080, and reads certificates from the main Elektrine Caddy volume. It also joins the main Elektrine Docker network so Haraka can call http://elektrine_app:8080 directly.

Useful Commands

# inspect all services
docker compose ps

# view role logs
docker compose logs -f haraka-inbound
docker compose logs -f haraka-submission
docker compose logs -f haraka-outbound
docker compose logs -f haraka-worker

# queue state
docker compose exec redis redis-cli LLEN elektrine:inbound
docker compose exec redis redis-cli LLEN elektrine:inbound:dlq

# queue alert check (non-zero exit when thresholds exceeded)
../scripts/check-queues.sh

# health checks from the host running Haraka
curl -s -H 'X-API-Key: <key>' http://127.0.0.1:18080/status
curl -s -H 'X-API-Key: <key>' http://127.0.0.1:18080/metrics

Notes

• Elektrine should call the HTTP API through HARAKA_BASE_URL, commonly http://127.0.0.1:18080 on same-host installs or http://haraka-outbound:8080 on a shared Docker network.
• SMTP HTTP API traffic is served directly by haraka-outbound:8080 inside Compose.
• Inbound SMTP processing is async: accept fast on haraka-inbound, parse/deliver from haraka-worker.
• Client SMTP submission normally lives in Elektrine. Publish haraka-submission only if you intentionally want Haraka-managed submission.
• /status, /healthz, and /metrics accept X-API-Key by default.
• Set OPS_ALLOWED_CIDRS and METRICS_ALLOWED_CIDRS in .env only if you also want keyless access from trusted networks.
• Use immutable HARAKA_IMAGE_TAG values for reproducible rollouts.
• Override HARAKA_IMAGE in .env if you need to pull from a different registry/repo.