DOCS / UWA V1 RELEASE CONTRACT SELF-HOSTED GATEWAY
Configuration
Understand runtime environment variables, release profiles and offline preflight checks.
On this page 3 sections
#Core environment
| Variable | Purpose |
|---|---|
APP_ENV | development / staging / production profiles |
APP_RELEASE_PROFILE | lean_v1 (default, required in prod/staging) or full_experimental (dev/test only) |
APP_BIND_HOST | 127.0.0.1 by default |
APP_PORT | 8080 by default |
APP_DB_DRIVER | memory for local dev, postgres required in production |
APP_DATABASE_URL | PostgreSQL DSN for durable client key storage |
APP_CACHE_DRIVER | memory for local dev, redis required in production/staging |
APP_SECRET_DRIVER | chained, file, env or memory |
APP_PROVIDER_POLICY_FILE | Operator-reviewed JSON provider policy |
APP_DEPLOYMENT_USE | noncommercial or commercial classification for vendor rules |
APP_COUNTRY_POLYGONS_FILE | Verified country polygon data for regional coverage |
APP_PROVIDER_QUOTAS_JSON | Explicit usage budgets (required for every active provider in prod/staging) |
APP_WEATHER_PLACE_RESOLVER | Set to strict to enable place-name resolution on weather, forecast & /v1/datasets |
APP_METRICS_MODE | off (default) or loopback (requires 127.0.0.1 bind and APP_METRICS_TOKEN) |
APP_METRICS_TOKEN | Bearer secret (>=32 chars) required when APP_METRICS_MODE=loopback |
APP_TRUSTED_PROXY_CIDRS | Optional bounded CIDR allowlist (max 16) for right-to-left X-Forwarded-For parsing |
APP_DEV_CLIENT_KEY | Optional local dev client key (24–512 chars, loopback + memory dev only) |
#Offline preflight and doctor checks
go run ./cmd/gateway --check-config
go run ./cmd/uapctl doctor --json
go run ./cmd/uapctl validate-policy --file configs/provider-policy.example.json--check-config constructs the exact credential-dependent provider registry used at startup (without outbound network calls) and verifies that every configured provider has an explicit quota budget in production/staging. uapctl doctor --json independently audits Redis and quota configuration.
#Restricted hosted products
Hosted Open-Meteo forecast, geocoding, air quality, history and marine adapters require APP_DEPLOYMENT_USE=noncommercial, explicit product enablement flags, and reviewed shared quota budgets. Air quality, history, marine, alerts, US NWS, Bright Sky and public Nominatim are deferred in lean_v1 and require APP_RELEASE_PROFILE=full_experimental in development/test.
Canonical contracts:
docs/openapi.yaml (lean_v1) and docs/openapi.experimental.yaml · Verify against your build before production use.