ADR-006 — Environment Variables

Status

Accepted

Context

The project needs environment variables to configure the database, security, CORS, and auth. Some are common to all environments, others are exclusive to local development, and others only exist in production. Mixing them or not documenting the separation leads to incomplete .env files or secrets accidentally committed to the repository.

Decision

A single .env at the project root (copied from .env.example). Docker Compose injects it into the api container. The Angular frontend does not use .env — build variables are configured in Amplify Console in production.

Common (dev and prod). Variables required in all environments.

Variable	Description	Default dev
`DJANGO_SETTINGS_MODULE`	Active settings module	`config.settings.local`
`POSTGRES_DB`	Database name	`kdx_ng`
`POSTGRES_USER`	PostgreSQL user	`kdx_ng`
`POSTGRES_PASSWORD`	PostgreSQL password	`kdx_ng`
`POSTGRES_HOST`	Database host	`db` (Docker)
`POSTGRES_PORT`	PostgreSQL port	`5432`
`LOCAL`	`True`/`False` flag — affects cookies and CSP	`True`
`CORS_ALLOWED_ORIGINS`	CORS origins, comma-separated	`http://localhost:4200`
`COVERIS_PAGE_SIZE`	DRF pagination page size	`25`

Development only. Variables exclusive to local dev; not present in production.

Variable	Description	Default dev
`DJANGO_SECRET_KEY`	Django secret key	auto-generated (warning)
`SUPERUSER_PASSWORD`	Password for the superuser created at boot	`localdev123`
`SUPERUSER_EMAIL`	Superuser email	required
`SUPERUSER_GIVEN_NAME`	Superuser first name	required
`SUPERUSER_FAMILY_NAME`	Superuser last name	required
`MOCK_USER_PASSWORD`	Password for seeded mock users	`clinic2026!`

[!note] Dev secret key & superuser bootstrap DJANGO_SECRET_KEY is optional in dev — if not set, Django generates one in memory with a warning. Sessions do not persist between container restarts.

SUPERUSER_EMAIL, SUPERUSER_GIVEN_NAME, and SUPERUSER_FAMILY_NAME have no fallback defaults — the create_superuser command fails if they are missing. Recommended values are provided in .env.example.

Production only. Variables injected by AWS infrastructure ([[adr-003-a-backend-prod-stack|ADR-003-a]], [[adr-008-authentication|ADR-008]]); never set in .env.

Variable	Description	Source
`DJANGO_SECRET_KEY`	Django secret key	AWS Secrets Manager
`ALLOWED_HOSTS`	Allowed hosts, comma-separated	App Runner env vars
`POSTGRES_HOST`	RDS endpoint	AWS Secrets Manager
`POSTGRES_PASSWORD`	RDS password	AWS Secrets Manager
`WEB_CONCURRENCY`	Uvicorn worker count	App Runner env vars
`COGNITO_USER_POOL_ID`	Cognito User Pool ID	App Runner env vars
`COGNITO_CLIENT_ID`	Cognito Client ID	App Runner env vars
`COGNITO_REGION`	AWS region for Cognito	App Runner env vars

[!note] Production settings In production, DJANGO_SETTINGS_MODULE=config.settings.production and LOCAL=False.

ALLOWED_HOSTS is only read from the environment in production settings. In development, it is hardcoded in local.py.

Consequences

.env is never committed — it is in .gitignore. Only .env.example lives in the repository.
The Angular frontend has no .env; in production, build variables are injected in Amplify Console as NG_APP_* and accessed from environment.prod.ts.
Any new variable must appear first in .env.example (with a dev value) and in this ADR before being used in code.