74 lines
4.8 KiB
Markdown
74 lines
4.8 KiB
Markdown
# Operations Runbook
|
|
|
|
## Start, inspect, stop
|
|
|
|
From the repository root:
|
|
|
|
```sh
|
|
docker compose up --build -d
|
|
docker compose ps
|
|
docker compose logs --follow api web
|
|
docker compose down
|
|
```
|
|
|
|
The expected health endpoints are:
|
|
|
|
- API: `GET http://localhost:8000/api/v1/health/live`
|
|
- Web: `GET http://localhost:8080/healthz`
|
|
|
|
A service is ready only when Compose reports `healthy`; container running status alone is insufficient. Health checks call public liveness endpoints and must remain unauthenticated—do not add a session requirement to `/api/v1/health/live` or `/healthz`. The Compose environment explicitly carries `AUTOMATED_OUTREACH_ENABLED=false` as an operational safety setting.
|
|
|
|
## Configuration and deployment
|
|
|
|
Copy `.env.example` for local development. Production values must be supplied by the deployment environment, never committed. `BOOTSTRAP_ADMIN_EMAIL` and `BOOTSTRAP_ADMIN_PASSWORD` are optional API environment variables for first-run admin provisioning only; set them together through a secret store or protected deployment environment, remove them immediately after successful bootstrap, and rotate the password. Do not put real values in Compose files, CI variables visible to logs, images, or committed `.env` files.
|
|
|
|
For production, use Argon2id for password hashing and require MFA for administrator accounts. Configure TLS before enabling `Secure` session cookies. Local Compose uses HTTP, so browser testing of the production `Secure` cookie behavior requires an HTTPS staging environment. Treat session cookies as bearer credentials: protect state-changing routes with CSRF controls, expire/revoke sessions, and never print cookie values in logs.
|
|
|
|
Before deployment:
|
|
|
|
1. Run `docker compose config` and review the rendered configuration (optional bootstrap values should be empty in CI and local validation).
|
|
2. Build from a reviewed commit and scan the resulting images.
|
|
3. Restrict host/network exposure at the ingress/firewall.
|
|
4. Verify both unauthenticated health checks and review logs for unexpected errors or sensitive data.
|
|
5. Record the image digest and configuration revision for rollback.
|
|
|
|
## Data, backups, and retention
|
|
|
|
The canonical API runtime under `apps/api` uses the named Docker volume `prospect-platform-api-data`.
|
|
|
|
Any older files under `infrastructure/docker/` are not referenced by Compose and are non-canonical; use `apps/api` and `apps/web` for all container changes. They can be removed during repository cleanup once no external tooling references them.
|
|
|
|
Inspect the volume with `docker volume inspect prospect-platform-api-data`; do not treat a local Docker volume as a backup.
|
|
|
|
For the current MVP there is no database migration or backup command. If runtime data is material, stop writes first and snapshot/copy the volume using an approved host backup process. Protect backup files with encryption and access controls, test a restore into an isolated environment, and document the result.
|
|
|
|
Recommended starting policy for a future production data store:
|
|
|
|
- daily encrypted backups, with at least 30 days of retention;
|
|
- point-in-time recovery where supported;
|
|
- one offline or separately isolated copy;
|
|
- quarterly restore drills, plus a restore test after storage/provider changes;
|
|
- retention and deletion schedules aligned with the source/contact policy and applicable law.
|
|
|
|
Do not run `docker compose down -v` on a data-bearing environment: it removes the named volume.
|
|
|
|
## Failure handling
|
|
|
|
- **Unhealthy API:** inspect `docker compose logs api`, verify port binding and resource availability, then restart with `docker compose restart api` if appropriate.
|
|
- **Unhealthy web:** inspect `docker compose logs web`; confirm port `8080` is available and the image contains `/healthz`.
|
|
- **Build failure:** run `docker compose build --no-cache` from a reviewed checkout and check Docker daemon/network status.
|
|
- **Unexpected outbound traffic:** stop the stack, preserve logs/metadata, and investigate. The MVP has no outreach worker and must not send automated messages.
|
|
|
|
## Scaling path
|
|
|
|
Adding Postgres, Redis, workers, or schedulers requires explicit readiness checks, migrations, queue durability/idempotency, secret injection, network segmentation, metrics/alerts, backup/restore procedures, and an operational owner. Do not add them as an implicit Compose dependency: this MVP is intentionally runnable without external Postgres or Redis.
|
|
|
|
## Incident checklist
|
|
|
|
1. Record time, affected service, image/config revision, and observed health state.
|
|
2. Preserve relevant logs without exporting secrets or unnecessary contact data.
|
|
3. Stop or isolate the affected service if data loss, unauthorized access, SSRF, or unexpected outreach is suspected.
|
|
4. Rotate exposed credentials through the secret manager.
|
|
5. Validate recovery with health checks and a targeted smoke test.
|
|
6. Document root cause, corrective action, and any retention/suppression impact.
|