# Tutorial: Deploy a Rails app using Kamal

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/help/ruby/2026.3/llms.txt).

[Kamal](https://kamal-deploy.org) is a deployment tool for containerized Rails applications. Instead of running tasks over SSH like Capistrano, Kamal builds a Docker image of your application, pushes it to a registry, and runs it on your servers inside lightweight containers.

In RubyMine, you can run Kamal commands directly from the built-in terminal or by using `Run Anything`. This makes it easy to trigger deployments, manage environments, and monitor logs without leaving the IDE.

In this tutorial, we'll show you how to deploy a sample Rails application to a remote server using Kamal. As the application server, Puma will run inside a Docker container, with Kamal Proxy handling HTTP and HTTPS traffic.

## Prerequisites

To deploy a Rails application with Kamal entirely from RubyMine, make sure your local environment and the remote server meet these requirements.

Local machine

* Mac with macOS

* RubyMine installed and configured for your Rails project

* A Rails 8 application. For older Rails versions, add Kamal to your Gemfile or install it locally with `gem install kamal`

* A valid `Dockerfile` in the project root

* Docker installed locally

* Access to a container registry (Docker Hub, GitHub Container Registry, or private registry) with credentials stored securely

* SSH configured locally

Web server

* Linux-based host

* SSH access for the same user defined in your Kamal `deploy.yml` (or in your OpenSSH config)

* Docker installed and running (Kamal can install it during `kamal setup` on fresh hosts)

## Deployment

This part of the tutorial describes the steps required to deploy an app with Kamal.

Procedure: Initialize Kamal

1. In RubyMine, open the terminal: `View | Tool Windows | Terminal`. Alternatively, click the Terminal icon on the toolbar in the lower left corner of the IDE.

2. Run the following command:

```BASH
kamal init
```

3. This creates a `config/deploy.yml` file. This file contains many configuration keys and options for deployment, but in this tutorial, we will focus only on the settings that are necessary for our deployment.

Procedure: Configure your deployment

Edit the created `config/deploy.yml` file generated by `kamal init`.

Below is an example of the file contents:

> **Note:**
> The default `config/deploy.yml` file generated by `kamal deploy` includes additional keys. The example file shown here contains only the keys that need to be configured based on your deployment environment.

```YAML
      # Name of your application. Used to uniquely configure containers.
service: app_name # Name of the application being deployed.

# Registry path for your Docker image.
image: user/app_name # Docker image path in the container registry.

servers:
  web:
    - # List of IPs or hostnames of the servers where the application will be deployed.

ssh:
  user: user_name # SSH user for connecting to the deployment server(s).

proxy:
  ssl: true # To disable SSL (useful for local testing), set to false.
  host: app.example.com # The hostname or domain where the app will be accessible.

registry:
  username: # Registry username for pushing/pulling Docker images (e.g., Docker Hub credentials).
  password: # Registry token or password for authentication.

env:
  clear:
    RAILS_ENV: # Specifies the environment for the Rails application (e.g., production, development).
    PORT: # The port the application should run on.
    SECRET_KEY_BASE: # Rails secret key base for encryption.

builder:
  # The architecture used to build the Docker image (amd64 for compatibility with most servers).
```

> **Tip:**
> For more details, refer to the official [Kamal documentation](https://kamal-deploy.org/docs/configuration/overview/).

Procedure: Manage secrets

In production, Rails requires a valid `SECRET_KEY_BASE` for encryption and secure operations. Perform the steps below to configure it correctly:

1. Run one of the following commands to generate a strong `SECRET_KEY_BASE`:

```BASH
bin/rails secret
# or
ruby -rsecurerandom -e 'puts SecureRandom.hex(64)'
# or, if using your built Docker image:
docker run --rm  <your-image> ./bin/rails secret
```

2. Update your `config/deploy.yml` file by adding the generated key to your environment configuration:

```YAML
env:
  clear:
    RAILS_ENV: production
    PORT: "3000"
    SECRET_KEY_BASE: <%= ENV.fetch("SECRET_KEY_BASE") %>
```

3. Before running the `kamal deploy` command, export the key to your environment:

```BASH
export SECRET_KEY_BASE="<your-generated-value>"
```

Once deployed, your application will use the provided `SECRET_KEY_BASE` value for securing sensitive operations.

Procedure: Run the first-time server setup

Run the `kamal setup` command to prepare the server for deployment.

> **Note:**
> You need to run this command only if you are deploying to a fresh server. The procedure installs Docker (if needed), configures networks and volumes, boots accessory services, and performs the initial deployment. If Docker and all required services are already installed and the application was deployed before, you can skip this step and go directly to deploying the application.

Procedure: Deploy your application

Now that you configured your deployment and made sure the wev server is ready, you can deploy the application.

1. Run the following command from the RubyMine terminal.

```BASH
kamal deploy
```

Kamal will do the following:

* Build the Docker image locally

* Push it to your registry

* Establish an SSH connection to the server

* Pull the new image

* Launch the application in the configured environment

2. Once the deployment is complete, open your browser and visit the URL you configured for your application.

## Troubleshooting

Procedure: SSH keeps asking for a passphrase/password

1. Load your SSH key into the agent to avoid passphrase prompts:

```BASH
ssh-add ~/.ssh/id_ed25519
```

2. Add your SSH key to the macOS Keychain for persistent access:

```BASH
ssh-add --apple-use-keychain -K ~/.ssh/id_ed25519
```

3. Ensure SSH uses the correct key by configuring `~/.ssh/config`:

```BASH
Host your-server-ip
  User your-username
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes
```

4. Test the SSH connection to verify everything works:

```BASH
ssh your-username@your-server-ip
```

### Your page returns 404

Procedure:

* Check whether requests reach Rails:

```
# in one shell
kamal app logs -f
# in another shell
curl -I http://app.example.com/
```

If logs are empty, fix the DNS or proxy. If Rails logs show a 404, add a root route in your app.

* Check the proxy is routing and healthy:

```
kamal proxy ps
kamal proxy logs -f
curl -I -H "Host: app.example.com" http://127.0.0.1
```

Use a health check path that returns 200 (for example, `/up`) in `deploy.yml`.

* Confirm the app listens on the right port (default 3000) and binds `0.0.0.0`:

```
curl -I http://127.0.0.1:3000/
```

## Rollback

Roll back the application to a previous version if the current deployment has issues. This can help quickly restore a stable state.

Procedure:

1. First, list the available containers to identify previous versions:

```
kamal app containers -q
```

2. Then, roll back to a previous image by specifying the desired version or the latest stable one:

```
kamal rollback
```

3. After the rollback, monitor logs and the app’s health to ensure the previous version is running correctly.

> **Note:**
> Rollback works while old images are still present on the server (pruned after the retention period).

## See also

* [Kamal documentation](https://kamal-deploy.org/docs/)

* [Kamal on GitHub](https://github.com/basecamp/kamal)

* [Ruby on Rails Guides](https://rubyonrails.org/)

