Your First Project

The Quickstart gets you running fast. This page runs the same commands but explains what each one does, so you understand the machinery before you rely on it.

1. Register the project — and watch the profile detection.

   mdocker init

   mdocker init ~/Projects/aurora

   init reads the project’s compose file and runs a profile heuristic (engine/detect.sh) that looks at image and service names to choose a template — for example shopware-dockware, strapi-next, api-web-postgres, or the generic fallback. It then generates ~/.config/multi-docker/overrides/<name>.override.yml and records the project in registry.json.

   You can override the guesses:

   explicit name, profile and host

   mdocker init ~/Projects/aurora \
     --name aurora \
     --profile generic \
     --host aurora.coding9.test

   See Registering & Detecting Projects for the full set of options.

2. Start the project — and understand the port pre-flight.

   mdocker up

   mdocker up aurora

   Before starting, up runs a port-conflict pre-flight. If a host port your project would publish is already taken by a foreign process, MultiDocker finds a free replacement, persists it under port_overrides in the registry and writes a <name>.ports.yml. Then it renders the COMPOSE_FILE chain and calls docker compose up -d. The containers join the multi-docker-edge network and Traefik starts routing immediately.

   Port pre-flight controls

   • mdocker up <name> --auto-remap-ports — remap automatically without prompting.
   • mdocker up <name> --no-port-check — skip the pre-flight entirely.
   • If no free replacement port can be found, up exits with code 2.

3. Open it — trusted HTTPS, no warnings.

   mdocker open

   mdocker open aurora

   The hostname resolves because dnsmasq answers *.coding9.test with 127.0.0.1 and the macOS resolver forwards that domain to it. The mkcert wildcard certificate makes the TLS connection trusted, so the browser shows a padlock rather than a security warning.

4. Inspect what is running.

   mdocker inspect

   mdocker inspect aurora

   inspect lists each service’s container, ports and environment, plus a ready-to-copy connection string (mysql://, postgres://, …). Add --json for scripting.

First time seeing a certificate prompt?

If your browser still warns about the certificate, the mkcert CA may not be trusted yet. Run mkcert -install and restart the browser — see Common Issues.

Where to go next

• Manage hostnames and routing: Hostnames & Routing.
• Reach the database from your host: Accessing Databases.
• Understand the internals: Architecture Overview.