# Docker Compose implementation requirements

`docker-compose.blueprint.yml` is an executable architecture blueprint, not a release manifest. `WP-020` must replace every `:?` image variable with an exact tag **and digest**, build local images, and generate a validated production override.

## Compose project

- fixed project name: `itworx-mcp-hub`;
- dedicated appdata root, default proposal: `/srv/example/appdata/itworx-mcp-hub`;
- no modification of unrelated containers, networks, volumes, or proxy hosts;
- no service uses `network_mode: host`;
- only the explicit management, dataplane, and optional Inspector bindings may publish host ports;
- PostgreSQL, Redis, ContextForge, workers, connectors, and broker remain internal;
- all local services run non-root, drop Linux capabilities, use `no-new-privileges`, and use a read-only root filesystem where practical;
- each service has bounded memory/CPU/logging and a real healthcheck;
- startup ordering uses health conditions but applications must still tolerate dependency restarts;
- Redis is non-authoritative and may be emptied without data loss;
- the Docker socket is mounted only into `docker-read-broker`, read-only;
- target-system credentials are Compose secrets or equivalent mounted files, never normal environment values;
- release deployments use immutable image digests and record them in release evidence.

## Required profiles

- default/core: production Hub services;
- `project-connectors`: optional connectors requiring external project credentials;
- `inspector`: MCP Inspector bound to an explicitly configured LAN address only;
- `observability`: optional OTel Collector/Grafana stack if not reusing existing services;
- `fake`: deterministic fake targets for clean-room acceptance.

## Required generated outputs in WP-020

- `docker-compose.yml` or an equivalent production base;
- Unraid-specific override;
- development/fake override;
- exact `.env.example` without secrets;
- all Dockerfiles and healthchecks;
- `docker compose config` evidence;
- image pin/digest inventory;
- network and published-port assertion tests.

## Production build-fallback (WP-200 / DIAG-02)

`docker-compose.prod.yml` must cancel every owned service's inherited `build:`
block using the Compose Specification's `!reset` YAML tag — `build: !reset
null` — never plain `build: null`. Plain `null` is not treated as "delete
this key" by the real Compose merge engine; the base file's `build:` mapping
survives and `docker compose up -d` will attempt a local build (and fail in a
confusing way, or in the worst case succeed and deploy an unscanned image)
if a registry pull ever fails. `tests/test_compose.py`'s
`test_real_compose_config_has_no_build_for_owned_services` enforces this
against the real `docker compose config` CLI output; any new owned service
added to `docker-compose.prod.yml` must be added to that test's service list
and use the same `!reset` pattern.