fix(docker): drop Swarm-oriented deploy: keys so the stack deploys on NAS platforms - #108

A user reported that the deploy: resource limits prevent deployment on their NAS. Synology Container Manager and QNAP Container Station reject or mishandle the Swarm-oriented deploy: block, so docker/docker-compose.yml would not deploy there at all — even though Compose v2 honours it standalone.

The limits are a CIS-baseline hardening measure, so they were re-expressed rather than removed.

What was there

deploy: appeared on all three services, only ever as resources (no replicas, restart_policy, placement, update_config). A fourth copy sat in the README's paste-in stack.

What changed

Memory limits stay on by default, written with the portable mem_limit / mem_reservation keys that every Compose implementation accepts. Memory is the containment control that matters most here: it bounds the OOM blast radius, and the RAM-backed /tmp tmpfs is charged against it. No opt-in required.

CPU limits moved to a new opt-in overlay, docker/docker-compose.cpu-limits.yml, applied with a second -f:

docker compose -f docker/docker-compose.yml \
               -f docker/docker-compose.cpu-limits.yml up -d

They were moved rather than deleted: the caps are tuned, and the 0.5 on docker-socket-proxy is deliberate — that sidecar is the only container in the stack that mounts docker.sock, and its cap is the documented bound on a wedged or runaway proxy. CPU exhaustion degrades where memory exhaustion kills, which is what makes CPU the right half to make opt-in.

Two things the implementation turned up

The overlay can't use deploy:. The first draft did, on the reasoning that opting in implies a platform that supports it. docker compose config rejected the merged project:

services.scrye: can't set distinct values on 'mem_limit' and 'deploy.resources.limits.memory'

Compose normalizes mem_limit and deploy.resources.limits.memory into one field and validates that they agree, so an overlay contributing a deploy.resources.limits map with no memory in it conflicts with the base file's mem_limit. The overlay would not have applied at all. The portable cpus: key merges cleanly and is accepted by more implementations besides.

cpus: is the same limit, not a weaker one — verified rather than assumed. Compose enforces the identical normalization for CPU: a service setting both cpus: 2.0 and deploy.resources.limits.cpus: "3.0" is rejected with can't set distinct values on 'cpus' and 'deploy.resources.limits.cpus', and setting both to the same value normalizes to one limit. A key that were merely parsed and ignored could not participate in that check.

Verification

docker compose config was run on all four combinations — base alone and base + overlay, each with no profiles and with --profile trivy-server --profile docker-env. All four parse, and the merged config reports exactly the pre-change values:

  docker-socket-proxy    cpus=0.5   mem_limit=   64 MiB   mem_reservation=   0 MiB
  scrye                  cpus=2     mem_limit= 2048 MiB   mem_reservation= 256 MiB
  trivy-server           cpus=1     mem_limit= 1024 MiB   mem_reservation=   0 MiB

Only the Compose CLI is available in this environment (no daemon), so no container was started — what is verified is that the files parse and normalize to the original limits, not that a live container was inspected. docker compose up / /healthz is unverified here for that reason; CI's image job is the gate.

Five regression guards were added to backend/tests/test_compose_hardening.py: no deploy: key in either file, a mem_limit for every service, scrye's mem_reservation, a cpus entry in the overlay for every service the base file defines, and the overlay's use of the portable key. They were exercised against seven mutations of the real files (a deploy: block returning, the overlay deleted, mem_limit/mem_reservation dropped, a new uncapped service, the overlay reverting to deploy:, the socket-proxy cap loosened) — each fires on the regression it names, with the unmodified files clean. They are string-level like the rest of that module, deliberately: the backend declares no YAML parser.

The backend suite could not be run locally (this container has Python 3.11; the backend requires 3.14), so the new test bodies were executed standalone against the checked-in files. ruff and black are clean.

Docs

• README gains a Resource limits (and NAS platforms) section: the memory table, the overlay invocation, the COMPOSE_FILE alternative, the warning that both -f flags must be repeated on every command for the stack, and a pointer for NAS users to their platform's own CPU controls. The paste-in stack, the security-model bullet, the sidecar commands, and the contents list are updated to match.
• CHANGELOG.md under Unreleased, with the action-required note.
• See docs/ARCHIVE.md § Deviations for changes made in this pass.