Configuration Index
A single-page inventory of runtime configuration grouped by entry-point app. The index is the fast lookup; canonical doctrine lives in the linked ADR or runbook for each row.
Each table has the same shape:
- Env var — the variable name as it appears in code or in Render
- Source — where the value is set: env group, per-service env var, image-baked at build, build-time bundled (frontends), or computed at runtime
- Rotation — when the value changes, and the trigger
- Owning — the canonical ADR or runbook for the value
For the env-group-vs-per-service placement principle see
CD pipeline overview D7 / D8. For the provisioning +
rotation flow see Secrets management and
ADR-037. The two Render Environment Groups
(spectral-staging-runtime, spectral-production-runtime) carry every “env group” row below.
apps/api — FastAPI on Render (api.runspectral.com)
Section titled “apps/api — FastAPI on Render (api.runspectral.com)”Substrate
Section titled “Substrate”| Env var | Source | Rotation | Owning |
|---|---|---|---|
SUPABASE_URL | Env group | Per-environment; set at provisioning | ADR-039 |
SUPABASE_ANON_KEY | Env group | At Supabase JWT-secret rotation | Auth runbook |
SUPABASE_SERVICE_ROLE_KEY | Env group | At Supabase JWT-secret rotation | Auth runbook |
OTEL_EXPORTER_OTLP_ENDPOINT | Env group | Provider migration only | ADR-036 |
SENTRY_DSN | Env group | Provider migration only | ADR-036 |
LOGFIRE_TOKEN | Env group | Provider migration only | ADR-036 |
Per-service (atomic with deploy)
Section titled “Per-service (atomic with deploy)”| Env var | Source | Rotation | Owning |
|---|---|---|---|
SPECTRAL_GENERATION | Per-service (set by GH Actions at deploy) | Bumped per deploy | ADR-048 |
TRUSTED_PROXIES | Per-service | Edge / DNS topology change | Security boundaries |
Deploy-key registry (sk_deploy_*) | Per-service env vars; key-exchange middleware reads at startup | Rotates as deploy side-effect | Deployment topology — version-detail auth |
apps/workers — LangGraph background runtime on Render
Section titled “apps/workers — LangGraph background runtime on Render”Inherits all apps/api substrate vars plus:
Per-service (atomic with deploy)
Section titled “Per-service (atomic with deploy)”| Env var | Source | Rotation | Owning |
|---|---|---|---|
SPECTRAL_GENERATION | Per-service | Bumped per deploy (must match apps/api) | ADR-048 |
HANDLER_MAX | Per-service (default 60s) | Tuning only | Deployment topology — drain |
SPECTRAL_DRAIN_AND_EXIT | Per-service (legacy-drain workflow only) | Set on the temporary drain worker; never on prod workers | Legacy-drain runbook |
SPECTRAL_DRAIN_COOLING_SECONDS | Per-service | Drain-workflow tuning | Legacy-drain runbook |
maxShutdownDelaySeconds is a Render service-config property declared in render.yaml (per ADR-048 D9), not a worker-process env var; the workers do not read it directly.
LLM provider (production)
Section titled “LLM provider (production)”| Env var | Source | Rotation | Owning |
|---|---|---|---|
ANTHROPIC_API_KEY | Env group | Quarterly + on suspected leak | LLM platform |
OPENAI_API_KEY | Env group | Quarterly + on suspected leak | LLM platform |
GOOGLE_API_KEY | Env group | Quarterly + on suspected leak | LLM platform |
apps/dashboard — TanStack Start customer UI on Render (app.runspectral.com)
Section titled “apps/dashboard — TanStack Start customer UI on Render (app.runspectral.com)”Frontend env vars are build-time bundled (Vite reads VITE_* at build, embeds into the
client bundle). Rotation requires a rebuild, not a config flip.
| Env var | Source | Rotation | Owning |
|---|---|---|---|
VITE_API_URL | Env group → built into bundle | Edge / DNS topology change | Frontend architecture |
VITE_SUPABASE_URL | Env group → built into bundle | At Supabase JWT-secret rotation | ADR-039 |
VITE_SUPABASE_ANON_KEY | Env group → built into bundle | At Supabase JWT-secret rotation | ADR-039 |
SUPABASE_SERVICE_ROLE_KEY | Never (server-side only) | n/a | n/a |
Rule: anything sensitive lands at apps/api and is reached through the API proxy. The dashboard
holds only public-facing keys.
apps/operations — TanStack Start staff console on Render (ops.runspectral.com)
Section titled “apps/operations — TanStack Start staff console on Render (ops.runspectral.com)”Same frontend posture as apps/dashboard, plus the Pattern A auth surface:
| Env var | Source | Rotation | Owning |
|---|---|---|---|
VITE_API_URL | Env group → built into bundle | Edge / DNS topology change | Frontend architecture |
VITE_SUPABASE_URL | Env group → built into bundle | At Supabase JWT-secret rotation | ADR-039 |
VITE_SUPABASE_ANON_KEY | Env group → built into bundle | At Supabase JWT-secret rotation | ADR-039 |
OPERATIONS_SCOPES | Per-service (Pattern A middleware reads at startup) | Scope-taxonomy change only | Access control |
docs-codex (Cloudflare Pages, codex.runspectral.com)
Section titled “docs-codex (Cloudflare Pages, codex.runspectral.com)”The Codex docs site is a static Astro build with a Pages Function for JWKS-local auth on operator-only routes.
| Env var | Source | Rotation | Owning |
|---|---|---|---|
OPERATIONS_SCOPES | Cloudflare Pages env (Function reads at request time) | Scope-taxonomy change only | Access control |
SUPABASE_URL | Cloudflare Pages env | At Supabase JWT-secret rotation | ADR-039 |
docs-user (Cloudflare Pages, docs.runspectral.com)
Section titled “docs-user (Cloudflare Pages, docs.runspectral.com)”Public marketing/docs site. No runtime config; all content is statically rendered at build.
retention-run cron (reuses apps/workers image)
Section titled “retention-run cron (reuses apps/workers image)”Inherits the apps/workers env. Posts a single retention.run_scheduled event into the
substrate, then exits. No cron-specific env vars.
backup-nightly cron
Section titled “backup-nightly cron”Required env vars per tools/ops/backup/backup-nightly.sh:
| Env var | Source | Rotation | Owning |
|---|---|---|---|
DATABASE_URL | Env group | At Supabase JWT-secret rotation | Disaster recovery runbook |
AGE_RECIPIENT | Env group | At age-key rotation | Disaster recovery runbook |
GCS_BACKUP_BUCKET | Env group | Bucket migration only | ADR-040 |
GCS_SA_KEY_PATH | Env group (filesystem path to a mounted SA key) | At GCS service-account rotation | Disaster recovery runbook |
BACKUP_RETENTION_DAYS | Env group | At retention-policy change | ADR-040 |
CI secrets (GitHub Actions, not runtime)
Section titled “CI secrets (GitHub Actions, not runtime)”GitHub Environments hold these. Each environment carries required-reviewer = self. See
CI secrets handling runbook and
ADR-062 for rotation procedure.
| Env var | Environment | Used by | Rotation |
|---|---|---|---|
RENDER_API_KEY | staging, production | Deploy workflows | Quarterly |
CLOUDFLARE_API_TOKEN | staging, production | Edge config workflows | Quarterly |
SUPABASE_MANAGEMENT_PAT | staging, production | Migration / preview-branch workflows | Quarterly |
LLM_TEST_ANTHROPIC_KEY | test-live | Nightly LLM live-drift workflow | At provider key rotation |
LLM_TEST_OPENAI_KEY | test-live | Nightly LLM live-drift workflow | At provider key rotation |
LLM_TEST_GOOGLE_KEY | test-live | Nightly LLM live-drift workflow | At provider key rotation |
GITHUB_OAUTH_TEST_CLIENT_* | staging | OAuth integration tests | At OAuth-app rotation |
GOOGLE_OAUTH_TEST_CLIENT_* | staging | OAuth integration tests | At OAuth-app rotation |
Tunables that are code constants, not env vars
Section titled “Tunables that are code constants, not env vars”The following appear in design docs but are set in source code (not configurable per-deploy). Listed here so a reader who searches for them lands somewhere useful:
| Constant | Defined in | Notes |
|---|---|---|
min_size, max_size, max_idle, prepare_threshold, reconnect_timeout | psycopg_pool config in spectral_api.db and spectral_workers.db | See Connection pooling for the alpha defaults |
Session-var names (app.account_id, app.workspace_id, app.user_id) | spectral.core.db.session_vars | Pinned by RLS contract tests |
See also
Section titled “See also”- Hosting — which env group each service reads
- Secrets management — provisioning + rotation flow
- CD pipeline overview — env-group vs per-service placement principle
- ADR-037 — provisioning architecture and target-swap discipline
- Secrets management runbook — the operational rotation procedure