diff --git a/docs/development/non-container.md b/docs/development/non-container.md index f60b933..33a5483 100644 --- a/docs/development/non-container.md +++ b/docs/development/non-container.md @@ -15,9 +15,9 @@ The workspace is a pnpm monorepo with three package groups: | Group | Path | Purpose | | --- | --- | --- | -| `apps/` | `apps/server` (`@personal-blog/server`) | Public server application. Serves the application health endpoint (E00-S02-T03); the Fastify 5 application shell lands in a later story. | +| `apps/` | `apps/server` (`@personal-blog/server`) | Public server application. Serves the application health endpoint (E00-S02-T03) gated on the startup migration run (E00-S03-T06); the Fastify 5 application shell lands in a later story. | | `packages/` | `packages/core` (`@personal-blog/core`) | Application core (site identity, content primitives). Bootstrap placeholder. | -| `packages/` | `packages/database-postgres` (`@personal-blog/database-postgres`) | PostgreSQL database adapter package. Single owner of the `pg`/Kysely driver imports (E00-S03-T02); the migration ledger (`schema_migrations`, E00-S03-T03), the migration advisory lock (E00-S03-T04) and the migration runner with its failure diagnostic (E00-S03-T05) are implemented here. | +| `packages/` | `packages/database-postgres` (`@personal-blog/database-postgres`) | PostgreSQL database adapter package. Single owner of the `pg`/Kysely driver imports (E00-S03-T02); the migration ledger (`schema_migrations`, E00-S03-T03), the migration advisory lock (E00-S03-T04) and the migration runner with its failure diagnostic (E00-S03-T05) are implemented here. The server depends on this package to run the startup migrations behind its readiness gate (E00-S03-T06). | | `extensions/` | `extensions/example` (`@personal-blog/example-extension`) | Example extension exercising the `extensions/` group. Bootstrap placeholder. | A dependency-boundary rule (`dependency-boundaries.json`, enforced by @@ -94,10 +94,16 @@ compiled application entrypoint. Two things to know: compiled artifact in `dist/`, it does not compile first. 2. Since [E00-S02-T03], `apps/server` serves the **application health endpoint**: starting it opens an HTTP server on port 3000 answering - `GET /health` with HTTP 200 and `{"status":"ok"}`, so the process stays up. - The real Fastify 5 application shell — which turns this into the full - serving API — lands in a later story; the `start` command shape stays the - same once it does. + `GET /health`, so the process stays up. Since [E00-S03-T06] the endpoint + is the **readiness probe**: when a `DATABASE_URL` is configured, the app + runs the startup migrations before reporting ready — `GET /health` answers + HTTP 503 with `{"status":"not ready"}` while the run is in flight and HTTP + 200 with `{"status":"ok"}` only after it completes. With **no + `DATABASE_URL`** (this local non-container path) there is no migration run + to wait for, so the server reports ready immediately and `GET /health` + answers 200 `{"status":"ok"}` from the start. The real Fastify 5 + application shell — which turns this into the full serving API — lands in + a later story; the `start` command shape stays the same once it does. To run the compiled output of any other workspace package directly: