Rails 8 Kamal 2 on Digital Ocean with Managed DB

Kamal is Kamal (kamal means amazing in Hindi)

Deploying Rails 8 with Kamal 2 on DigitalOcean sometimes feels like navigating a maze — especially when you’re juggling multiple databases, Docker images, and custom SSH configs.

It took me a fair bit of trial and error to piece everything together, and I found myself running one-off commands just to confirm each moving part was in place. This blog is an attempt to share everything I learned in a single, cohesive narrative, focusing on DigitalOcean’s Managed Databases and storing Docker images in the DigitalOcean Container Registry.

I’ll include every little gotcha that had me stuck for hours. (I am not a smart cookie)

Why Kamal 2?

Rails 8 comes with Kamal (formerly “MRSK”) as an opinionated tool for deployment, but if you’re new to it — or to Docker-based Rails deployments in general — some details can sneak up on you. For example, Kamal automatically runs migrations but won’t seed your database, nor does it create it. Or maybe you need to tweak how multiple databases connect (production, queue, cache, cable). Throw in DigitalOcean’s registry and managed Postgres, and you have plenty of room for configuration mishaps.

I’ll walk through what I did, highlight the quirks, and show how to test each part so you’re never left guessing what went wrong.

Note: This is not hardening any VPS, which I’ll cover in a later blog.

DigitalOcean Setup and Auth Steps

Before even touching your Rails app, you should have your DigitalOcean account and CLI ready to go. If you’re using the DigitalOcean Container Registry and Managed Databases, these commands helped me get set up quickly:

doctl auth init
docker login registry.digitalocean.com

The doctl auth init command configures the DigitalOcean CLI, letting you create databases, droplets, etc., without logging in through the web interface. And docker login registry.digitalocean.com ensures you can push/pull images to your private registry on DigitalOcean. (I decided to store my container images there instead of Docker Hub.)

Testing Rails in Production Locally

Sometimes, you just want to sanity-check your Rails production environment without the overhead of a full container build. To poke around, I’d run:

rails c -e production

This command loads the production environment in your local Rails console. If there are issues with your production gems, environment variables, or configurations, you’ll likely see them here before deploying.

Another common pitfall is email configuration. If you haven’t set up a mail service, errors can cascade. You can silence those by adding these lines in config/environments/production.rb:

config.action_mailer.raise_delivery_errors = false
config.action_mailer.perform_deliveries = false
config.action_mailer.delivery_method = :test

Now you won’t get blocked by an unconfigured mailer when you just want to see if your app boots. At least you can have a live web app which you can play with.

Database Configuration with DigitalOcean Managed Databases

DigitalOcean Managed Databases provide a hostname, port, username, and password. You plug all that into config/database.yml. If you have multiple databases (like for caching or background jobs), it might look something like:

# We are using PostgreSQL, but you can use Sqlite, Mysql or anything else
default: &default
  adapter: postgresql
  encoding: unicode
  pool: <%= ENV[“RAILS_MAX_THREADS”] { 5 } %>
  <% if ENV[“DB_HOST”] %>
  host: <%= ENV[“DB_HOST”] %>
  username: postgres
  password: postgres
  <% end %>

production:
  primary: &primary_production
    <<: *default
    host: <%= ENV[“PRODUCTION_DB_HOST”] %>
    port: <%= ENV[“PRODUCTION_DB_PORT”] %>
    username: <%= ENV[“PRODUCTION_DB_USERNAME”] %>
    password: <%= ENV[“PRODUCTION_DB_PASSWORD”] %>
    database: prod 
  cache:
    <<: *primary_production
    database: prod_cache
    migrations_paths: db/cache_migrate
  queue:
    <<: *primary_production
    database: prod_queue
    migrations_paths: db/queue_migrate
  cable:
    <<: *primary_production
    database: prod_cable
    migrations_paths: db/cable_migrate

Make sure you set the sslmode to require, as Managed Databases typically expect SSL connections. To confirm connectivity from your local machine, you can use the psql CLI:

psql -h DB_HOST -p DB_PORT -U DB_USERNAME -d DB_NAME

If you can log in, you know your credentials are fine. Don’t forget to close out connections when you’re done.

The Dockerfile

The Dockerfile you use with Kamal dictates how your Rails app is bundled, what system packages are included, and how assets get precompiled. Here’s a condensed version of the one I used (with some extra goodies like nano, htop, and vim — because debugging a production container without them can be painful). If you’re not using Jumpstart Pro or Avo Pro, you can comment out any lines referencing them:

# syntax=docker/dockerfile:1
# check=error=true

ARG RUBY_VERSION=3.3.6
FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base

WORKDIR /rails

RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y curl libjemalloc2 libvips sqlite3 postgresql-client libz-dev libssl-dev libffi-dev && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

ENV RAILS_ENV=“production” \
    BUNDLE_DEPLOYMENT=“1” \
    BUNDLE_PATH="/usr/local/bundle" \
    BUNDLE_WITHOUT=“development”

Notice how there’s a build stage and a final stage to keep the production image lean. Also, Kamal will rely on this Dockerfile to build images before shipping them to your DigitalOcean registry.

The `deploy.yml` (Kamal Config)

Kamal looks for a deploy.yml (by default in config/deploy.yml) to know how to handle servers, images, and environment variables. Here’s a sample:

service: yourbusinessname
image: yourbusinessname
servers:
  web:
    - IP_ADDRESS

This config should work, I had to give KAMAL_REGISTRY_PASSWORD in both secret and in registry

In your ~/.ssh/config, you might have something like:

Host quick_do
  HostName IP_ADRESS
  User root
  IdentityFile ~/.ssh/digital_ocean_dev_vm

Kamal Commands and Testing

After everything is configured, Kamal helps you manage your app lifecycle on the server:

kamal setup (or kamal setup — verbose): Installs Docker and sets up the server.
kamal deploy (or kamal deploy — verbose): Builds your image, pushes it to the registry, and deploys containers on the server.
kamal app logs: Tails the logs so you can see what’s happening in real time.
kamal remove: Removes your containers if you need a clean slate.

Dealing with Local Docker Images

When you’re testing locally, you might accumulate a bunch of leftover images or partial builds. If you’re using Buildx and you need to reset, use:

docker buildx rm kamal-local-docker-container

It’s a quick fix when you start running out of disk space or something seems stuck in Docker caching.

Production Key

Use rails credentials:edit –environment=production to generate the production credentials in config/credentials/. This command creates two files: production.key and production.yml.enc. Kamal often references these files in its secrets configuration, so keep them properly managed and stored securely.

Check the comment I’ve written in the below secrets sample file

KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
PRODUCTION_DB_HOST=$PRODUCTION_DB_HOST
PRODUCTION_DB_PORT=$PRODUCTION_DB_PORT
PRODUCTION_DB_NAME=$PRODUCTION_DB_NAME
PRODUCTION_DB_USERNAME=$PRODUCTION_DB_USERNAME
PRODUCTION_DB_PASSWORD=$PRODUCTION_DB_PASSWORD


# Improve security by using a password manager. Never check config/master.key or config/credentials/*.key into git!
# RAILS_MASTER_KEY=$(cat config/master.key)
# But its gonna be
RAILS_MASTER_KEY=$(cat config/credentials/production.key)

I was writing master.key and then I was tearing off my hair why it was not working

Kamal Bash

A highly useful command for debugging is:

kamal app exec -i "/bin/bash" This command allows you to log into the deployed container and access an interactive Bash shell. Once inside, you can run debugging commands such as inspecting logs, checking installed packages, verifying environment variables, or even manually testing Rails commands.

Wrapping Up the Gotchas

Suppressing emails: If no email service is set up, turn off deliveries in your production environment.
Multiple DB connections: Confirm each one with psql using the credentials from DigitalOcean.
SSH config: Keep your ~/.ssh/config neat so you don’t get confused about which server you’re deploying to.

Once all these pieces are in place, you’ll have a reliable pipeline. The next time you push code, you can just run kamal deploy and watch your app gracefully update. If something fails, you know exactly which logs to inspect and which config to tweak.

Kamal is, in fact, KAMAL.

— Rishi Banerjee
Jan 2025