Installing & Runtime Model

The app doesn’t depend on a separately-installed CLI. It bundles its own copy of the mdocker runtime and manages it under ~/.multidocker/. This page explains that model — how the runtime is laid out, how updates work, and why your certs and projects survive them.

First run

On first launch the app opens a six-step wizard that gets you to a working setup:

1. Welcome
2. Install — extract the bundled runtime into ~/.multidocker/runtime/<version>/.
3. Symlink — optionally install a user CLI symlink at ~/.local/bin/mdocker.
4. Tools — install the prerequisite Homebrew packages (mkcert, yq, jq, …).
5. Setup — TLS CA + wildcard cert, DNS resolver, docker network, edge stack (this is the admin step that asks for your password once).
6. Done

Any project you register during the wizard shows up in the main window automatically when it closes — no manual refresh needed.

The runtime directory

The app manages everything under ~/.multidocker/:

~/.multidocker/
├── bin/mdocker            wrapper that resolves the "current" runtime
├── runtime/
│   └── <version>/         extracted runtime (bin, lib, engine, scripts, edge)
├── current → runtime/<v>  symlink updated by the installer
├── config/                registry, overrides, certs, snapshots, tunnels
├── preferences/preferences.json
├── state/{wizard.json, .migrated-*}
└── logs/console-YYYY-MM.log

InstallerService extracts a runtime.tar shipped inside the app bundle into a version-stamped folder, then repoints the current symlink at it. The bin/mdocker wrapper always resolves through current, so the app and any user symlink transparently pick up the active version.

The Install step shows both sides of that: where the runtime lands, and which version is currently active.

Once you are set up, the same information lives in Settings → Runtime, together with a reinstall button, the CLI symlink toggle and a way to reopen the wizard:

How the app finds the binary

MdockerService.locateBinary() searches in order:

1. A user-configured override path (from preferences).
2. ~/.multidocker/bin/mdocker (the wrapper).
3. ~/.local/bin/mdocker (the user symlink from the wizard).
4. /usr/local/bin/mdocker, /opt/homebrew/bin/mdocker.
5. which mdocker.

If none is found, the wizard surfaces the Install step.

Updates keep your data

When a new app version ships a newer runtime, the installer unpacks a fresh runtime/<version>/ and moves the current symlink — it never touches config/. So:

Nothing to redo after an update

Your registry, overrides, snapshots and — crucially — your mkcert CA and wildcard cert all live in config/, outside the versioned runtime folder. An update can’t overwrite them, so you don’t re-trust certificates or re-register projects. See Filesystem Layout.

The post-update cycle

Recreating the edge network during an update can detach running project containers, and a plain restart won’t re-attach them. After a real runtime update, the app detects this (pendingPostUpdateCycle) and offers to run mdocker cycle — a clean restart of the edge stack plus every previously-running project, so everything re-attaches to the fresh network and picks up any re-rendered overrides. You can also trigger it manually from the Runtime settings section.

Data migration

On startup, before anything else constructs, DataMigration runs a set of idempotent phases (gated by marker files) that move older installs to the current layout — including migrating certs out of the runtime folder and into config/. Migrations only run once each.