Kamal 2 Quick Start - the missing tutorial

Kamal is the new out of the box deployment tool that comes with Ruby on Rails. I'm assuming you already know this and are trying to get up and running quickly so let's skip the formality and get right into it.

Step 1: Get Docker

Yes, you do need to sign up for a Docker account first. Go to https://www.docker.com and sign up for an account. This will take you to your Docker Hub.

From there you will want to select a private repository for your project unless you want your build artifacts made public.

Step 2: Download Docker Desktop

Now you should download docker desktop and install. You should then be able to run docker login in your terminal and log in with your credentials. However, you don't want to necessarily log in with your password for you deploys. You'll want to use an access token instead...

Step 3: Create an Access Token

Go to settings -> personal access tokens in Docker Hub and you can create a token there. Here's the link if you are already logged in: https://app.docker.com/settings/personal-access-tokens.

Now try to run docker login and enter the access token you just generated as a password. It should succeed.

Step 4: Save to .env File

Now what you are going to want to do is create a .env file at the root of your Rails app. This is the part where AI will fail you and the existing documentation is sparse. Do not store this in your encrypted credentials like your other secrets. Kamal specifically looks for this in a .env file.

You should also not commit this to source, Rails by default will have this in the .gitignore file so you should be able to see it's not getting committed after creation.

Step 5: Update Your deploy.yml

Open the config/deploy.yml file. Here we can make some updates.

1. Update the service value with the name of your app.

2. Update the image value with your username slash the name of your app: <your_docker_username>/<name_of_app>

3. Under servers -> web add the IP Address of your deploy target. If this is Digital Ocean like I used, this is the public IP of the server found in the admin panel.

4. Under proxy you will want the ssl value to stay true if you want an ssl to be generated and the host will be the URL of your app including subdomain if you are deploying to a subdomain.

5. Under registry -> username put your Docker username. Leave the password value as is - KAMAL_REGISTRY_PASSWORD.

Note: If you are just testing this and want to have it so you can hit the public IP address of your server in your browser without a domain name, first set the ssl value to false and set the host to the public IP address of the server for testing under servers.

Everything else can remain as is. Here's what it should look like:

# Name of your application. Used to uniquely configure containers.
service: <YOUR_APPLICATION_NAME>

# Name of the container image.
image: <YOUR_DOCKER_USERNAME>/<YOUR_APPLICATION_NAME>

# Deploy to these servers.
servers:
  web:
    - <YOUR_SERVER_IP_ADDRESS>
  # job:
  #   hosts:
  #     - 192.168.0.1
  #   cmd: bin/jobs

# Enable SSL auto certification via Let's Encrypt (and allow for multiple apps on one server).
# Set ssl: false if using something like Cloudflare to terminate SSL (but keep host!).
proxy:
  ssl: true
  host: <YOUR_DOMAIN_NAME_INCLUDING_SUBDOMAIN_IF_APPLICABLE>

# Credentials for your image host.
registry:
  # Specify the registry server, if you're not using Docker Hub
  # server: registry.digitalocean.com / ghcr.io / ...
  username: <YOUR_DOCKER_USERNAME>

  # Always use an access token rather than real password when possible.
  password:
    - KAMAL_REGISTRY_PASSWORD

Step 6: Deploy Time!

Ok, now this last part is very important, it's time to deploy your app. First, make sure that you can ssh into the deploy target from your machine. I like to setup a firewall that only allows my IP Address to SSH into the machine so before you deploy make sure you can ssh root@<YOUR_SERVER_IP_ADDRESS> before running deploy.

Now you can run dotenv kamal deploy and everything should run in your terminal and complete.

That dotenv piece deals with the fact that for some reason Kamal 2 cannot find the .env file by default. After much skimming of git issues and yelling at LLM's I arrived at that single glorious comment. Simply use dotenv kamal deploy and all should work as expected.

I hope this helps with your first Kamal 2 deploy.