INFRA.md

Infra

Directory layout for local and containerized run of the Metaboost stack. Includes Docker local infra and Kubernetes bases / alpha app-of-apps manifests for GitOps.

Layout

• config/env-templates/ – Template env files (api.env.example, web.env.example, etc.) for API and web. Canonical app-level templates live under apps/*/.env.example.
• config/local/ – Local env files (gitignored); generated by make local_env_setup (secrets auto-generated; override files in dev/env-overrides/local/ are optional and not used by default). Required for Docker: run make local_env_setup before docker compose up. See docs/development/env/LOCAL-ENV-OVERRIDES.md. All env keys from templates/examples (defaults and K8s wiring): docs/development/env/ENV-VARS-REFERENCE.md.
• database/ – Deprecated legacy location; canonical SQL now lives under infra/k8s/base/db/source/.
• management-database/ – Deprecated legacy location; canonical management schema now lives under infra/k8s/base/db/source/0005_management_schema.sql.frag.
• docker/local/ – Dockerfiles and docker-compose for api, web, sidecar, postgres, and valkey. Combined stack (from repo root): docker compose -f infra/docker/local/docker-compose.yml --project-directory . up --build. Shared network metaboost_local_network is created on first up. Run make local_env_setup to generate infra/config/local/*.env (including postgres and valkey split files: db-source-only.env, db.env, … and valkey-source-only.env, valkey.env).
• k8s/ – Kubernetes manifests for GitOps consumption:
  • base/ reusable per-component bases (remote GitOps)
  • alpha/ in-repo alpha app-of-apps and child overlays
  • optional root argocd-project.yaml (see k8s/INFRA-K8S.md; environment Application CRs usually live in your GitOps repo — docs/development/k8s/ARGOCD-GITOPS-METABOOST.md)
  • see k8s/INFRA-K8S.md and docs/development/k8s/REMOTE-K8S-GITOPS.md

Management database

Dedicated store for management identities, permissions, and audit events. The main app Postgres is not used for this; the management API uses this store for super admin, admins, permissions, and management_events, and uses the main DB only for main-system user CRUD.

Canonical schema location: infra/k8s/base/db/source/ (0003_app_schema.sql for main app and 0005_management_schema.sql.frag for management).

Postgres (second database): Create a second database (e.g. management_db) on the same server as the main app. One-time: psql -h HOST -p PORT -U USER -d postgres -c "CREATE DATABASE management_db;" then run psql ... -d management_db -f infra/k8s/base/db/source/0005_management_schema.sql.frag. Management-api connects with the same DB_HOST / DB_PORT as the main API plus DB_MANAGEMENT_NAME and DB_MANAGEMENT_READ_WRITE_USER / DB_MANAGEMENT_READ_WRITE_PASSWORD (see env configuration db.db-management). The same Postgres container can host both databases.

Schema: management_user (super admin singleton + admins; no email/password on main table), management_user_credentials (1:1: email, password_hash), management_user_bio (1:1: display_name), admin_permissions (admins_crud and users_crud as 0–15 CRUD bitmasks; can_change_passwords, can_assign_permissions, event_visibility), management_event (audit log). Only the management API (and management-web via that API) use this store.

Package @metaboost/management-orm: TypeORM access layer for this store. Initialize managementDataSource, then use ManagementUserService, ManagementEventService, and entities. The management API depends on this package.