Configuration

# Booting

Roll boots across a large fleet instead of restarting every host at once.

When deploying to large numbers of hosts, you might prefer not to restart your services on every host at the same time.

Kamal’s default is to boot new containers on all hosts in parallel. However, you can control this with the boot configuration.

This is a whole-deploy setting: `limit` slices the combined host list of every role, so it cannot hold one role back while another keeps booting. To pace a single role's hosts, set `boot` on that role instead (see dash docs role).

```yaml
boot:
```

The number or percentage of hosts to boot at a time, across all roles. This can be an integer (e.g., 3) or a percentage string (e.g., 25%).

A percentage counts the hosts this run is actually booting: app hosts only — accessories are not booted here — and narrowed by `--roles` / `--hosts`. So `25%` with `--roles web` is a quarter of web's hosts, not a quarter of the file.

```yaml
limit: 25%
```

The number of seconds to wait between booting each group of hosts.

This fills the gap between one group and the next, so it needs `limit` to mean anything: without one, every host boots in a single group and there is no gap to fill. Kamal warns if you set `wait` on its own. Nothing waits after the final group either — the deploy moves on as soon as the last host is up.

```yaml
wait: 10
```

The number of primary-role hosts to boot one at a time before the rest of the hosts boot.

A canary is the gate people reach for `limit: 1` to get — prove the new version on one host before touching the fleet — without serialising every host after it. The first N hosts of the primary role each boot alone; a boot failure there stops the deploy before any other host is touched. The remaining hosts of every role then boot together, or in groups when `limit` is also set (a percentage limit counts those remaining hosts). `wait` paces canary and remaining groups alike. Behind dash-proxy this never reduces capacity: each host keeps serving the old container until the new one passes its health check.

Top-level only. A role-scoped `boot` refuses it: the canary slices the primary role's hosts ahead of every other role, which a single role cannot express.

```yaml
canary: 1
```

Whether to boot roles in parallel on a host.

If a host has multiple roles, control whether they are booted in parallel or sequentially on that host.

Defaults to false. A role that sets its own `boot` needs this on, since per-role pacing has no meaning when each host walks its roles in turn — Kamal turns it on for you if you have not set it, and refuses the deploy if you set it to false.

```yaml
parallel_roles: true
```

> **Note:** Generated from the gem's `lib/dash/configuration/docs/boot.yml` — the same reference `dash docs boot` prints in your terminal, so this page always matches your installed version.