INFRA.md

Infra

Directory layout for local and containerized run of the Boilerplate stack (aligned with podverse monorepo conventions). Includes Docker local infra and a k3d/k3s + ArgoCD deployment scaffold.

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/LOCAL-ENV-OVERRIDES.md.
• database/ – Postgres init: numbered migrations in database/migrations/ (e.g. 0000_init_helpers.sql, 0001_users.sql). Run scripts/database/combine-migrations.sh to generate infra/k8s/base/stack/postgres-init/0003_app_schema.sql (single committed combined SQL under k8s); do not edit that file by hand. Local Docker still uses database/combined/01_create_users.sh and seed_local_user.sql with that schema file. Combined schema runs on first Postgres start.
• management-database/ – Same convention as database/; see Management database below.
• 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 boilerplate_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 and Argo CD scaffold:
  • base/ reusable manifests (per-component bases for remote GitOps + base/stack/ for local)
  • local/ k3d local overlay and child apps
  • alpha/ docs-only remote-env placeholder (no root Argo app in this repo)
  • root manifests: argocd-project.yaml, local-application.yaml (non-local Argo apps live in your GitOps repo; see docs/development/ARGOCD-GITOPS-BOILERPLATE.md)
  • see k8s/INFRA-K8S.md and docs/development/K3D-ARGOCD-LOCAL.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.

Layout (same as database/): Migrations in management-database/migrations/; run scripts/database/combine-migrations.sh to regenerate infra/k8s/base/stack/postgres-init/0005_management_schema.sql.frag (and the main-app 0003_app_schema.sql). Do not edit the generated combined files by hand.

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/stack/postgres-init/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 classification 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 @boilerplate/management-orm: TypeORM access layer for this store. Initialize managementDataSource, then use ManagementUserService, ManagementEventService, and entities. The management API depends on this package.