ITWorx Pulse release export
bd774932d5
Public source validation / validate (push) Failing after 3m8s
47 lines
2.5 KiB
Markdown
47 lines
2.5 KiB
Markdown
# 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.
|