In this article, we'll walk through the steps to deploy a Rails API-only application using Kamal. Whether you're a seasoned developer or someone who's just discovered that "bundle install" isn't a jewelry store promotion, this guide will help you get your app up and running in no time.
Prerequisites
A locally working Ruby on Rails app (rails 7 in this example).
This app, for this example, we won't use redis so if you use action cable, you need to have solid_cable configured. And for jobs, solid_queue (I use both here)
Docker Installed: Kamal uses Docker, so you'll need Docker installed. No, you can't skip this step—Docker is the star of this show!
A Server with SSH Access (DigitalOcean here). Think of it as your app's new home.
A container registry in DigitalOcean.
Configuring Kamal
Add this to your gemfile:
gem 'kamal', require: false
gem 'thruster', require: false
Then
bundle install
kamal init
This will create a couple of files:
config/deploy.yml.kamal/secrets
config/deploy.yml should look like this (make sure to update the IPs and the env vars accordingly):
service: your_app_name_api
image: your_user/your_app_name_api
servers:
web:
- 199.xxx.xxx.xx
proxy:
ssl: false
registry:
server: registry.digitalocean.com
username: your_user
password:
- KAMAL_REGISTRY_PASSWORD
builder:
arch: amd64
# Inject ENV variables into containers (secrets come from .kamal/secrets).
env:
secret:
- RAILS_MASTER_KEY
- POSTGRES_PASSWORD
clear:
SOLID_QUEUE_IN_PUMA: true
DB_HOST: your_app_name_api-db
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"
volumes:
- "your_app_name_api_storage:/app/storage"
accessories:
db:
image: postgres:17
host: 199.xxx.xxx.xx
port: 127.0.0.1:5432:5432
env:
clear:
POSTGRES_USER: your_app_name_api
POSTGRES_DB: your_app_name_api_production
POSTGRES_HOST_AUTH_METHOD: trust
secret:
- YOUR_APP_NAME_API_DATABASE_PASSWORD
files:
- config/init.sql:/docker-entrypoint-initdb.d/setup.sql
directories:
- data:/var/lib/postgresql/data
And in .kamal/secrets add:
KAMAL_REGISTRY_PASSWORD=dop_v1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
RAILS_MASTER_KEY=$(cat config/master.key)
YOUR_APP_NAME_API_DATABASE_PASSWORD=anythingyouwant
POSTGRES_PASSWORD=anythingyouwant
You will need a couple of additional files. Run this in your terminal:
touch bin/thrust
touch bin/docker-entrypoint
touch Dockerfile
touch config/init.sql
In bin/thrust add:
#!/usr/bin/env ruby
require "rubygems"
require "bundler/setup"
load Gem.bin_path("thruster", "thrust")
In bin/docker-entrypoint add:
#!/bin/bash -e
# Enable jemalloc for reduced memory usage and latency.
if [ -z "${LD_PRELOAD+x}" ]; then
LD_PRELOAD=$(find /usr/lib -name libjemalloc.so.2 -print -quit)
export LD_PRELOAD
fi
# If running the rails server then create or migrate existing db
if [ "${@: -2:1}" == "./bin/rails" ] && [ "${@: -1:1}" == "server" ]; then
./bin/rails db:prepare
fi
exec "${@}"
The Dockerfile, since it's an api only app, this will be enough:
# syntax=docker/dockerfile:1
# check=error=true
# This Dockerfile is designed for production, not development. Use with Kamal or build'n'run by hand:
# docker build -t your_app_name_api .
# docker run -d -p 80:80 -e RAILS_MASTER_KEY=<value from config/master.key> --name your_app_name_api your_app_name_api
# For a containerized dev environment, see Dev Containers: https://guides.rubyonrails.org/getting_started_with_devcontainer.html
# Make sure RUBY_VERSION matches the Ruby version in .ruby-version
ARG RUBY_VERSION=3.3.1
FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base
# Rails app lives here
WORKDIR /rails
# Install base packages
RUN apt-get update -qq && \
apt-get install --no-install-recommends -y curl libjemalloc2 libvips libpq-dev postgresql-client && \
rm -rf /var/lib/apt/lists /var/cache/apt/archives
# Set production environment
ENV RAILS_ENV="production" \
BUNDLE_DEPLOYMENT="1" \
BUNDLE_PATH="/usr/local/bundle" \
BUNDLE_WITHOUT="development"
# Throw-away build stage to reduce size of final image
FROM base AS build
# Install packages needed to build gems
RUN apt-get update -qq && \
apt-get install --no-install-recommends -y build-essential git libpq-dev pkg-config && \
rm -rf /var/lib/apt/lists /var/cache/apt/archives
# Install application gems
COPY Gemfile Gemfile.lock ./
RUN bundle install && \
rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git && \
bundle exec bootsnap precompile --gemfile
# Copy application code
COPY . .
# Precompile bootsnap code for faster boot times
RUN bundle exec bootsnap precompile app/ lib/
# Final stage for app image
FROM base
# Copy built artifacts: gems, application
COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}"
COPY --from=build /rails /rails
# Run and own only the runtime files as a non-root user for security
RUN groupadd --system --gid 1000 rails && \
useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \
chown -R rails:rails db log storage tmp
USER 1000:1000
# Entrypoint prepares the database.
ENTRYPOINT ["/rails/bin/docker-entrypoint"]
# Start server via Thruster by default, this can be overwritten at runtime
EXPOSE 80
CMD ["./bin/thrust", "./bin/rails", "server"]
Finally, in config/init.sql add:
CREATE DATABASE your_app_name_api_production;
CREATE DATABASE your_app_name_api_production_cable;
Next step is to make sure your database.yml matches the deploy configuration:
production:
primary: &primary_production
<<: *default
database: your_app_name_api_production
username: your_app_name_api
password: your_app_name_api_password
host: your_app_name_api-db
cable:
<<: *primary_production
database: your_app_name_api_production_cable
migrations_paths: db/cable_migrate
You will also need to make sure that config/environments/production.rb has:
config.assume_ssl = true
config.force_ssl = true
config.solid_queue.connects_to = { database: { writing: :production } } # in case you are using solid_queue
If you don't have a commited file in storage/ you will need to add one:
touch storage/.keep
Deploy
Afte commiting all changes with git, we are ready to go:
kamal setup
After a few minutes, you should see your app deployed =)