Note: This post will guide you through deploying a Rails application with SQLite using Kamal. If you’re looking to deploy a Rails application with PostgreSQL or MySQL, check out our guide on Deploying Rails application with Kamal and Postgres and Deploying Rails application with Kamal and MySQL.

Pro Tip:

Run the following command to switch the database from sqlite to mysql2:

rails db:system:change --to=mysql

Verify the changes and then you can jump to step 4.

1. Gemfile

First, update the Gemfile to use mysql2 as the database for Active Record.

-# Use sqlite3 as the database for Active Record
-gem "sqlite3", ">= 2.1"
+# Use mysql2 as the database for Active Record
+gem "mysql2", "~> 0.5"

2. Dockerfile

Next, update the Dockerfile to install the default-mysql-client and default-libmysqlclient-dev packages.

 # Install base packages
 RUN apt-get update -qq && \
-    apt-get install --no-install-recommends -y curl libjemalloc2 libvips sqlite3 && \
+    apt-get install --no-install-recommends -y curl default-mysql-client libjemalloc2 libvips && \
     rm -rf /var/lib/apt/lists /var/cache/apt/archives


 # Install packages needed to build gems
 RUN apt-get update -qq && \
-    apt-get install --no-install-recommends -y build-essential git pkg-config && \
+    apt-get install --no-install-recommends -y build-essential default-libmysqlclient-dev git pkg-config && \
     rm -rf /var/lib/apt/lists /var/cache/apt/archives

3. config/database.yml

Update the config/database.yml to use mysql2 as the adapter.

Note: Make sure to replace the password in production block to <%= ENV["MYSQL_ROOT_PASSWORD"] %>

default: &default
  adapter: mysql2
  encoding: utf8mb4
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  username: root
  password:
  host: <%= ENV.fetch("DB_HOST") { "127.0.0.1" } %>

development:
  <<: *default
  database: kamal_demo_development

test:
  <<: *default
  database: kamal_demo_test

production:
  primary: &primary_production
    <<: *default
    database: kamal_demo_production
    password: <%= ENV["MYSQL_ROOT_PASSWORD"] %>
  cache:
    <<: *primary_production
    database: kamal_demo_production_cache
    migrations_paths: db/cache_migrate
  queue:
    <<: *primary_production
    database: kamal_demo_production_queue
    migrations_paths: db/queue_migrate
  cable:
    <<: *primary_production
    database: kamal_demo_production_cable
    migrations_paths: db/cable_migrate

4. config/deploy.yml

Update the config/deploy.yml to add environment variables the db accessory.

<% require "dotenv"; Dotenv.load(".env") %>

service: kamal-demo
image: yourregistryusername/kamal-demo
servers:
  web:
    - 12.34.56.78

proxy:
  ssl: true
  host: example.com

registry:
  username: yourregistryusername
  password:
    - KAMAL_REGISTRY_PASSWORD

env:
  secret:
    - RAILS_MASTER_KEY
    - MYSQL_ROOT_PASSWORD
  clear:
    DB_HOST: kamal-demo-db
    SOLID_QUEUE_IN_PUMA: true

volumes:
  - 'kamal_demo_storage:/rails/storage'

asset_path: /rails/public/assets

builder:
  arch: amd64

accessories:
  db:
    image: mysql:8.0
    host: 12.34.56.78
    port: "127.0.0.1:3306:3306"
    env:
      clear:
        MYSQL_ROOT_HOST: '%'
      secret:
        - MYSQL_ROOT_PASSWORD
    files:
      - db/production.sql:/docker-entrypoint-initdb.d/setup.sql
    directories:
      - data:/var/lib/mysql

5. .env

Add the MYSQL_ROOT_PASSWORD to the .env file.

KAMAL_REGISTRY_PASSWORD=dckr_pat_*******************o
MYSQL_ROOT_PASSWORD=mysql_*******************_password

6. .kamal/secrets

Add the MYSQL_ROOT_PASSWORD to the .kamal/secrets file.

KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
MYSQL_ROOT_PASSWORD=$MYSQL_ROOT_PASSWORD

RAILS_MASTER_KEY=$(cat config/master.key)

7. Deploy

Once done you should be able to deploy your Rails application with Kamal.

kamal deploy

If you get an error saying the service app-name-db already exists you can remove the service using the following command and then re-deploy.:

kamal accessory remove db
kamal deploy

We have a separate guide on how to remove an accessory in Kamal.

What is the Local Docker Registry Feature?

Kamal now supports using a local Docker registry for pushing and pulling application images. When you configure your registry server to start with "localhost", Kamal will:

1. Start a local Docker registry on the specified port
2. Push your app image to this local registry
3. Use SSH port forwarding to make the registry accessible from your app servers

This can reduce deployment time by 10-15 seconds by eliminating the need to push/pull from remote registries.

Configuration

Update your config/deploy.yml to use a local registry:

<% require "dotenv"; Dotenv.load(".env") %>

service: my-app
image: my-app
servers:
  web:
    - 192.168.1.100

registry:
  server: "localhost:5555"

env:
  secret:
    - RAILS_MASTER_KEY

Note: You don’t need to specify username/password when using a local registry.

How It Works

When Kamal detects a localhost registry configuration:

1. Local Registry Startup: Kamal starts a Docker registry container on your deployment machine
2. Image Push: Your application image is pushed to this local registry
3. SSH Port Forwarding: Kamal creates an SSH tunnel from your app servers to the local registry
4. Image Pull: App servers pull the image through the SSH tunnel

Benefits

• Faster Deployments: Eliminates remote registry push/pull time
• Simplified Setup: No need to configure Docker Hub, GHCR, or other remote registries
• Development Friendly: Perfect for staging environments or local development
• Reduced Dependencies: Less reliance on external services

When to Use Local Registry

Good for:

• Development and staging environments
• Quick prototyping and testing
• Situations where you want minimal external dependencies
• Teams that prefer to keep images local during development

Consider Remote Registry for:

• Production deployments
• Multi-developer teams needing shared image access
• CI/CD pipelines
• Long-term image storage and versioning

Troubleshooting

If you encounter issues:

# Check if the local registry is running
docker ps | grep registry

# Verify SSH port forwarding
kamal app details

This feature makes Kamal even more developer-friendly by removing the friction of setting up remote registries for development workflows.

Command:

kamal rollback [VERSION]

To rollback you need to specify the version you want to rollback to.

To find the version you can use the following command to list the available containers.

kamal app containers -q

App Host: 37.27.188.95
CONTAINER ID   IMAGE                                                            COMMAND                  CREATED          STATUS                        PORTS     NAMES
df826bc62d45   deepakmahakale/meetup:9533761e01c8810dc5a678675c0907a91cf7935d   "/rails/bin/docker-e…"   26 seconds ago   Up 25 seconds                 80/tcp    meetup-web-9533761e01c8810dc5a678675c0907a91cf7935d
911a7e9baa16   deepakmahakale/meetup:f34e9efe57fb781c89b3ce3f85427bb230b34d9e   "/rails/bin/docker-e…"   10 days ago      Exited (255) 18 seconds ago             meetup-web-f34e9efe57fb781c89b3ce3f85427bb230b34d9e

Note:
9533761e01c8810dc5a678675c0907a91cf7935d is the version that we just deployed (bad version)
f34e9efe57fb781c89b3ce3f85427bb230b34d9e is the previous stable version that we want to rollback to.

Once we have identified the version we want to rollback to we can run the following command:

kamal rollback f34e9efe57fb781c89b3ce3f85427bb230b34d9e

This will rollback the deployment to the specified version.

Kamal setup provides a default aliases for logs. But, if it’s not available, you can add your own aliases to the deploy.yml file.

aliases:
  logs: app logs -f

and then run the following command:

$ kamal logs

INFO Following logs on 37.xx.xxx.xx.

Kamal setup provides a few default aliases like console, shell, logs, and dbc. You can add your own aliases to the deploy.yml file.

# config/deploy.yml
aliases:
  console: app exec --interactive --reuse "bin/rails console"
  shell: app exec --interactive --reuse "bash"
  logs: app logs -f
  dbc: app exec --interactive --reuse "bin/rails dbconsole"

Now you can run the alias using the kamal command.

Open rails console

$ kamal console

Loading production environment (Rails 8.0.1)
meetup(prod)> Post.count
# => 1

Open bash

$ kamal shell

rails@37:/rails$ ls
Gemfile  Gemfile.lock  README.md  Rakefile  app  bin  config  config.ru  db  lib  log  public  script  storage  test  tmp  vendor

See rails app logs

$ kamal logs

INFO Following logs on 37.xx.xxx.xx.

Open rails dbconsole (sqlite, psql or whatever database you are using)

$ kamal dbc

SQLite version 3.40.1 2022-12-28 14:03:47
Enter ".help" for usage hints.

sqlite> select count(*) from posts;
1

Syntax:

kamal app exec -i 'bundle exec rake <task_name>'

Example:

kamal app exec -i 'bundle exec rake users:import'

A common use case would be to check some data related to users, products or specific scenarios like users with specific attributes, etc.

With Kamal 2.0

With the introduction of aliases in Kamal 2.0 it’s easier to run the Rails console.

You can define aliases in the deploy.yml file:

aliases:
  console: app exec --reuse -i "bin/rails console"

and then run the Rails console using the following command:

kamal console

With Kamal 1.x

With Kamal 1.x, you can run the Rails console using the following command:

kamal app exec -i --reuse "bin/rails console"