Environment Files

The repo keeps local developer env files next to the runtime that reads them. Real local files are ignored; .env.example files are the tracked contract for each runtime.

Area	Tracked template	Ignored local file	Loaded by	Production source
Backend API	backend/.env.example	backend/.env	Go backend when run from backend/	ECS task environment plus APP_SECRET_JSON from Secrets Manager
Frontend portal	frontend/portal/.env.example	frontend/portal/.env.local	Vite	GitHub Actions build env, sourced from repository variables/secrets
Pipelines	pipelines/.env.example	pipelines/.env	pipelines/run_all.py and the Go ingestion adapter	Scheduler/container env or secret manager for the runner
Agent hooks extension	none	.oliver/agent-hooks/config.json	extensions/agent-hooks install/runtime code	User/repo config plus process env overrides
Chrome extension	none	browser extension storage	extension runtime	packaged extension configuration

Rules

• Keep .env and .env.local files local only. The root .gitignore ignores them and allows only .env.example.
• Put shared local defaults in the matching .env.example; put machine-specific values in the ignored local file.
• A local env file can contain fewer variables than its example. Missing optional values should fall back to code defaults.
• Use VITE_* only for browser-safe frontend values. Anything sensitive belongs in the backend, pipelines, or deployment secret store.
• Do not add production-only secrets to local examples unless the service also needs a local placeholder.

Local Defaults

• scripts/start-local-stack.sh runs the backend API on API_PORT=8081, the frontend on FRONTEND_PORT=5173, and the docs site on DOCS_PORT=3000 by default.
• The local docs server uses DOCS_ENV=local, so it includes both public docs and internal docs under /internal/.
• frontend/portal/.env.example sets VITE_OLIVER_API=http://127.0.0.1:8081 so direct Vite runs point at the same backend port.
• pipelines/.env.example sets CONTEXT_LAYER_API=http://127.0.0.1:8081 for the same reason.

Deployment

Deployment config should not read local .env files. Terraform owns infrastructure shape, GitHub repository variables provide public build-time values, and sensitive backend values live in Secrets Manager as the JSON value injected through APP_SECRET_JSON.