A Step By Step Guide With Kamal

I recently discovered Kamal. This article is a tutorial for easily deploying your React app to a VM with HTTPS.

The V2 of Kamal was recently released, and you can watch Donald McBreen’s presentation about it during the Rails World Conference 2024. video

What is Kamal?

Kamal 2 is a tool designed to simplify container deployment on virtual machines. It automates provisioning containers on VMs, including deployment, updates, and monitoring.

Unlike full-fledged orchestrators like Kubernetes, Kamal 2 is more straightforward and better suited for less complex environments. It is ideal for small infrastructures with limited VMs, as it avoids the need for a complex orchestration system.

Using configuration files, you can define your containers and their requirements, and Kamal 2 takes care of the deployment process. It is an efficient and lightweight solution for managing containers on VMs.

Prerequisites

For this tutorial, you will need:

• A project managed with Git
• A VM from your preferred provider
• A domain name (optional but recommended for HTTPS).

In this tutorial, I’ll use OVH for hosting (no sponsored links here). You also need to install Ruby.

Project Setup

I’ll deploy a React app for this tutorial, but you can deploy any project (front or back). The only requirement is that it must be dockerized. You can reuse the Dockerfile below for Angular or Vue projects as well.

yarn create vite my-app-name --template react-ts

Dockerfile

FROM node:20-alpine AS builder

WORKDIR /appCOPY package.json yarn.lock ./RUN yarn install --frozen-lockfileCOPY . .RUN yarn buildFROM nginx:stable-alpineCOPY --from=builder /app/dist /usr/share/nginx/htmlEXPOSE 80CMD ["nginx", "-g", "daemon off;"]

This Dockerfile uses a two-step build process. First, the project is built using Node.js. Then, the compiled content is copied into an Nginx container to serve the app.

VPS Setup

In OVH, navigate to Public Cloud > Instance > Create an Instance.

Follow the steps to create the cheapest instance with this configuration:

• 2 GB RAM
• 1 vCore (2 GHz)
• 25 GB NVMe storage
• 100 Mbit/s bandwidth

The trickiest part is generating and uploading your SSH key:

cd ~/.ssh
ssh-keygen -f kamal
cat kamal.pub

Copy the output of cat kamal.pub and paste it into the form provided by OVH.

Once the VM is created, you should see its public IP address, which we’ll use later.

Recap

At this point, you should have:

• A React project (or any other app) dockerized with a Dockerfile.
• An SSH key is created and linked to your VM.
• The public IP address of your VM.

VM Configuration

You must connect to your VM once to install Docker and configure permissions. Use the following command:

ssh -i name_of_ssh_key ubuntu@your_public_ip

# Example with placeholder data:
ssh -i kamal ubuntu@94.114.12.48

Once connected, install Docker:

sudo apt update
sudo apt install docker.io
sudo usermod -aG docker ubuntu

Kamal Setup

Back in your React project directory, initialize Kamal with:

kamal init
Created configuration file in config/deploy.yml
Created .kamal/secrets file
Created sample hooks in .kamal/hooks

Kamal generates the following:

• config/deploy.yml: The main configuration file for deployment.
• .kamal/secrets: A file to store secrets (via environment variables, .env files, or external providers like 1Password).
• .kamal/hooks: A folder with example hooks for your Git workflow.

Now, let’s edit the deploy.yml file.

Kamal Deployment

Before editing deploy.yml, here are two important points:

1. Kamal has detailed documentation on each part of the file here.
2. The kamal deploy command follows these steps:

• Logs into your Docker registry.
• Builds, tags, and pushes the Docker image.
• Connects to the VM.
• Pulls the latest image and restarts the container.

Here’s an example deploy.yml:

service: kamal_test
image: muf-test/kamal_test
servers:
  web:
    - 901.23.10.43
ssh:
  user: ubuntu
registry:
  server: YOUR_DOCKER_URL
  username: YOUR_DOCKER_USERNAME
  password: YOUR_DOCKER_PASSWORD
builder:
  arch: amd64
proxy:
  ssl: true
  host: kamal.test.blue-legion.com
  healthcheck:
    path: /y

• service and image: Define the Docker image to deploy.
• servers: Specify the IP addresses of your VMs.
• ssh: Set the SSH user (default is user).
• registry: Configure your Docker registry credentials.
• proxy: Configure the reverse proxy, including HTTPS (ssl: true), the domain name, and health checks.

Before deploying, add this to your SSH config file (~/.ssh/config):

Host 901.23.10.43
  IdentityFile ~/.ssh/kamal
  User ubuntu
  ForwardAgent yes

Replace the IP and SSH key path with your values.

Now you’re ready to run:

kamal deploy

Within 2 minutes, your app will be live at https://kamal.test.blue-legion.com.

Conclusion

Congratulations! You’ve successfully deployed your app with Kamal.

Kamal is an excellent alternative to more complex deployment tools. It handles container management, automated deployments, and SSL configuration with minimal setup.

For small teams or simpler projects, Kamal is an efficient solution. It even has the potential to replace certain steps in CI/CD pipelines by automating the build and deployment process.

If you’re looking for a lightweight deployment tool, Kamal is definitely worth a try. So, what are you waiting for?