Compose profiles and CLI
Which compose profile starts what, which overlay file changes what, and the make targets and update flags an operator runs on a direct install.
- Version: 0.4
- Role: admin_user
- Type: reference
The commands on this page apply to a direct install — CID222 running from the compose files on a host you administer.
Warning
An appliance runs a rendered release compose file placed by the signed release, and its lifecycle belongs to the updater on its host. Do not run these commands on an appliance: use Settings → System Updates instead. See Update the appliance.
Profiles
A service with no profile starts on a plain docker compose up -d. A profile is additive — it
starts its services alongside the defaults rather than replacing them. Which service belongs to
which profile is generated in services, ports and profiles.
| Profile | Starts | Use it when |
|---|---|---|
| (none) | The 19 services that make up the product | Always |
llm-analyst | risk-analyst, mcp-server | You run the LLM Risk Analyst. Enterprise tier |
inline-proxy | cid-inline-proxy | CID222 is the forward proxy for client browsers |
userid-agent | cid-userid-agent | You attribute inspected traffic to Active Directory users |
routing | cost-analyzer | You run cost-based model routing |
gpu | ocr-service-gpu | You have an NVIDIA card and want the transformer OCR engine |
llm | llm-inference | The analyst's model engine runs on this host rather than a separate GPU machine |
llm-build | weights-fetch | You are building the analyst model bundle, not serving it |
tools | pgadmin, redis-commander | Development only. Both expose a database console |
ldap-test | openldap-test | Development only — a throwaway directory to test LDAP against |
mailtest | mailpit | Development only — captures outbound mail instead of sending it |
Danger
Never start tools, ldap-test or mailtest on a production host. pgadmin and
redis-commander are unauthenticated consoles onto the product's own data, and a release
compose deliberately never ships mailpit.
Compose files
The base file is always first; an overlay is added with a second -f.
| File | What it changes |
|---|---|
docker-compose.yml | The base stack. Every secret is a ${VAR:-default} placeholder, so it starts without an environment file |
docker-compose.dev.yml | Development overlay: volume mounts, watch mode, and the only place that opts back into schema auto-sync |
docker-compose.prod.yml | Production overlay: nginx for the dashboard, no host port mappings on internal services, Caddy for TLS. Needs Docker Compose 2.20 or newer |
docker-compose.public.yml | The public-facing deploy overlay used by deploy-public.sh |
docker-compose.gpu.yml | Rebuilds ocr-service to run PaddleOCR on CUDA |
docker-compose.llm-gpu.yml | The analyst model engine on a GPU host |
docker-compose.llm-build.yml | Builds the analyst model bundle |
Make targets
make help prints the full list. These are the ones an operator uses.
| Target | Does |
|---|---|
make first-run | Build every image, then start the stack |
make up / make down | Start / stop |
make restart | Restart, then report health |
make status | Container status |
make health | Health state per container |
make stats | Live resource usage |
make logs / make logs-api | Follow all logs / the gateway's logs |
make shell-api | A shell inside the gateway container |
make update-smart | Rebuild only the services whose code changed |
make update-api / make update-dashboard / make update-ml | Rebuild one service |
make rebuild | Rebuild every image with no cache |
make update-db | Apply pending database migrations |
make migration-status | List applied and pending migrations |
make migration-verify | Apply the whole chain to throwaway copies of an empty database and of this box's schema, and assert nothing is lost |
make migration-baseline | Stamp the initial schema on a database that predates migrations |
make schema-drift | Report entity-versus-schema drift; silence means none |
make seed | Run the database seeder |
make check-licenses | Refuse AGPL, GPL and SSPL dependencies |
make sbom | A CycloneDX software bill of materials per shipped image |
make airgap-verify | Run real OCR with the network disabled, to prove the models are in the image |
Warning
make seed and make update-db-reseed run the full seeder, which resets seeded account
passwords. They are for a development or hub box. Never run either against a production
installation.
Updating a direct install
./update.sh is the supported in-place update. It refuses a dirty git working tree, pulls the
tracked branch, maps the changed paths to compose services, takes a pg_dump, rebuilds only what
changed, recreates those containers, and waits for the health checks.
| Flag | Effect |
|---|---|
| (none) | Pull, then rebuild only the services whose source changed |
--full | Rebuild every service. Use after a large infrastructure change |
--no-pull | Rebuild from the current checkout without pulling |
--branch <name> | Check that branch out first |
--skip-backup | Skip the database dump. Faster, and it removes the only thing the failure path restores from |
| Exit code | Means |
|---|---|
0 | Success |
2 | The working tree is dirty; nothing was done |
3 | The pull failed |
4 | A build failed |
5 | The health wait timed out. The database was restored from the dump; the new containers were left running so their logs survive |
Backups are written to ./backups and the last 14 are kept. The location is a shell variable of
the script rather than a product setting: set a backup directory in the environment you run
./update.sh from to override it.
Notes
- Ports in the generated table are host-side. Inside the compose network services address each other by service name, on a port that is not always the same number.
- A profile is opt-in, never opt-out. There is no profile that removes a default service; to run without one, stop it.
- The GPU paths are mutually exclusive.
docker-compose.gpu.ymlrebuildsocr-serviceon CUDA, while thegpuprofile'socr-service-gputakes over the same container name with a different engine. Run one or the other. See resource sizing.
Related
- Services, ports and profiles — the generated service table.
- Environment variables — the settings these commands read.
- Requirements and sizing — what the host needs before any of this runs.
Last updated on