docs(ops): add the operator runbook and record Phase 6 as complete
Why: - the slice had no operator documentation: no tuning guidance, no failure procedure, no statement of the proxy timeout requirement. Changes: - add docs/runbook.md: startup, deployment steps, provisioning, the INGESTION_* tuning table with each bound's status code, the proxy read-timeout rule, /healthz vs /readyz, failure investigation by real event name plus job/event SQL, retry semantics, and alert thresholds - link it from the README and note provisioning there - mark plan 001 Phase 6 done and refresh CLAUDE.md's status paragraph Impact: - documentation only Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -289,17 +289,28 @@ retrying the upload produces a correct final state without duplicate chunks.
|
||||
|
||||
1. Add an operator runbook covering local startup, migrations, MinIO bucket
|
||||
setup, the run command, ingestion-bound tuning, the proxy/client timeout
|
||||
requirement, and how to retry a failed ingestion.
|
||||
requirement, and how to retry a failed ingestion. — `docs/runbook.md`.
|
||||
2. Add a serialized Compose-based operational smoke test covering upload through
|
||||
indexed points against the running web process. Testcontainers remains the
|
||||
standard pytest mechanism for individual adapter integration tests.
|
||||
standard pytest mechanism for individual adapter integration tests. —
|
||||
`scripts/smoke.sh` driving `tests/e2e/test_compose_smoke.py`, which skips
|
||||
itself unless `SMOKE_BASE_URL` is set so `uv run pytest` never invokes
|
||||
Compose.
|
||||
3. Add end-to-end tests for duplicate upload, retrying a failed upload, tenant
|
||||
isolation, capacity/timeout rejection, and failed parser/Qdrant behavior.
|
||||
isolation, capacity/timeout rejection, and failed parser/Qdrant behavior. —
|
||||
`tests/e2e/test_ingestion_slice.py`, on Testcontainers, in the default suite.
|
||||
4. Add health/readiness checks that distinguish process health from dependency
|
||||
readiness.
|
||||
readiness. — `/healthz` and `/readyz`; `/readyz` additionally requires the
|
||||
`chunks` collection to exist, since a reachable but unbootstrapped Qdrant
|
||||
would `502` on the first upload.
|
||||
5. Update the README with local-start instructions and links to ADRs, this plan,
|
||||
and the operations runbook.
|
||||
|
||||
Provisioning a tenant and its first API key turned out to be a prerequisite for
|
||||
1 and 2 rather than a separate milestone: nothing over HTTP can create the first
|
||||
tenant, so `src/cli/provision_tenant.py` was added alongside the other two
|
||||
deployment-step commands.
|
||||
|
||||
**Exit criteria:** a new developer can start the stack, apply migrations, upload a
|
||||
a document, observe the job through completion, and understand how to investigate or
|
||||
retry a failure.
|
||||
|
||||
Reference in New Issue
Block a user