A short, unique name for your app or service. This name is used to label containers, logs, and other resources, so keep it lowercase and simple (e.g., myapp). It becomes part of hostnames like myapp-web-1.

It defines both the repository name and tag for your Docker image. For example, it might be something like "mycompany/myapp:latest" or "username/application:v1.2.3". This name needs to be unique and must be available in the Docker registry that Kamal has access to (such as Docker Hub, GitHub Container Registry, or a private registry you've configured).

Defines what this machine will do in your deployment. Common roles are web (handles HTTP requests), worker (background jobs), or db (database). A single server can have multiple roles (e.g., web,worker). Kamal uses this to organize your services.

Web

The server that will handle web traffic — it runs your app’s web process (like Puma or another HTTP server). Enter the IP address or hostname (e.g., 203.0.113.5 or web.myapp.com). Kamal will connect via SSH to this machine and deploy the web containers there.

I.e 100.100.100.100, unagi.com.ar

Jobs

Do you need a container for background jobs?

The proxy handles all incoming HTTP and HTTPS traffic to your application. Kamal installs and manages its own lightweight reverse proxy (kamal-proxy) on these hosts. It routes requests to your web containers, supports load balancing, and can automatically enable SSL using Let's Encrypt. These hosts act as the public-facing entry point for your app.

The internal port your app listens on inside the container (e.g., 3000 for Rails with Puma). The proxy will forward incoming traffic to this port. Make sure it matches the port your app server is actually using.

These are the servers where Kamal will install and run its built-in reverse proxy (kamal-proxy). They handle incoming web traffic and route it to your app’s web containers. These hosts act as your application's public entrypoints, and Kamal will use them to manage SSL, load balancing, and domain-based routing.

Check this to automatically enable HTTPS using Let's Encrypt. Kamal will configure the proxy to request and renew SSL certificates for your domain. Make sure your DNS is properly set up before enabling this.

This section defines how your Docker image is built before deployment. You can specify the target architecture (e.g., arm64 or amd64), and choose whether to build the image locally or on a remote server. This helps ensure your app runs correctly on your production hardware and simplifies cross-platform builds.

If enabled, the image will be built on a remote server instead of your local machine. This is useful when your local environment can't build for the target architecture, or when you want to avoid pushing large images over slow networks.

This section tells Kamal where to push your Docker image so it can be pulled by your servers during deployment. You can use a service like Docker Hub, GitHub Container Registry, or any private registry. Credentials are stored securely using environment variables.

The URL of your container registry (e.g., ghcr.io, index.docker.io for Docker Hub, or your own private registry domain). Kamal will push the image here so servers can pull it.

The username used to log in to your container registry. This is usually your Docker Hub or GitHub username.

The name of the environment variable that holds your registry password or access token (e.g., REGISTRY_PASSWORD). Kamal uses this to authenticate when pushing and pulling images.

This section defines environment variables that will be available to your application at runtime. Use this to set things like RAILS_ENV, API keys, or any other configuration your app needs. These variables are injected into the running containers, so avoid putting secrets directly here—use secret managers or encrypted variables when possible.

Removes a previously set environment variable from the container’s environment. This is useful if you want to override or clean up a value from a shared config.

Marks an environment variable as sensitive. Kamal will load its value from the host machine’s environment at runtime instead of hardcoding it into the deploy file. This keeps secrets like API keys or database passwords out of version control.

Accessories are additional services your app depends on — like PostgreSQL, Redis, or Elasticsearch. Kamal will run each accessory in its own container, on the specified host, and manage them alongside your app. These containers are not exposed to the public; they’re meant to be accessed internally by your app. Accessories can have custom commands, environment variables, and volumes for data persistence.