Host Deployment
Run the root compose stack behind Nginx and TLS on a single host.
Host Deployment
The repository includes host deployment notes for wipe.stack-plane.com. The
same pattern applies to a single VM or bare-metal host that runs Docker Compose
behind host Nginx.
Prepare Environment
Copy the host environment template and replace every placeholder:
cp deploy/host/wipe.stack-plane.com.env.example .env
Review at minimum:
| Group | Required values |
|---|---|
| Public URLs | API, frontend, Keycloak, verification, invitation, callback URLs. |
| Secrets | PostgreSQL, Keycloak, MinIO/S3, SMTP, frontend session secret, OIDC client secrets. |
| Admin access | ADMIN_API_ALLOWED_CIDRS, ADMIN_API_ALLOW_INTERNAL_NETWORKS, MFA window. |
| Storage | S3 endpoint, bucket names, credentials, optional filesystem fallback. |
| Signer | SIGNER_MODE, endpoint, bearer or mTLS material, key IDs, TSA settings. |
| Observability | OTel endpoint, environment name, logs/metrics/traces routing. |
Do not reuse local default passwords or seeded API keys outside local development.
Start The Stack
docker compose up --build -d
Check service health:
docker compose ps
curl -fsS http://127.0.0.1:8080/healthz
curl -fsS http://127.0.0.1:8080/readyz
Nginx And TLS
Install Nginx and Certbot on the host, create the webroot used by the provided configuration, issue a certificate, then enable the Nginx site:
mkdir -p /var/www/letsencrypt
Install deploy/host/wipe.stack-plane.com.nginx.conf as the enabled site after
adjusting names, upstream ports, and TLS paths.
The provided host routing shape is:
| Public path | Upstream |
|---|---|
| Dashboard or portal | 127.0.0.1:5173 or 127.0.0.1:5174, depending on selected frontend. |
| Public API paths | 127.0.0.1:8080 |
| Keycloak OIDC paths | 127.0.0.1:8081 |
When deploying both SvelteKit apps, keep a clear host split. The compose comments
expect the newer frontend on wipe.stack-plane.com and the older dashboard on a
test hostname.
Post-Deploy Checks
| Check | Expected result |
|---|---|
/healthz | HTTP 200 with {"status":"ok"}. |
/readyz | HTTP 200 and database ok. |
| Keycloak realm metadata | Public issuer URLs match the configured external hosts. |
| Login callback | Redirect URI exactly matches the Keycloak web client. |
| Invitation link | Uses the public PUBLIC_INVITATION_BASE_URL. |
| Swagger | Available only if exposing it is acceptable for the environment. |
| Admin API | Denied from non-allowlisted source IPs when allowlist is configured. |
| Grafana alerts | API heartbeat and worker heartbeat are present. |
Production Notes
The compose deployment is a reference shape. For regulated production, move the same services to the selected Kubernetes/Harbor target once secret ownership, image registry, storage policy, and signer connectivity are finalized.