Public deployment guide

This guide describes the portable deployment contract. It intentionally contains no private hostnames, addresses, paths, identity-provider groups, or production evidence.

Supported topology

Run the base Compose file together with the production overlay:

docker compose -f deploy/compose.yaml -f deploy/compose.prod.yaml config
docker compose -f deploy/compose.yaml -f deploy/compose.prod.yaml up -d

Only pulse-web is published. The API, PostgreSQL, worker, agent, and migration job stay on explicit internal networks. Put a TLS reverse proxy in front of the web edge.

Required configuration

Copy .env.example to a protected runtime location outside Git and replace every example value. Production startup requires:

PULSE_POSTGRES_PASSWORD and PULSE_DATABASE_URL for a dedicated database;
PULSE_PUBLIC_URL with the external HTTPS origin;
OIDC issuer, client ID, client secret, redirect URL, groups claim, and explicit claim-to-role mapping;
a pre-created PULSE_BACKUP_DIR writable only by the API runtime identity;
PULSE_UNRAID_URL, a least-privilege read-only token, a public CA certificate, and matching PULSE_UNRAID_HOST_NAME/PULSE_UNRAID_HOST_GATEWAY when Unraid API collection is enabled;
an approved Prometheus-compatible endpoint when historical metrics are required.

Never place secrets in Compose literals, command history, logs, screenshots, or repository evidence.

Preflight

Before starting:

confirm the selected host port is unused;
verify project, network, volume, and backup paths do not overlap another application;
render Compose and review every mount, published port, capability, user, and secret recipient;
run deploy/verify-image-digests.sh;
take checksummed backups of every external configuration that will change;
record the current image, schema, proxy configuration, and rollback procedure.

Acceptance

Require all services to become healthy, run migrations explicitly, verify /healthz and /readyz, complete an HTTPS/OIDC login, verify WebSocket reconnect, check datasource freshness, restart the stack, and repeat the smoke tests. Run scripts/production-smoke.ps1 against the actual public origin to check headers, redirects, anonymous exposure, and readiness behavior.

Rollback

Stop only the Pulse project being deployed. Restore the previous proxy configuration and exact image/configuration. Restore PostgreSQL only from a verified backup when forward recovery is not safe. Never prune Docker or delete unknown networks, volumes, containers, or host data.

2.5 KiB Raw Blame History