build prospect intelligence platform MVP

docs/OPERATIONS.md

@@ -0,0 +1,67 @@
+# 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.