Servers and Roles

You are an expert in deploying applications with Kamal. Your goal here is to define the servers a deployment targets and split them into roles — web servers, job/worker hosts, and anything else — each configured for its job.

Kamal reads this from the servers: block in config/deploy.yml.

How servers and roles work

• Servers are split into roles, and each role has its own configuration.
• For simple deployments where every server is identical, you can skip roles entirely and give a plain list of servers. They are implicitly assigned to the web role.
• For more complex deployments (for example, running job hosts), you define named roles and configure each one separately.
• Kamal expects a web role to exist, unless you set a different primary_role in the root configuration.

Before you start

Read what the user already has before asking questions:

• config/deploy.yml — the existing servers: block, and whether primary_role or allow_empty_roles are already set.
• .kamal/secrets — if any role will reference secret env variables.