From cdd9e7bdd82c83c89ffa4f05266b23a96d93ab1c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Pedro?= Date: Wed, 21 Oct 2026 01:23:54 -0400 Subject: [PATCH 1/3] docs: README and command reference for registries, contexts, migrate and compose extras --- README.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/COMMANDS.md | 15 ++++++++++- 2 files changed, 84 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index df10800..e132242 100644 --- a/README.md +++ b/README.md @@ -336,6 +336,76 @@ docker ps macker ps ``` +### Registries, build and push + +```bash +echo "$TOKEN" | docker login ghcr.io -u myuser --password-stdin # password never in argv +docker login registry.local:5000 --scheme http -u ci --password-stdin +docker logout ghcr.io + +docker build -t app:1 --target prod --platform linux/arm64 --label team=web \ + --secret id=token,src=$HOME/.npmrc --pull -f Dockerfile.dev . +docker build -t app:1 --no-cache . +docker tag app:1 registry.example.com/team/app:1 +docker push registry.example.com/team/app:1 +``` + +`docker login` reads the password from `--password-stdin` or a hidden prompt. +`docker build` does not accept `-a`, `-c` or `-m` on `commit`; for build, +`--cache` tuning is not exposed by the 1.6.0 CLI, so only `--no-cache` and +`--pull` control caching. + +### Contexts and other daemons + +```bash +docker context ls +docker context create colima --docker host=unix://$HOME/.colima/default/docker.sock +docker context use colima # later commands go to Colima through its docker CLI +docker --context default ps # one call on the local runtime +docker context rm colima +``` + +The `default` context is Macker's own runtime. Any other context sends the +command, unchanged, to the docker CLI installed with that runtime (Docker +Desktop, Colima and OrbStack ship one). Macker never uses itself for that. + +### Migrating from Docker Desktop, Colima or OrbStack + +```bash +macker migrate --from colima --dry-run # list images (and volumes with --volumes) +macker migrate --from colima # copy every image +macker migrate --from orbstack --volumes # also copy named volumes, with contents +macker migrate --from docker-desktop --volumes --helper-image alpine:latest +``` + +Images are saved with the source's docker CLI and loaded with `container image +load`. Named volumes are read and written with `tar` in a helper container +(default `alpine:latest`, which must contain `tar`). Containers, compose +projects, bind mounts and anonymous volumes are not moved; recreate them with +`docker compose up` once the images and volumes are in place. + +### Compose extras + +```bash +docker compose -f compose.yaml -f compose.prod.yaml up -d # files are merged in order +COMPOSE_FILE=compose.yaml:compose.dev.yaml docker compose up -d +docker compose --profile debug up -d # or COMPOSE_PROFILES=debug +docker compose up -d --scale web=3 # replicas: web-1, web-2, web-3 +docker compose stop web # acts on every replica +``` + +- Without `-f`, Macker uses `compose.yaml` (or `docker-compose.yml`) and its + `.override` file when present. +- Services with `profiles:` run only when a matching profile is active. +- `deploy.replicas` sets the replica count when `scale:` and `--scale` are unset. +- `configs:` and `secrets:` with a `file:` source are mounted read-only at their + `target:` (default `/` for configs, `/run/secrets/` for secrets). +- `healthcheck: { disable: true }` (or `test: [NONE]`) turns a healthcheck off. + +Not yet supported in Compose: inline `content:` configs, environment-backed +secrets, external configs and secrets, healthcheck status in `ps`, and the +per-check `timeout`. + Full command reference — see [docs/COMMANDS.md](docs/COMMANDS.md). --- diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 3ffd01c..0d575cf 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -5,7 +5,9 @@ | Group | Commands | |-------|----------| | **Containers** | `ps`, `run`, `create`, `start`, `stop`, `restart`, `kill`, `rm`, `exec`, `logs`, `stats`, `wait`, `port`, `top`, `pause`, `unpause`, `cp`, `inspect`, `events` | -| **Images** | `images`, `pull`, `push`, `build`, `tag`, `rmi`, `prune`, `load`, `save`, `search`, `scan` | +| **Images** | `images`, `pull`, `push`, `build` (`--target`, `--platform`, `--label`, `--secret`, `--pull`, `--no-cache`, `-m`, `-c`), `tag`, `rmi`, `prune`, `load`, `save`, `search`, `scan` | +| **Registries** | `login` (`-u`, `--password-stdin`, `--scheme`), `logout` | +| **Contexts** | `context ls`, `context create`, `context use`, `context show`, `context inspect`, `context rm`, `--context NAME` | | **Secrets** | `secret ls`, `secret create`, `secret inspect`, `secret rm` | | **Volumes** | `volume create`, `volume ls`, `volume rm`, `volume inspect`, `volume prune` | | **Networks** | `network create`, `network ls`, `network rm`, `network inspect`, `network connect`, `network disconnect`, `network prune` | @@ -31,4 +33,15 @@ | `port` | Print the public port for a service | | `rm` | Remove stopped service containers | +`up` also accepts `-f` (repeatable), `--profile` (repeatable), `--scale SERVICE=N`, and `COMPOSE_FILE` / `COMPOSE_PROFILES`. `stop`, `start`, `restart`, `kill` and `logs` act on every replica. + +## `macker migrate` + +| Flag | Description | +|------|-------------| +| `--from docker-desktop\|orbstack\|colima` | Source runtime (required) | +| `--dry-run` | List what would be copied | +| `--volumes` | Also copy named volumes with their contents | +| `--helper-image IMAGE` | Image with `tar` used for volume copies (default `alpine:latest`) | + Unsupported commands fail with an explicit, actionable message. From e07568d2e79a6c08b48725c3d672b8ce94844db7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Pedro?= Date: Wed, 21 Oct 2026 01:24:06 -0400 Subject: [PATCH 2/3] docs: clarify build cache options in the README --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e132242..1cb65d7 100644 --- a/README.md +++ b/README.md @@ -351,9 +351,8 @@ docker push registry.example.com/team/app:1 ``` `docker login` reads the password from `--password-stdin` or a hidden prompt. -`docker build` does not accept `-a`, `-c` or `-m` on `commit`; for build, -`--cache` tuning is not exposed by the 1.6.0 CLI, so only `--no-cache` and -`--pull` control caching. +Build caching is controlled with `--no-cache` and `--pull`. The 1.6.0 CLI has no +cache-from/cache-to options, so cache import and export are not available yet. ### Contexts and other daemons From cf82ad39523ea4f08c9ebb47868a5b0f80dbf1ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Pedro?= Date: Wed, 21 Oct 2026 01:24:31 -0400 Subject: [PATCH 3/3] Fix braces in DockerShimTests after merging compose and migrate branches --- Tests/DockerShimTests/DockerShimTests.swift | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Tests/DockerShimTests/DockerShimTests.swift b/Tests/DockerShimTests/DockerShimTests.swift index e0ad5d1..44d1626 100644 --- a/Tests/DockerShimTests/DockerShimTests.swift +++ b/Tests/DockerShimTests/DockerShimTests.swift @@ -166,6 +166,9 @@ final class RegistryAndBuildParsingTests: XCTestCase { XCTAssertEqual(cmd.value(short: "u", long: "username"), "ana") XCTAssertTrue(cmd.has("password-stdin")) XCTAssertEqual(cmd.arguments, ["ghcr.io"]) + } +} + final class ComposeScaleFlagTests: XCTestCase { func testScaleFlagsParseIntoCounts() throws { let cmd = try DockerCommandParser.parse(["compose", "up", "-d", "--scale", "web=3", "--scale", "worker=0"])