ITWorx_MCP_Hub-Public/infrastructure/compose/COMPOSE_REQUIREMENTS.md

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.