Publish ITWorx Pulse source

2026-09-03 02:09:19 +02:00
commit bd774932d5
614 changed files with 77116 additions and 0 deletions
@@ -0,0 +1,46 @@
+# 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.