Skip to content

Commit 39a7cbb

Browse files
bpamiribpamiri
authored
docs(docs): add wheels deploy guides and CLI reference (starlight-native mdx) (#2190)
Adds the deployment docs slot deliberately left empty when the v4 guides rewrite shipped (#2169). The wheels deploy Kamal port (#2187) is now documented for end users: Deployment guides (web/sites/guides/src/content/docs/v4-0-0-snapshot/deployment/): - index.mdx rewrite: replaces the "no wheels deploy in 4.0" placeholder with a proper landing describing the Kamal lineage, when to use it, and the zero-downtime rollover story - first-deploy.mdx: guided tutorial from init → setup → deploy - config-reference.mdx: full deploy.yml schema, with every allowed top-level key sourced from Validator.cfc - accessories.mdx: sidecar lifecycle - secrets.mdx: .kamal/secrets and the 5 adapters (op/bw/aws/lpass/doppler) - hooks.mdx: KAMAL_* env contract + pre/post/post-failure - migrating-from-kamal.mdx: coexistence contract, ERB→Mustache divergence CLI reference (web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/commands/deploy/): - 69 per-verb pages — every verb in DeployMainCli, DeployAppCli, DeployProxyCli, DeployAccessoryCli, DeployBuildCli, DeployRegistryCli, DeployServerCli, DeployPruneCli, DeployLockCli, DeploySecretsCli - Each page: frontmatter, synopsis, flags table, behavior, examples - Behavior sourced directly from the *Cli.cfc files on develop Sidebar wiring (web/sites/guides/src/sidebars/v4-0-0-snapshot.json): - Deployment & Operations: 6 new items promoted to top, existing production-config/docker/vm/security/observability retained below - CLI Reference: new "Deploy Commands" subsection with collapsible per-verb-group leaves Build: pnpm --filter @wheels-dev/site-guides build succeeds, 415 pages. Cross-reference: #2187 (the port).
1 parent fcfafc4 commit 39a7cbb

77 files changed

Lines changed: 3967 additions & 52 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/boot.mdx‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: "wheels deploy accessory boot"
3+
description: First-time install and run of a named accessory container.
4+
type: reference
5+
sidebar:
6+
label: "boot"
7+
order: 1
8+
---
9+
10+
`docker run` the named accessory container on its pinned host(s).
11+
12+
## Synopsis
13+
14+
```
15+
wheels deploy accessory boot --name=<name|all> [--destination=<name>] [--dry-run]
16+
```
17+
18+
## Flags
19+
20+
| Flag | Description |
21+
|------|-------------|
22+
| `--name=<name>` | **Required.** Accessory name, or `all`. |
23+
| `--destination=<name>` | Overlay destination config. |
24+
| `--dry-run` | Print commands without executing. |
25+
26+
## Behavior
27+
28+
For each targeted accessory, emits `docker run` with the image, env, volumes, and `files:` uploads declared in `deploy.yml`. Container named `<service>-<accessory>`.
29+
30+
## Example
31+
32+
```bash
33+
wheels deploy accessory boot --name=db
34+
wheels deploy accessory boot --name=all
35+
```

‎web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/details.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: "wheels deploy accessory details"
3+
description: docker ps filtered to the named accessory container.
4+
type: reference
5+
sidebar:
6+
label: "details"
7+
order: 6
8+
---
9+
10+
`docker ps --filter name=<service>-<name>` on each of the accessory's hosts. Confirms it's up and shows uptime.
11+
12+
## Synopsis
13+
14+
```
15+
wheels deploy accessory details --name=<name|all> [--destination=<name>] [--dry-run]
16+
```
17+
18+
## Flags
19+
20+
| Flag | Description |
21+
|------|-------------|
22+
| `--name=<name>` | **Required.** Accessory name, or `all`. |
23+
| `--destination=<name>` | Overlay destination config. |
24+
| `--dry-run` | Print commands without executing. |
25+
26+
## Example
27+
28+
```bash
29+
wheels deploy accessory details --name=db
30+
```

‎web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/index.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: "wheels deploy accessory"
3+
description: Sidecar container lifecycle — mirrors app verbs, scoped to a named accessory.
4+
type: reference
5+
sidebar:
6+
label: "accessory"
7+
order: 40
8+
---
9+
10+
Sidecar container lifecycle. Every accessory verb takes a `--name` (or `all` for fan-out) and targets the pinned host(s) for that accessory.
11+
12+
## Verbs
13+
14+
| Verb | Purpose |
15+
|------|---------|
16+
| [`boot`](/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/boot/) | First-time install + run. |
17+
| [`reboot`](/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/reboot/) | Stop, remove, re-install. |
18+
| [`start`](/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/start/) | `docker start`. |
19+
| [`stop`](/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/stop/) | `docker stop`. |
20+
| [`restart`](/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/restart/) | `docker restart`. |
21+
| [`details`](/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/details/) | `docker ps --filter`. |
22+
| [`logs`](/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/logs/) | Tail accessory logs. |
23+
| [`remove`](/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/remove/) | Stop + remove the container. |
24+
25+
## Common flags
26+
27+
| Flag | Description |
28+
|------|-------------|
29+
| `--name=<name>` | **Required.** Accessory name, or `all` to fan out. |
30+
| `--destination=<name>` | Overlay destination config. |
31+
| `--dry-run` | Print commands without executing. |
32+
33+
Missing `--name` throws `DeployAccessoryCli.MissingName`.
34+
35+
## Relationship to `wheels deploy`
36+
37+
Accessory verbs are **not** part of the rolling app deploy. `wheels deploy` leaves accessories alone — that's deliberate, so routine rollouts can't accidentally bounce your database. See [Accessories](/v4-0-0-snapshot/deployment/accessories/).

‎web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/logs.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: "wheels deploy accessory logs"
3+
description: Tail the named accessory's container logs.
4+
type: reference
5+
sidebar:
6+
label: "logs"
7+
order: 7
8+
---
9+
10+
`docker logs` on the named accessory, on every host it's pinned to.
11+
12+
## Synopsis
13+
14+
```
15+
wheels deploy accessory logs --name=<name|all> [--tail=<N>] [--follow] [--destination=<name>] [--dry-run]
16+
```
17+
18+
## Flags
19+
20+
| Flag | Description |
21+
|------|-------------|
22+
| `--name=<name>` | **Required.** Accessory name, or `all`. |
23+
| `--tail=<N>` | Trailing lines per host. Default 100. |
24+
| `--follow` | Stream logs continuously. |
25+
| `--destination=<name>` | Overlay destination config. |
26+
| `--dry-run` | Print commands without executing. |
27+
28+
## Example
29+
30+
```bash
31+
wheels deploy accessory logs --name=db --tail=500
32+
wheels deploy accessory logs --name=redis --follow
33+
```

‎web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/reboot.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: "wheels deploy accessory reboot"
3+
description: Stop, remove, and re-run the named accessory container.
4+
type: reference
5+
sidebar:
6+
label: "reboot"
7+
order: 2
8+
---
9+
10+
Stop, remove, and re-run the named accessory container. Useful after bumping the image tag in `deploy.yml`.
11+
12+
## Synopsis
13+
14+
```
15+
wheels deploy accessory reboot --name=<name|all> [--destination=<name>] [--dry-run]
16+
```
17+
18+
## Flags
19+
20+
| Flag | Description |
21+
|------|-------------|
22+
| `--name=<name>` | **Required.** Accessory name, or `all`. |
23+
| `--destination=<name>` | Overlay destination config. |
24+
| `--dry-run` | Print commands without executing. |
25+
26+
## Behavior
27+
28+
Per accessory: `docker stop <service>-<name>`, `docker rm <service>-<name>`, then the same `docker run` as [`accessory boot`](/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/boot/). Downtime lasts until the new container passes its health check (if declared).
29+
30+
## Example
31+
32+
```bash
33+
wheels deploy accessory reboot --name=redis
34+
```

‎web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/remove.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: "wheels deploy accessory remove"
3+
description: Stop and remove the named accessory container. Volumes persist.
4+
type: reference
5+
sidebar:
6+
label: "remove"
7+
order: 8
8+
---
9+
10+
import { Aside } from '@astrojs/starlight/components';
11+
12+
Stop and remove the named accessory container. Does not touch attached volumes.
13+
14+
<Aside type="caution">
15+
Volumes persist after `accessory remove`. Data survives. If you want a truly clean slate, follow up with `docker volume rm` on the host.
16+
</Aside>
17+
18+
## Synopsis
19+
20+
```
21+
wheels deploy accessory remove --name=<name|all> [--destination=<name>] [--dry-run]
22+
```
23+
24+
## Flags
25+
26+
| Flag | Description |
27+
|------|-------------|
28+
| `--name=<name>` | **Required.** Accessory name, or `all`. |
29+
| `--destination=<name>` | Overlay destination config. |
30+
| `--dry-run` | Print commands without executing. |
31+
32+
## Example
33+
34+
```bash
35+
wheels deploy accessory remove --name=redis
36+
```

‎web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/restart.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: "wheels deploy accessory restart"
3+
description: docker restart the named accessory container.
4+
type: reference
5+
sidebar:
6+
label: "restart"
7+
order: 5
8+
---
9+
10+
`docker restart <service>-<name>`. Briefly interrupts the accessory.
11+
12+
## Synopsis
13+
14+
```
15+
wheels deploy accessory restart --name=<name|all> [--destination=<name>] [--dry-run]
16+
```
17+
18+
## Flags
19+
20+
| Flag | Description |
21+
|------|-------------|
22+
| `--name=<name>` | **Required.** Accessory name, or `all`. |
23+
| `--destination=<name>` | Overlay destination config. |
24+
| `--dry-run` | Print commands without executing. |
25+
26+
## Example
27+
28+
```bash
29+
wheels deploy accessory restart --name=redis
30+
```

‎web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/start.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: "wheels deploy accessory start"
3+
description: docker start the named accessory container.
4+
type: reference
5+
sidebar:
6+
label: "start"
7+
order: 3
8+
---
9+
10+
`docker start <service>-<name>` on the accessory's pinned host(s). Fails if the container doesn't exist — use [`accessory boot`](/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/boot/) for first-time install.
11+
12+
## Synopsis
13+
14+
```
15+
wheels deploy accessory start --name=<name|all> [--destination=<name>] [--dry-run]
16+
```
17+
18+
## Flags
19+
20+
| Flag | Description |
21+
|------|-------------|
22+
| `--name=<name>` | **Required.** Accessory name, or `all`. |
23+
| `--destination=<name>` | Overlay destination config. |
24+
| `--dry-run` | Print commands without executing. |
25+
26+
## Example
27+
28+
```bash
29+
wheels deploy accessory start --name=db
30+
```

‎web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/stop.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: "wheels deploy accessory stop"
3+
description: docker stop the named accessory container.
4+
type: reference
5+
sidebar:
6+
label: "stop"
7+
order: 4
8+
---
9+
10+
`docker stop <service>-<name>`. Container remains on disk — use [`accessory remove`](/v4-0-0-snapshot/command-line-tools/commands/deploy/accessory/remove/) to delete.
11+
12+
## Synopsis
13+
14+
```
15+
wheels deploy accessory stop --name=<name|all> [--destination=<name>] [--dry-run]
16+
```
17+
18+
## Flags
19+
20+
| Flag | Description |
21+
|------|-------------|
22+
| `--name=<name>` | **Required.** Accessory name, or `all`. |
23+
| `--destination=<name>` | Overlay destination config. |
24+
| `--dry-run` | Print commands without executing. |
25+
26+
## Example
27+
28+
```bash
29+
wheels deploy accessory stop --name=db
30+
```

‎web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/commands/deploy/app/boot.mdx‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: "wheels deploy app boot"
3+
description: Run new app containers for the given version on every host in every role.
4+
type: reference
5+
sidebar:
6+
label: "boot"
7+
order: 1
8+
---
9+
10+
`docker run` new containers for the given version, on every host in every role.
11+
12+
## Synopsis
13+
14+
```
15+
wheels deploy app boot --version=<v> [--role=<name>] [--destination=<name>] [--dry-run]
16+
```
17+
18+
## Flags
19+
20+
| Flag | Description |
21+
|------|-------------|
22+
| `--version=<v>` | **Required.** Version to boot. Throws `DeployAppCli.MissingVersion` if absent. |
23+
| `--role=<name>` | Limit to one role. Default: every role. |
24+
| `--destination=<name>` | Overlay `deploy.<name>.yml`. |
25+
| `--dry-run` | Print the `docker run` commands without executing. |
26+
27+
## Behavior
28+
29+
For each host in each role, emits:
30+
31+
```
32+
docker run --detach --restart unless-stopped \
33+
--name <service>-<role>-<version> \
34+
--network kamal \
35+
--label service=<service> --label role=<role> --label destination=<dest> --label version=<v> \
36+
-e KEY=VALUE ... \
37+
<image>:<version>
38+
```
39+
40+
`boot` does **not** ask the proxy to cut traffic — that's what `wheels deploy` does. Use `boot` for a stand-alone container bring-up; use `wheels deploy` for a full zero-downtime rollout.
41+
42+
## Example
43+
44+
```bash
45+
wheels deploy app boot --version=abc1234
46+
wheels deploy app boot --version=abc1234 --role=job
47+
```

0 commit comments

Comments
 (0)