# 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:

```bash
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:

1. confirm the selected host port is unused;
2. verify project, network, volume, and backup paths do not overlap another application;
3. render Compose and review every mount, published port, capability, user, and secret recipient;
4. run `deploy/verify-image-digests.sh`;
5. take checksummed backups of every external configuration that will change;
6. 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.