How to Deploy Applications with Kamal (formerly MRSK)

How to Deploy Applications with Kamal (formerly MRSK)

Kamal is a deployment tool created by the team behind Ruby on Rails. It deploys containerized applications to bare-metal or cloud servers using Docker, without requiring Kubernetes or any orchestration platform. This makes it ideal for deploying to your Breeze instances.

Prerequisites

• Ruby 3.1+ installed on your local machine
• Docker installed on your Breeze server
• SSH access to your target Breeze instance
• A container registry (self-hosted or public)

Installing Kamal

gem install kamal
kamal version

Initializing Your Project

Run kamal init in your project directory to generate the configuration files:

kamal init

This creates config/deploy.yml and a .kamal/ directory with hooks.

Configuring deploy.yml

Edit config/deploy.yml with your Breeze server details:

service: myapp
image: registry.yourdomain.com/myapp

servers:
  web:
    hosts:
      - your-breeze-ip
    labels:
      traefik.http.routers.myapp.rule: Host(`app.yourdomain.com`)

registry:
  server: registry.yourdomain.com
  username: deploy
  password:
    - KAMAL_REGISTRY_PASSWORD

env:
  clear:
    NODE_ENV: production
    PORT: 3000
  secret:
    - DATABASE_URL
    - SECRET_KEY_BASE

traefik:
  options:
    publish:
      - "443:443"
    volume:
      - "/letsencrypt:/letsencrypt"
  args:
    entryPoints.websecure.address: ":443"
    certificatesResolvers.letsencrypt.acme.email: "admin@yourdomain.com"
    certificatesResolvers.letsencrypt.acme.storage: "/letsencrypt/acme.json"

Setting Secrets

Create a .kamal/secrets file (never commit this):

KAMAL_REGISTRY_PASSWORD=your-registry-password
DATABASE_URL=postgres://user:pass@db-host/myapp
SECRET_KEY_BASE=your-long-secret-key

Deploying Your Application

# First-time setup (installs Docker, Traefik, and deploys)
kamal setup

# Subsequent deployments
kamal deploy

# Roll back to the previous version
kamal rollback

# View application logs
kamal app logs

# Open a console on the server
kamal app exec --interactive bash

How Kamal Works

• Builds your Docker image locally or in CI
• Pushes it to your container registry
• SSHs into each server and pulls the new image
• Starts the new container alongside the old one
• Waits for health check to pass, then stops the old container
• Uses Traefik for zero-downtime routing between containers

Tips for Production

• Use accessories for databases, Redis, and other services managed by Kamal
• Configure health checks with healthcheck in deploy.yml
• Run kamal audit to view deployment history
• Set up CI to run kamal deploy after tests pass

Kamal provides a simple, Kubernetes-free deployment workflow that works perfectly with Breeze servers.