diff --git a/docs/development/non-container.md b/docs/development/non-container.md index 1956391..a7c7459 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) gated on the startup migration run (E00-S03-T06); 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), and fails fast at startup with a field-specific error when a required setting is missing (E00-S04-T02); 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/config` (`@personal-blog/config`) | Configuration service. Owns the TypeBox/Ajv configuration schema for the validated config fields (E00-S04-T01); the environment adapter (E00-S04-T04), field-specific startup errors (E00-S04-T02) and secret redaction (E00-S04-T03) land in later tasks. | +| `packages/` | `packages/config` (`@personal-blog/config`) | Configuration service. Owns the TypeBox/Ajv configuration schema for the validated config fields (E00-S04-T01) and the field-specific startup error for a missing required setting (E00-S04-T02); the environment adapter (E00-S04-T04) and secret redaction (E00-S04-T03) land in later tasks. | | `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. | @@ -85,15 +85,23 @@ Expected result: `apps/server/dist/`, `packages/core/dist/`, ```sh # Run the compiled public server entrypoint -pnpm --filter @personal-blog/server start +EPPP_SESSION_SECRET='change-me-0123456789abcdefghijklmnopqrstuvwxyz' pnpm --filter @personal-blog/server start ``` This runs the `start` script of `apps/server` (`node dist/index.js`), i.e. the -compiled application entrypoint. Two things to know: +compiled application entrypoint. Three things to know: 1. The command **must follow `pnpm build`** — the `start` script executes the compiled artifact in `dist/`, it does not compile first. -2. Since [E00-S02-T03], `apps/server` serves the **application health +2. Since [E00-S04-T02] the server validates its **required settings at + startup**: the admin-session secret `EPPP_SESSION_SECRET` (the config + schema's required field, ≥ 32 characters, Security-and-Operations §32/§26) + must be set in the environment — if it is missing, the process fails fast + with a field-specific startup error (`missing required setting: + sessionSecret`) that names the missing field instead of booting. Provide it + in your shell or a local `.env` file (the `.env.example` template lands in + E00-S04). +3. Since [E00-S02-T03], `apps/server` serves the **application health endpoint**: starting it opens an HTTP server on port 3000 answering `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 @@ -131,7 +139,7 @@ pnpm install --frozen-lockfile # exit 0, lockfile untouched pnpm build # 5/5 packages emit dist/, exit 0 pnpm typecheck # 5/5 packages pass --noEmit, exit 0 pnpm test # 10/10 pass, exit 0 -pnpm --filter @personal-blog/server start # serves GET /health on port 3000, stays up +pnpm --filter @personal-blog/server start # requires EPPP_SESSION_SECRET (see [Run](#run)); serves GET /health on port 3000, stays up ``` ## Troubleshooting @@ -142,6 +150,7 @@ pnpm --filter @personal-blog/server start # serves GET /health on port 3000, s | `ERR_PNPM_OUTDATED_LOCKFILE` | `pnpm-lock.yaml` is out of date with the manifests. Run `pnpm install` (unfrozen) and commit the lockfile update. | | `ERR_PNPM_UNSUPPORTED_ENGINE` on install | Your Node version is outside the supported 24.x engine line (`engines.node` in the root `package.json`, enforced by `engineStrict: true` in `pnpm-workspace.yaml`). Install Node 24.x (e.g. via `nvm`, `fnm` or another version manager). | | `start` exits immediately with no output | The server crashed or exited at startup — check the process output. Since [E00-S02-T03] the entrypoint serves `GET /health` on port 3000 and stays up; a missing `pnpm build` (stale/absent `dist/`) is the usual cause (see [Run](#run)). | +| `start` fails with `missing required setting: sessionSecret` | Since [E00-S04-T02] the server validates its required settings at startup: the admin-session secret `EPPP_SESSION_SECRET` (≥ 32 chars) is missing or too short — set it in your shell or a local `.env` file (see [Run](#run)). | | `.env` files | `.env`/`.env.*` are git-ignored; a committed `.env.example` template lands with the environment story (E00-S04). | ## Out of scope