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:
co-authored by
Claude Opus 5.5
parent
a55a15861e
commit
2ba880c7e2
@@ -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
|
||||
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
|
||||
@@ -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");
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user