Hosts and roles

A host is one server pinned to one Kamal role. The set of hosts in an environment is exactly the roles-and-hosts shape Kamal deploys from.

Roles

The roles on offer are the ones your repository’s deploy.yml declares – web, worker, job, whatever you named. Place at least one server against each role you actually use.

A role the repository declares with nothing placed against it is a blocked environment. Kamal would fall back to whatever deploy.yml says, and after kamal init that is a placeholder address pointing at somebody else’s machine.

Order

Hosts within a role are ordered. The first host of the primary role is the primary: it is where kamal app exec runs, where the deploy lock lives, and where scheduled tasks execute.

One machine, many roles

The same server can hold several roles of the same environment – web and worker on one box is a perfectly ordinary small deployment. That is still one environment on one machine.

Several machines

Adding a second host in a role is how an environment spans machines. Three things to know before you do:

SSH. Kamal takes one SSH user and one port for the whole destination. Every machine in the environment has to agree. An environment whose hosts disagree is blocked.

Architecture. One architecture across the fleet is one build. Mixing amd64 and arm64 machines in one environment means a multi-arch build – which Kamal supports, and which is much slower.

TLS. kamal-proxy only obtains its own certificate for a single host. Above one machine in the proxy role, somebody has to supply a certificate pair. See Domains and TLS.

Restarts. KamalCloud sets no rolling boot for a role, so a deploy restarts every host in it at once. Two web hosts are two copies, not a deploy that keeps one serving while the other restarts.

Accessories do not spread

An accessory runs on the machine its config names, and only there. With several hosts in an environment, that is not necessarily the primary one. Moving an accessory to another machine would leave its container and its data behind on the old one, so KamalCloud treats where an accessory lives as a decision rather than a detail.

From the server’s side

A server’s Apps page is the same relationship asked from the other end: what is deployed on this machine, and a way to put something here.

Removing a host

Removing a host stops Kamal deploying to that machine, and that is all it does. Nothing is sent to the machine: anything already running on it stays until you remove it there.

KamalCloud only clears containers off a machine when you delete the server itself and choose to wipe what KamalCloud deployed. See Servers.