Skip to content

LOCAL-ENV-OVERRIDES.md

Latest commit

 

History

History
77 lines (58 loc) · 9.52 KB

LOCAL-ENV-OVERRIDES.md

File metadata and controls

77 lines (58 loc) · 9.52 KB

Local Env Overrides (Home Directory)

For the full classified variable list with expected defaults and where each key appears in Kubernetes, see ENV-VARS-CATALOG.md.

Secrets (API and management API JWT, DB, Valkey, etc.) are auto-generated by make local_env_setup in scripts/local-env/setup.sh using the same approach as Podverse: hex for passwords (generate_hex_32), UUID for JWT (generate_uuid), and first_non_empty_or_generate to reuse existing values across runs. Postgres env is a single merged file: infra/config/local/db.env holds all classification db env group keys (single flat vars block in base.yaml, including DB_MANAGEMENT_SUPERUSER_* with override_file: db_management_superuser), generated by merge-env --profile local_docker --group db. Docker Compose uses --env-file infra/config/local/db.env for the postgres service and for compose variable interpolation so DB_USER / DB_PASSWORD / DB_APP_NAME can bridge to the official image’s POSTGRES_* vars. API and management-api get different JWT secrets (API_JWT_SECRET and MANAGEMENT_API_JWT_SECRET). scripts/env-setup-secrets.sh only sets host connection defaults (e.g. DB_HOST=localhost, ports). Canonical override examples live in dev/env-overrides/examples/*.env.example (one set for all flows). Working override files consumed by setup and by K8s render live under dev/env-overrides/local/*.env (and dev/env-overrides/alpha/*.env after link). Those files are used for customizable values: management superuser, app/legal display names (info.env: WEB_BRAND_NAME, LEGAL_NAME, MANAGEMENT_WEB_BRAND_NAME), auth mode, locale (sensible defaults), and mailer (no defaults — bring your own SMTP; tests use mailpit). The prepare/link/setup flow and home-directory layout align with Podverse. WEB_BASE_URL, WEB_URL and CORS allowlists (API_CORS_ORIGINS on api.vars, MANAGEMENT_API_CORS_ORIGINS on management-api.vars, with local defaults aligned to http web URLs) stay in generated env (not in home overrides). Web and management-web app .env.example files contain only RUNTIME_CONFIG_URL; the full list is in the sidecar env templates (sidecar env templates under each app’s sidecar/ directory when present). Two outputs — same classification workloads, different merge profiles: infra/config/local/web-sidecar.env and infra/config/local/management-web-sidecar.env are merge-env --profile local_docker for Docker Compose only (internal API_SERVER_BASE_URL / MANAGEMENT_API_SERVER_BASE_URL). apps/web/sidecar/.env and apps/management-web/sidecar/.env are merge-env --profile dev (same host profile as apps/web/.env.local / apps/management-web/.env.local) for npm run dev:all and runtime-config sidecars; they are not copied from infra. Host processes load sidecar env via DOTENV_CONFIG_PATH=sidecar/.env (see dev:sidecar in each app’s package.json). make local_env_clean removes generated sidecar/.env files along with other generated app env files.

Sidecars validate env at startup (Podverse-style): missing or invalid required vars exit non-zero; GET /runtime-config returns 500 with missingKeys if required values are absent.

Recommended flow (one consistent process)

  1. Setup — Generate app and infra env files (secrets generated in setup.sh when empty, then host defaults set by env-setup-secrets.sh; overrides from info.env, db-management-superuser.env, mailer.env, auth.env, and locale.env applied when present):

    make local_env_setup

  2. Start infrastructure — Start Postgres, Valkey, create management DB, and create super admin:

    make local_infra_up

Alternatively, run make local_setup once: it runs local_env_setup and local_infra_up in order.

Prepare and link (optional): To use a single set of overrides across work trees, run make local_env_prepare (seeds ~/.config/metaboost/local-env-overrides/*.env from dev/env-overrides/examples/*.env.example via prepare-local-env-overrides.sh → prepare-home-env-overrides.sh), edit those files, then make local_env_link and make local_env_setup. When no example files exist under dev/env-overrides/examples/, prepare and link exit successfully with a short message (no-op).

Override files and which apps they affect

Override file Apps / env files that receive its values
db-management-superuser.env infra/config/local/db.env, apps/management-api/.env, infra/config/local/management-api.env (DB_MANAGEMENT_SUPERUSER_USERNAME, DB_MANAGEMENT_SUPERUSER_PASSWORD) — bootstrap for scripts/management-api/create-super-admin.mjs only; they do not set Docker POSTGRES_*. When both are set after local_env_setup, make local_infra_up runs that script non-interactively (no TTY prompt).
info.env WEB_BRAND_NAME (API transactional email + web UI via NEXT_PUBLIC_WEB_BRAND_NAME on web-sidecar), LEGAL_NAME (Terms first-sentence interpolation via NEXT_PUBLIC_LEGAL_NAME), MANAGEMENT_WEB_BRAND_NAME (management-web UI via NEXT_PUBLIC_MANAGEMENT_WEB_BRAND_NAME on management-web-sidecar). Do not set the NEXT_PUBLIC_* keys in overrides; merge-env / setup.sh sync them from the canonical keys.
mailer.env API (MAILER_HOST, MAILER_PORT, MAILER_FROM, MAILER_USER, MAILER_PASSWORD). No classification defaults — bring your own SMTP; local tests use Mailpit without auth.
auth.env AUTH_MODE (env group auth): API, management-api, and web (NEXT_PUBLIC_AUTH_MODE via scripts/local-env/setup.sh). Sensible default in example (admin_only_username).
locale.env API, web, management-api, management-web including sidecars (DEFAULT_LOCALE, SUPPORTED_LOCALES). Single source—do not set in other override files. Example: en-US, all-available.

Mailer: SMTP authentication (Brevo, SendGrid, Mailpit)

For AUTH_MODE values that send email (admin_only_email, user_signup_email), the API uses Nodemailer SMTP. MAILER_USER and MAILER_PASSWORD are optional as a pair: leave both empty for an open relay or Mailpit (no AUTH). For authenticated SMTP (e.g. Brevo), set both — Brevo uses host smtp-relay.brevo.com, port 587, MAILER_USER = your Brevo SMTP login, MAILER_PASSWORD = your Brevo SMTP key, and MAILER_FROM = a verified sender. Startup validation fails if only one of MAILER_USER / MAILER_PASSWORD is set.

Default location (for future overrides)

Override files live in:

  • Default: ~/.config/metaboost/local-env-overrides/
  • Override: set METABOOST_HOME_OVERRIDES_DIR to a different path.

See also

  • QUICK-START.md – Full local setup.
  • K3D-ARGOCD-LOCAL.md – k3d + ArgoCD local stack; includes troubleshooting for "password authentication failed for user metaboost_app_read" (e.g. after changing DB passwords or recreating env) and make local_k3d_postgres_reset.
  • K8S-ENV-RENDER.md – Render ConfigMaps and Secrets for alpha/beta/prod K8s from the same .env.example contract (make alpha_env_render, dev/env-overrides/<env>/).
  • make local_env_clean – Removes generated env files under infra/config/local/ and app .env/.env.local files, but keeps dev/env-overrides/local/ (and symlinks if present) intact. Uses repo root so it works no matter which directory you run make from. Aborts if local Docker Compose or k3d cluster is running; run make local_down and/or make local_k3d_down first.