What Kamal 2 automates

A gem, not a hosting platform

Open this app's Gemfile and one line, with a comment above it, names what this course is about:

# Deploy this application anywhere as a Docker container [https://kamal-deploy.org]
gem "kamal", require: false

Gemfile.lock pins the installed version, kamal (2.12.0). That's Kamal 2, the rewrite that replaced Kamal 1's Traefik-based proxy with its own kamal-proxy and reworked how accessories and secrets work. require: false matters: Kamal isn't a library this app loads at runtime. It's a command-line tool you run from your own machine, driving servers this app never talks to directly.

The problem Kamal solves

Getting a Rails app onto a server by hand takes several steps at minimum. You build a container image, push it somewhere reachable, SSH into the box, pull the image, stop the old process, start the new one, and hope nothing broke in between. Do that more than once and you'll script it. Kamal is that script, written once by people who deploy Rails apps for a living, and driven by one YAML file.

This app's deploy.yml, in outline

# Kamal deployment — single VPS, app + Postgres accessory, kamal-proxy with Let's Encrypt.
# Fill .kamal/secrets (see .kamal/secrets.example) and export NOR_SERVER_IP before deploying.
service: newbieonrails
image: gxolivei/nor

Those two comment lines, written into the config by this app's maintainer, sum up the setup in a sentence. It's one server, this Rails app plus a Postgres accessory container, and kamal-proxy handling HTTPS. service: newbieonrails names this deployment in Kamal's bookkeeping, and every container, network and volume Kamal creates is prefixed with it. image: gxolivei/nor is the Docker image name Kamal builds and pushes; lesson 2 covers where it's pushed to.

What Kamal isn't

Kamal doesn't provision a server for you: NOR_SERVER_IP in that comment has to point at a running Linux machine with Docker installed. It doesn't manage DNS, doesn't pick a cloud provider and doesn't replace Git or a CI service. It takes over after all of that. Given a working server and a container image, it gets your app running there and keeps it running through every later deploy. It removes the old version only once the new one has proven itself healthy.

How this course is organized

Each lesson takes one part of config/deploy.yml, quoted from the current file (with long comments trimmed where noted), and explains what it does on the server.

What this course covers

1. servers, ssh and registry: where the app runs and where its image lives
2. env: clear versus secret, and running background jobs inside the web server's process
3. proxy, SSL and the healthcheck that gates every deploy
4. The volumes and the db accessory: this app's self-managed Postgres
5. aliases and the Kamal commands they wrap
6. Putting it together: one kamal deploy, traced from your laptop to a live server