Decompose: Service documentation (architecture, deployment, performance, development) — Phase 2: Deployment + operations #61

New issue

Closed

opened 2026-06-22 16:31:35 +00:00 by Mark · 0 comments

Mark commented

2026-06-22 16:31:35 +00:00

Owner

Phase 2: Deployment + operations

Goal: "How do I run this in production." Covers Docker, node_hub,
env vars, log format, healthcheck, monitoring, common failure modes.

Files:

New: docs/service/deployment.md (Docker build/run, node_hub
integration, env vars, port, scaling)
New: docs/service/operations.md (log format, /healthz, metrics,
common errors and what they mean)

Acceptance:

docs/service/deployment.md covers: building, running, env vars
(PORT, MAX_UPLOAD_MB, LOG_LEVEL, WORKER_POOL_SIZE, CORS), port
(8080), CORS configuration, Docker, node_hub, scaling notes.
docs/service/operations.md covers: structured log format, request
correlation IDs, /healthz semantics, suggested metrics (request
count, latency histogram, error rate, queue depth), top-5 common
errors and their fix.
A new operator can deploy the service in < 30 minutes reading
only these two docs.

Depends on: P1 (architecture context).

Decomposed from easystitch#40

## Phase 2: Deployment + operations **Goal:** "How do I run this in production." Covers Docker, node_hub, env vars, log format, healthcheck, monitoring, common failure modes. **Files:** - New: `docs/service/deployment.md` (Docker build/run, node_hub integration, env vars, port, scaling) - New: `docs/service/operations.md` (log format, /healthz, metrics, common errors and what they mean) **Acceptance:** - `docs/service/deployment.md` covers: building, running, env vars (PORT, MAX_UPLOAD_MB, LOG_LEVEL, WORKER_POOL_SIZE, CORS), port (8080), CORS configuration, Docker, node_hub, scaling notes. - `docs/service/operations.md` covers: structured log format, request correlation IDs, /healthz semantics, suggested metrics (request count, latency histogram, error rate, queue depth), top-5 common errors and their fix. - A new operator can deploy the service in < 30 minutes reading only these two docs. **Depends on:** P1 (architecture context). --- --- _Decomposed from [easystitch#40](https://forgejo.tail018ac4.ts.net/Mark/easystitch/issues/40)_