53 lines
2.9 KiB
Markdown
53 lines
2.9 KiB
Markdown
# 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.
|