Config Env Contract Check

Config Env Contract Check

Use this skill when a change touches environment variables, deployment paths, Docker, Compose, settings APIs, or docs that describe configuration.

Contract Surfaces

Check these files when present:

• .env.example
• docker-compose.yml
• Dockerfile
• frontend/Dockerfile
• backend/app/config.py
• backend/app/api/routes/settings.py
• frontend/src/lib/api.ts
• frontend/src/lib/paths.ts
• frontend/vite.config.ts
• frontend/vite.paths.ts
• frontend/src/stores/useSettingsStore.ts
• scripts/check_config_contract.py ← CI contract enforcer; must be updated atomically with env var defaults
• scripts/validate_vite_env.mjs ← Build-time frontend env validator; must stay in sync with inline Dockerfile validation
• README.md
• INSTALLATION.md
• docs/admin-guide.md
• .github/workflows/ci.yml

Required Checks

• Defaults match between runtime config and deployment examples.
• Docker Compose defaults do not narrow application defaults unexpectedly.
• Frontend build-time env values and backend runtime env values are coordinated.
• Public path prefixes keep APP_ROOT_PATH, VITE_APP_BASENAME, and VITE_API_URL aligned.
• Security-sensitive placeholders are documented and rejected or validated by runtime config.
• Docs examples match the actual env names consumed by code.
• Tests cover parser edge cases for new config formats.

Atomicity rule for env var default changes

When changing a default value for any env var that appears across the deployment stack, all of the following surfaces MUST be updated in the same commit:

1. .env.example — example/documentation value
2. docker-compose.yml — Compose default
3. Dockerfile (root) — build-stage default
4. frontend/Dockerfile — frontend build-stage default
5. scripts/check_config_contract.py — CI contract assertion

Missing any one of these causes scripts/check_config_contract.py to fail in CI with a mismatch error that is hard to diagnose without knowing all five surfaces must agree. The script itself is part of the contract, not just an observer of it.

Additionally: the inline validation in frontend/Dockerfile and the standalone scripts/validate_vite_env.mjs must implement identical validation rules. If you add or relax a check in one, update the other.

Automation

Run the repo contract check when relevant:

python scripts/check_config_contract.py

If the script fails, treat it as a config contract regression unless the script itself is stale and the intended contract has changed.

Output

Report findings as:

Contract:
Owner:
Consumers:
Status: CONFIRMED / DISPROVED / UNVERIFIED
Evidence:
Fix: