Booting

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).

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.

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.

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.

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.