Kamal’s configuration comes with one primary proxy role to accept HTTP traffic. Here’s how to think about proxy roles and how to configure others.
Kamal roles
Roles are a Kamal way to split application containers by their assigned role. A web role runs the application server, a job role runs a job queue, and an api role might run API. They all run the same Docker image but can started with a different command:
# config/deploy.yml
...
servers:
web:
hosts:
- 161.232.112.197
job:
hosts:
- 161.232.112.197
cmd: bin/jobs
A web role is special role since it’s a primary role that also runs Docker Proxy:
# config/deploy.yml
...
servers:
web:
hosts:
- 161.232.112.197
proxy: true
primary_role: web
# proxy:
# ssl:
# host:
A primary role is a role that’s booted first. Other roles boot only once at least one container of the primary role passed its health check. We can change the name of the primary role with the primary_role directives.
Proxy roles
A proxy role is a role that uses Kamal Proxy to accept requests. By default, Kamal sets up the web role to accept requests as we have seen. But we can have more roles to accept requests.
Let’s say we want to run an API server alongside the main application:
# config/deploy.yml
...
servers:
web:
hosts:
- 161.232.112.197
api:
hosts:
- 161.232.112.197
env:
MODE: "api"
proxy:
host: api.example.com
cmd: bin/rails s
proxy:
ssl: true
host: example.com
Now Kamal will boot our application and shortly after start the API server. Since it’s a proxy role it also comes with the same health check run by Kamal Proxy (checking out the /up path on port 80).
Similarly we could split the application into backend and frontend:
# config/deploy.yml
...
servers:
frontend:
hosts:
- 161.232.112.197
proxy:
host: example.com
cmd: npm start
backend:
hosts:
- 161.232.112.197
proxy:
host: api.example.com
cmd: bin/rails s
primary_role: backend
proxy:
ssl: true
Still, only one role will be the primary role and both roles have to share the same Docker image.
