Make docker-compose.yml enforce the api/enterprise-api binary swap

Closes the local/dev half of a gap named repeatedly across this
phase's docs: Helm already made api/enterprise-api mutually exclusive
(same enterprise.enabled flag that turns on RBAC/audit/SSO, both
rendering to the same Service name/port); docker-compose.yml let both
run side by side, with nothing actually pointing at enterprise-api by
default.

Mechanism: both services now carry a `profiles` entry (single-tenant /
enterprise), selected via COMPOSE_PROFILES -- a new checked-in .env
sets single-tenant as the zero-config default (unchanged behavior for
anyone who doesn't touch it), and `COMPOSE_PROFILES=enterprise docker
compose up` swaps to enterprise-api instead. Docker Compose profiles
are purely additive (no "profile X excludes service Y" primitive), so
true exclusivity comes from both being profile-gated with no shared
default profile, not from one excluding the other directly.

Mirrors Helm's same-Service-name trick so alerting's API_QUERY_URL and
web's VITE_API_BASE_URL need zero conditional logic either way:
enterprise-api now maps host port 8080 (was 8083, its own binary
default -- overridden via HTTP_LISTEN_ADDR) and carries a
`networks.default.aliases: [api]` entry, so whichever binary is
actually running answers on the same compose-network hostname and host
port. alerting's and web's depends_on for api/enterprise-api are now
`required: false` (Compose's supported "optional dependency" shape) --
without it, compose errors on the inactive one rather than just
skipping it, since depends_on doesn't otherwise know about profiles.

Verified for real in this environment via `docker compose config`
(renders and validates the merged YAML without needing a daemon):
confirmed api/enterprise-api never both appear in --services output
for either profile selection, confirmed enterprise-api's rendered
block has port 8080/alias "api"/HTTP_LISTEN_ADDR ":8080" when the
enterprise profile is active, and confirmed `docker compose run
enterprise-api ...`/`docker compose build enterprise-api` (used by
enterprise/README.md's and phase-4-runbook.md's provisioning steps)
still work regardless of the active profile -- explicit service
references bypass profile filtering, confirmed by the commands
reaching a daemon-connection permission error rather than a
profile-resolution error. Not verified: an actual `docker compose up`
against a real daemon, still unavailable in this environment.

Docs updated in lockstep -- CLAUDE.md, threat-model.md (including its
summary table), phase-4-runbook.md (new §10a, §8's provisioning
commands updated for the new port/profile), enterprise/README.md.
This commit is contained in:
2026-08-14 08:17:41 -07:00
parent 2e698f5623
commit 8d7326fc6a
6 changed files with 178 additions and 56 deletions
+16 -8
View File
@@ -284,21 +284,29 @@ membership, listing a tenant's members, or a flag for
## Provisioning a tenant and running `enterprise-api`
`api`/`enterprise-api` are mutually exclusive in `docker-compose.yml`,
gated behind `COMPOSE_PROFILES` (`.env` checks in `single-tenant`, i.e.
plain `api`, as the zero-config default -- mirrors Helm's
`enterprise.enabled` flag). `-provision-tenant` itself doesn't bind a
port, so it runs fine regardless of the active profile; actually
serving traffic on `enterprise-api` needs the `enterprise` profile
active, since it now binds the same host port (8080) plain `api` does
(it gets a `default.aliases: [api]` network alias too, so `alerting`'s
`API_QUERY_URL`/`web`'s `VITE_API_BASE_URL` need zero changes either
way):
```sh
docker compose build enterprise-api # context is the repo root, not enterprise/ -- see cmd/enterprise-api/Dockerfile
docker compose run --rm enterprise-api -provision-tenant=acme -display-name="Acme Corp"
docker compose up -d enterprise-api
curl -s http://localhost:8083/healthz
COMPOSE_PROFILES=enterprise docker compose build enterprise-api # context is the repo root, not enterprise/ -- see cmd/enterprise-api/Dockerfile
COMPOSE_PROFILES=enterprise docker compose run --rm enterprise-api -provision-tenant=acme -display-name="Acme Corp"
COMPOSE_PROFILES=enterprise docker compose up -d enterprise-api
curl -s http://localhost:8080/healthz
```
`-provision-tenant` creates the tenant/data_source rows in rbacstore if
they don't exist, provisions ClickHouse, persists the credentials, and
marks the tenant active -- refuses to run twice for the same tenant
(re-provisioning would either rotate a live credential or silently fail
to, see `tenantprovision.ProvisionClickHouse`'s doc comment). `web`
still points at plain `api` by default (`VITE_API_BASE_URL`) --
pointing it at `enterprise-api` instead is a manual `docker-compose.yml`
edit today, not a supported flag.
to, see `tenantprovision.ProvisionClickHouse`'s doc comment).
## Environment variables (`enterprise-auth`)