openclaw-mission-control/docs/06-configuration.md

Configuration

This page documents where configuration comes from, the key environment variables, and a couple operational footguns (migrations, CORS).

For deployment/production patterns, see:

• Deployment
• Production

Configuration sources & precedence

Mission Control is a 3-service stack (compose.yml): Postgres (db), backend (backend), frontend (frontend).

Docker Compose (recommended for local/self-host)

Common pattern:

cp .env.example .env

docker compose -f compose.yml --env-file .env up -d --build

Precedence (high → low):

1. Environment exported in your shell (or -e NAME=value)
2. Compose --env-file .env (variable interpolation)
3. Defaults in compose.yml (e.g. ${BACKEND_PORT:-8000})
4. Backend defaults via env_file: ./backend/.env.example
5. Frontend optional user-managed frontend/.env

Note: Compose intentionally does not load frontend/.env.example to avoid placeholder Clerk keys accidentally enabling Clerk.

Backend env-file loading (non-Compose)

Evidence: backend/app/core/config.py.

When running the backend directly (uvicorn), settings are loaded from:

• backend/.env (always attempted)
• .env (repo root; optional)
• plus process env vars

Environment variables (grouped)

Root .env (Compose-level)

Template: .env.example.

• Ports: FRONTEND_PORT, BACKEND_PORT, POSTGRES_PORT
• Postgres defaults: POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD
• Backend knobs: CORS_ORIGINS, DB_AUTO_MIGRATE
• Frontend: NEXT_PUBLIC_API_URL (required)

Backend

Template: backend/.env.example + settings model backend/app/core/config.py.

• ENVIRONMENT
• LOG_LEVEL
• DATABASE_URL
• CORS_ORIGINS
• DB_AUTO_MIGRATE

Clerk:

• CLERK_SECRET_KEY (required; backend enforces non-empty)
• CLERK_API_URL, CLERK_VERIFY_IAT, CLERK_LEEWAY

Frontend

Template: frontend/.env.example.

Variable	Required?	Purpose	Default / example	Footguns
NEXT_PUBLIC_API_URL	yes	Backend base URL used by the browser	http://localhost:8000	Must be browser-reachable
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY	yes	Enables Clerk in the frontend	(none)	Must be a real publishable key
NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL	optional	Fallback redirect	/boards	—
NEXT_PUBLIC_CLERK_AFTER_SIGN_OUT_URL	optional	Post-logout redirect	/	—

Minimal dev configuration

Split-mode dev (fastest contributor loop)

• Start DB via Compose.
• Run backend+frontend dev servers.

See Development.

Migrations (DB_AUTO_MIGRATE)

Evidence: backend/app/db/session.py.

On backend startup:

• if DB_AUTO_MIGRATE=true and migrations exist under backend/migrations/versions/, backend runs alembic upgrade head.
• otherwise it falls back to SQLModel.metadata.create_all.

Operational guidance:

• Auto-migrate is convenient on a single host.
• In multi-instance deployments, prefer running migrations as an explicit deploy step to avoid race conditions.

CORS (CORS_ORIGINS)

Evidence: backend/app/main.py, backend/app/core/config.py.

• CORS_ORIGINS is a comma-separated list.
• It must include the frontend origin (e.g. http://localhost:3000) or browser requests will fail.

Common footguns

• Frontend env template vs runtime env: frontend/.env.example is a template and compose.yml intentionally does not load it at runtime. Use user-managed frontend/.env (for Compose) or frontend/.env.local (for Next dev).
• NEXT_PUBLIC_API_URL reachability: must work from the browser’s network context (host), not only from within the Docker network.

Troubleshooting config issues

• UI loads but API calls fail / Activity feed blank → NEXT_PUBLIC_API_URL is missing/incorrect.
• Backend fails at startup → check required env vars (notably CLERK_SECRET_KEY) and migrations.

See also: docs/troubleshooting/README.md.