Initial curated ITWorx_MCP_Hub source from 368fba691ea8d23403b4d56b53b5ec670d7c5020

infrastructure/compose/COMPOSE_REQUIREMENTS.md

@@ -0,0 +1,52 @@
+# 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.