How It Works (Overview)

This page is the bridge between What is MultiDocker? and the deeper Concepts. It follows one project from registration to an open browser tab and explains what happens at each step.

The end-to-end flow

init → up → open

mdocker init ~/Projects/aurora
  └─ detect profile (image/service heuristic)
  └─ write ~/.config/multi-docker/overrides/aurora.override.yml
  └─ record project in registry.json

mdocker up aurora
  └─ port-conflict pre-flight (remap to a free port if needed)
  └─ docker compose -p aurora up -d
       COMPOSE_FILE = <project>/docker-compose.yml : aurora.override.yml
  └─ containers join the multi-docker-edge network
  └─ Traefik picks up the labels and starts routing

mdocker open aurora
  └─ open https://aurora.coding9.test

What reads what

mdocker (any verb) ──► docker compose -p <name>   (COMPOSE_FILE chain)
       │
       ├─► engine/detect.sh     pick a profile
       ├─► engine/render.sh ──► engine/profiles/*.yml     generate the override
       └─► scripts/*.sh         TLS · DNS · network · doctor

edge/compose.yml ──► Traefik ──► your labelled project containers
                     (provider = docker, via the docker-socket-proxy)

Step by step

1. Registration (init)

mdocker init <path> inspects the project’s compose file, runs the profile heuristic (engine/detect.sh) to pick a suitable template, then generates the override with engine/render.sh. The project is recorded in registry.json — the single source of truth for its path, profile, hostnames and any persisted port overrides.

2. Start (up)

mdocker up <name> first runs a port-conflict pre-flight: if a host port your project publishes is already taken by a foreign process, MultiDocker finds a free replacement and persists it. It then calls docker compose with the COMPOSE_FILE chain so the override is layered on top of your untouched original. The containers join the multi-docker-edge network and Traefik immediately starts routing to them based on the labels in the override.

3. Open (open)

Because dnsmasq answers *.<base-domain> with 127.0.0.1 and the macOS resolver forwards that domain to it, https://aurora.coding9.test resolves to Traefik. The mkcert wildcard certificate makes the connection trusted, so the browser shows a green padlock.

The override in one glance

The generated override strips host ports and adds routing labels. A simplified example:

aurora.override.yml

services:
  proxy:
    ports: !reset []            # remove host port bindings, do not merge them
    networks: [default, edge]
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.aurora.rule=Host(`aurora.coding9.test`)"
      - "traefik.http.routers.aurora.tls=true"

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

Want the details? Read The Override Engine, The Edge Stack and DNS & TLS.