diff --git a/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/app/index.mdx b/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/app/index.mdx index 2c50941704..fea32b91e9 100644 --- a/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/app/index.mdx +++ b/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/app/index.mdx @@ -31,10 +31,10 @@ App container lifecycle. Every verb targets containers labelled with the current | Flag | Description | |------|-------------| | `--release=` | Required for boot/start/stop/remove. Optional for details. Ignored by containers/images/logs/live/maintenance. | -| `--role=` | Limit to one role. Default: all roles. | +| `--role=` | Limit to one role. Default: all roles. A name that `deploy.yml` doesn't define stops the command with an error that lists the roles it does define. | | `--destination=` | Overlay destination config. | | `--dry-run` | Print commands without executing. | diff --git a/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/app/logs.mdx b/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/app/logs.mdx index 86dae2ea5d..1ea8fb56cd 100644 --- a/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/app/logs.mdx +++ b/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/app/logs.mdx @@ -7,7 +7,7 @@ sidebar: order: 7 --- -`docker logs` fanned out across every host, prefixed by host. Follows and per-container targeting supported. +`docker logs` fanned out across every host, prefixed by host. Reads each role's newest container by default; `--container` picks one by name. ## Synopsis @@ -21,22 +21,30 @@ wheels deploy app logs [--tail=] [--follow] [--container=] [--role=` | Trailing lines per host. Default 100. | | `--follow` | `docker logs --follow`. Leaves the connection open; Ctrl-C to stop. | -| `--container=` | Container to read logs from. Pass it in practice: without it the emitted `docker logs` command has no container argument, and Docker rejects it. | -| `--role=` | Limit to one role. | +| `--container=` | Read this container's logs instead of each role's newest running container. | +| `--role=` | Limit to one role. A name that `deploy.yml` doesn't define stops the command with an error listing the roles it does define. | | `--destination=` | Overlay destination config. | `--release` is not required. ## Behavior -Emits `docker logs --tail [--follow] []` per host in the targeted role(s). Output is line-buffered and prefixed with `[]`. +Without `--container`, each host in the targeted role(s) reads the role's newest running container: + +```txt +docker ps --latest --quiet --filter 'label=service=' [--filter 'label=role=' --filter 'label=destination='] | xargs -r docker logs --tail [--follow] +``` + +The role and destination filters are added for each role the command runs for, which is every targeted role. Without `--destination`, the destination filter is empty (`label=destination=`) and matches containers deployed without one. + +With `--container=`, it runs `docker logs --tail [--follow] `, with the name shell-quoted. Output is line-buffered and prefixed with `[]`. Under `--follow`, the command fans out in parallel and stays running until interrupted. ## Examples ```bash title="illustrative" -wheels deploy app logs --container=myapp-web-abc1234 -wheels deploy app logs --container=myapp-web-abc1234 --tail=500 -wheels deploy app logs --container=myapp-web-abc1234 --follow --role=web +wheels deploy app logs +wheels deploy app logs --tail=500 --role=web +wheels deploy app logs --container=myapp-web-abc1234 --follow ``` diff --git a/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/build/create.mdx b/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/build/create.mdx index 34d9eb978b..577de2ab1b 100644 --- a/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/build/create.mdx +++ b/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/build/create.mdx @@ -24,11 +24,17 @@ wheels deploy build create [--destination=] [--dry-run] ## When to run -Only when you want a named `kamal-` buildx builder on the control machine, for example to select it yourself with `docker buildx use kamal-`. `build push` and `wheels deploy` do not need it. +Once, before the first build, when `builder.remote` is set. [`build push`](../push/) then builds with `--builder kamal-`, so that builder must exist. Without `builder.remote`, `build push` uses your current default builder and doesn't need this. ## Behavior -Emits `docker buildx create --name kamal- --driver=docker-container` on the control machine. The builder is not selected with `--use`, and `build push` / `wheels deploy` do not pass `--builder`, so they build with your current default builder. +Emits `docker buildx create --name kamal- --driver=docker-container` on the control machine. When `builder.remote` is set, its endpoint is passed too, so the builder runs on that host: + +```txt +[local] docker buildx create --name kamal-ddapp --driver=docker-container 'ssh://deploy@192.0.2.50' +``` + +The builder is not selected with `--use`; `build push` names it with `--builder` instead. ## Example diff --git a/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/build/push.mdx b/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/build/push.mdx index 8533bd072e..4167d09ae6 100644 --- a/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/build/push.mdx +++ b/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/build/push.mdx @@ -25,9 +25,23 @@ wheels deploy build push [--version=] [--destination=] [--dry-run] ## Behavior -Emits one command: `docker buildx build --push --tag : --file `, using `builder.dockerfile` (default `Dockerfile`) and `builder.context` (default `.`). The image is prefixed with `registry.server` unless the server is `docker.io`. +Emits one command: -`builder.arch`, `builder.args` and `builder.remote` are not applied: the command has no `--platform`, `--build-arg` or `--builder` option, so it always builds on the control machine with the current default buildx builder. +```txt +docker buildx build --push --platform linux/[,linux/...] [--builder kamal-] --label service= [--build-arg KEY=value ...] --tag : --file +``` + +- **`--file` and the context** come from `builder.dockerfile` (default `Dockerfile`) and `builder.context` (default `.`). The image is prefixed with `registry.server` unless the server is `docker.io`. +- **`--platform`** lists one `linux/` per entry in `builder.arch`, which takes a list or a comma-separated string and defaults to `amd64`. An entry that already contains `/` (for example `linux/arm/v7`) is used as is. An entry that isn't a plain platform name (letters, digits, `.`, `_`, `/` and `-` only) stops the command with `Wheels.Deploy.InvalidInput`. +- **`--builder kamal-`** is added when `builder.remote` is set. That builder is the one [`wheels deploy build create`](../create/) creates on the remote host. +- **`--build-arg`** is added once per `builder.args` entry, sorted by key. +- **`--label service=`** is always set. [`wheels deploy prune images`](../../prune/images/) relies on it to find the service's images; images built before this label was added carry none. + +With `--dry-run`, for a `builder` of `arch: amd64,arm64`, `remote: ssh://deploy@192.0.2.50` and `args: {ALPHA: first, ZETA: last}`: + +```txt +[local] docker buildx build --push --platform linux/amd64,linux/arm64 --builder kamal-ddapp --label 'service=ddapp' --build-arg 'ALPHA=first' --build-arg 'ZETA=last' --tag 'ddapp/web:v3' --file 'Dockerfile' '.' +``` ## Example diff --git a/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/prune/images.mdx b/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/prune/images.mdx index 97221ddd79..d41cf2322b 100644 --- a/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/prune/images.mdx +++ b/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/prune/images.mdx @@ -7,7 +7,7 @@ sidebar: order: 2 --- -Prune dangling images labelled with the service on every host. +Remove the service's unused images on every host. ## Synopsis @@ -24,7 +24,11 @@ wheels deploy prune images [--destination=] [--dry-run] ## Behavior -Per host, emits `docker image prune -f --filter label=service=`. Without `-a`, `docker image prune` removes only dangling (untagged) images, and only those carrying a `service=` label. The `Dockerfile` that `wheels deploy init` generates sets no such label and the build adds none, so on a default setup this removes nothing; tagged images of old versions stay on the host. +Per host, emits `docker image prune --all --force --filter label=service=`. It removes every image of the service that no container uses, tagged images of old versions included. Images used by any container, running or stopped, are kept. + +Rollback isn't affected while a version's container still exists: [`wheels deploy rollback `](../../rollback/) restarts that version's existing container (`docker start`) and doesn't pull, and an image in use by a stopped container is kept. Once [`prune containers`](../containers/) has removed a version's container, the next `prune images` removes its image too. Going back to that version then means deploying it again with `wheels deploy --version= --skip-push`, which pulls that version's image from the registry instead of building the current checkout. + +The label comes from [`wheels deploy build push`](../../build/push/), which sets `service=` on every image it builds. Images built before that label was added carry none, so this command doesn't remove them; remove those once with `docker image rm`. ## Example diff --git a/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/prune/index.mdx b/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/prune/index.mdx index 1270ecf6d8..b31b5f706b 100644 --- a/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/prune/index.mdx +++ b/web/sites/guides/src/content/docs/v4-2-0/command-line-tools/commands/deploy/prune/index.mdx @@ -13,8 +13,8 @@ Disk cleanup. Three verbs with increasing scope. | Verb | Removes | |------|---------| -| [`all`](/v4-2-0/command-line-tools/commands/deploy/prune/all/) | Old stopped containers + dangling service-labelled images. | -| [`images`](/v4-2-0/command-line-tools/commands/deploy/prune/images/) | Dangling service-labelled images only. | +| [`all`](/v4-2-0/command-line-tools/commands/deploy/prune/all/) | Old stopped containers + the service's unused images. | +| [`images`](/v4-2-0/command-line-tools/commands/deploy/prune/images/) | The service's unused images only. | | [`containers`](/v4-2-0/command-line-tools/commands/deploy/prune/containers/) | Old stopped containers only. | ## Retention policy