68 lines
3.7 KiB
Markdown
68 lines
3.7 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/healthz`
|
|
- Web: `GET http://localhost:8080/healthz`
|
|
|
|
A service is ready only when Compose reports `healthy`; container running status alone is insufficient. The API health response includes `"outreach_enabled": false` as an operational safety check.
|
|
|
|
## Configuration and deployment
|
|
|
|
Copy `.env.example` for local development. Production values must be supplied by the deployment environment, never committed. Keep `AUTOMATED_OUTREACH_ENABLED=false`; automated outreach is explicitly disabled in this MVP and there is no supported production enablement path in this repository.
|
|
|
|
Before deployment:
|
|
|
|
1. Run `docker compose config` and review the rendered configuration.
|
|
2. Build from a reviewed commit and scan the resulting images.
|
|
3. Restrict host/network exposure at the ingress/firewall.
|
|
4. Verify both 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`. Inspect it 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.
|