docs(config): document runtime profiles, deploy variables and precedence in README (13-15)

README said runtime settings live in public/config.json, which the build
replaces with config/runtime/<profile>.json, and named none of APP_PROFILE,
RUNTIME_*, VITE_BUILD_ID, RELEASE_ID or RELEASE_TARGET. A unit test now
requires README to name every variable the generator and admission read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 23:26:20 +09:00
co-authored by Claude Opus 5.5
parent a55a15861e
commit 2ba880c7e2
4 changed files with 76 additions and 9 deletions
+45 -2
View File
@@ -21,8 +21,51 @@ corepack pnpm install --frozen-lockfile
corepack pnpm dev
```
Runtime-public settings live in `public/config.json` and are validated before
the product tree mounts. Client secrets are forbidden.
## Runtime configuration
Runtime-public settings are validated against one schema before the product
tree mounts (`runtimeConfigV2ArtifactSchema` in
`src/contracts/release-artifacts.ts`). Client secrets are forbidden.
The source of truth is `config/runtime/<profile>.json`, one file per
environment: `local`, `development`, `staging`, `production`. `corepack pnpm
build` writes `dist/config.json` from the selected profile
(`scripts/generate-runtime-config.ts`). `public/config.json` is only the local
profile for `corepack pnpm dev`; the build replaces it, so settings put there
never reach a deployment. Keep it equal to `config/runtime/local.json` plus
`BUILD_ID: local-build` and `RELEASE_ID: local-release`; nothing checks that
yet.
Build and deploy variables, lowest precedence first:
| Variable | Sets | Default |
| --- | --- | --- |
| `APP_PROFILE` | which `config/runtime/<profile>.json` is used | `local`; an empty value fails the build |
| `RUNTIME_API_BASE_URL` | `API_BASE_URL`, overriding the profile | the profile value |
| `RUNTIME_TELEMETRY_ENDPOINT` | `TELEMETRY_ENDPOINT`, overriding the profile | the profile value |
| `VITE_BUILD_ID` | `BUILD_ID` in the runtime config and the release manifest | `local-build` |
| `RELEASE_ID` | `RELEASE_ID` in the runtime config and the release manifest | `local-release` |
| `RELEASE_TARGET` | the environment FE-GATE-027 admits the build to; must equal `APP_PROFILE` | none; admission refuses without it |
Only the two `RUNTIME_*` values can differ from the reviewed profile. Anything
else changes by editing the profile file. Staging and production reject demo
auth and non-HTTPS endpoints.
A production build and its admission check:
```bash
APP_PROFILE=production \
RUNTIME_API_BASE_URL=https://api.example.com/ \
RUNTIME_TELEMETRY_ENDPOINT=https://telemetry.example.com/v1/events \
VITE_BUILD_ID=<unique build id> RELEASE_ID=<unique release id> \
corepack pnpm build
APP_PROFILE=production RELEASE_TARGET=production corepack pnpm check:release-admission
```
With `CI=true` the gate runner (`corepack pnpm ci:gate`) also requires
`VITE_COMMIT_SHA`, `SOURCE_DATE_EPOCH` and `CI_RUNNER_IMAGE` before it runs a
gate (`scripts/lib/build-environment.ts`, `scripts/run-ci-gate.ts`). The CI variable
list is in [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md).
## Included starter experience
+5 -5
View File
@@ -23,11 +23,11 @@ import { makeDistFilesPublic } from "./lib/dist-permissions.ts";
* Steps 5 and 6 are skipped for `REMOVE_REGISTRATION`, `PURGE_OWNED_RESOURCES`
* and `null`: those modes never run an active worker build.
*
* Step 4 has to follow the Vite build and precede the asset scan. Vite copies
* `public/` verbatim, so without it every build — including a production one —
* ships the local runtime document; and the Service Worker hashes the emitted
* `config.json`, so the profile must be in place before that inventory is
* taken.
* Step 4 has to follow the Vite build. Vite copies `public/` verbatim, so
* without it every build — including a production one — ships the local
* runtime document. The Service Worker asset scan excludes `config.json`
* (`scripts/generate-service-worker-assets.ts`), so the order against step 5
* is not what keeps the profile out of the worker cache (13-15).
*/
const selection = INSTALLED_RUNTIME_CAPABILITIES.serviceWorker;
+2 -2
View File
@@ -29,7 +29,7 @@ const OUTPUT_PATH = "dist/config.json";
* Deployment-supplied values. Everything else is fixed by the profile so a
* deployment cannot quietly widen what was reviewed.
*/
const OVERRIDES = Object.freeze({
export const RUNTIME_OVERRIDES = Object.freeze({
API_BASE_URL: "RUNTIME_API_BASE_URL",
TELEMETRY_ENDPOINT: "RUNTIME_TELEMETRY_ENDPOINT",
} as const);
@@ -49,7 +49,7 @@ export async function generateRuntimeConfig(
`${profilePath}: declares APP_ENV ${String(draft["APP_ENV"])}, expected ${target}`,
);
}
for (const [field, variable] of Object.entries(OVERRIDES)) {
for (const [field, variable] of Object.entries(RUNTIME_OVERRIDES)) {
const supplied = environment[variable];
if (supplied !== undefined && supplied !== "") draft[field] = supplied;
}
+24
View File
@@ -0,0 +1,24 @@
import { readFileSync } from "node:fs";
import { describe, expect, it } from "vitest";
import { RUNTIME_OVERRIDES } from "../../scripts/generate-runtime-config.ts";
// 13-15. README said runtime settings live in public/config.json, which the
// build replaces with config/runtime/<profile>.json, and named none of the
// variables a production build needs.
describe("runtime configuration documentation", () => {
it("names every build and deploy variable in the README", () => {
const readme = readFileSync("README.md", "utf8");
for (const variable of [
"APP_PROFILE",
"RELEASE_TARGET",
"VITE_BUILD_ID",
"RELEASE_ID",
...Object.values(RUNTIME_OVERRIDES),
]) {
expect(readme, variable).toContain(`\`${variable}\``);
}
expect(readme).toContain("config/runtime/<profile>.json");
});
});