The Override Engine

The single most important design decision in MultiDocker:

Core principle

Your project’s compose files are never modified. Every adaptation lives in a separate, generated override file that MultiDocker layers on top at runtime.

Overrides, not edits

When you register a project, MultiDocker writes a generated file to ~/.config/multi-docker/overrides/<name>.override.yml. It never opens, patches or rewrites your original docker-compose.yml. Your repository stays exactly as your team committed it — no MultiDocker-specific labels, no stripped ports, nothing to .gitignore.

The override is derived from a profile template and typically does three things:

• Strips host port mappings so parallel projects can’t collide on the host (see Compose !reset & Port Stripping).
• Joins containers to the edge network (external multi-docker-edge) so Traefik can reach them.
• Attaches Traefik labels that route <host>.<base-domain> to the right service.

The COMPOSE_FILE chain

The CLI runs docker compose with both your file and the generated override, using Docker Compose’s built-in file-merging via the COMPOSE_FILE environment variable:

COMPOSE_FILE="<project>/docker-compose.yml:~/.config/multi-docker/overrides/<name>.override.yml" \
  docker compose -p <name> up -d

Compose merges the files left-to-right, so the override wins on any key it sets. If a project has port-conflict overrides, a third file is appended to the chain:

COMPOSE_FILE="<original>:<name>.override.yml:<name>.ports.yml"

A worked example

A typical rendered override for a Shopware project looks like this:

~/.config/multi-docker/overrides/aurora.override.yml

services:
  proxy:
    ports: !reset []
    networks: [default, edge]
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=multi-docker-edge"
      - "traefik.http.routers.aurora.rule=Host(`aurora.coding9.test`)"
      - "traefik.http.routers.aurora.entrypoints=websecure"
      - "traefik.http.routers.aurora.tls=true"
      - "traefik.http.services.aurora.loadbalancer.server.port=80"
  shop:
    ports: !reset []
    environment:
      MAILER_DSN: "smtp://mailcatcher:1025"
  db:
    ports: !reset []
  mailcatcher:
    profiles: ["off"]   # local mailcatcher off — the central edge one takes over

networks:
  edge:
    name: multi-docker-edge
    external: true

Note the mailcatcher service being switched off via profiles: ["off"], and the db having its host ports stripped — you reach the database through OrbStack DNS or mdocker inspect instead of a host port.

Regenerating an override

Overrides are pure functions of the registry state. Any time you add a hostname, change the base domain, or edit a profile, the affected overrides are re-rendered. You can also do it explicitly:

mdocker rerender <name>

The generator (engine/render.sh) also filters out any service that doesn’t exist in your original compose, so a profile template can safely mention optional services like opensearch without breaking projects that lack them.