DEV Community

Mike Rispoli
Mike Rispoli

Posted on • Edited on

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.

Image description

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
Enter fullscreen mode Exit fullscreen mode

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.

If you have just set this server up you'll want to run dotenv kamal setup first so that it installs docker and all dependencies on the remote server.

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.

Sentry blog image

How to reduce TTFB

In the past few years in the web dev world, we’ve seen a significant push towards rendering our websites on the server. Doing so is better for SEO and performs better on low-powered devices, but one thing we had to sacrifice is TTFB.

In this article, we’ll see how we can identify what makes our TTFB high so we can fix it.

Read more

Top comments (1)

Collapse
 
patrickft profile image
Patrick Feeney

guys for anyone having trouble with the subdirectory not working, what I did after adding the a record to namecheap was run bin/kamal proxy reboot and that fixed the subdomain not working lol. Now I have my subdomain working just fine.

Postmark Image

Speedy emails, satisfied customers

Are delayed transactional emails costing you user satisfaction? Postmark delivers your emails almost instantly, keeping your customers happy and connected.

Sign up