Omaship
Documentation Menu ▼

Kamal Basics

Omaship uses Kamal for deployment. You don't need to learn Kamal—but here's how it works if you're curious.

You don't need to run these commands. Omaship's CI/CD handles deployment automatically. This page is just reference for developers who want to understand the system.

What is Kamal?

Kamal is a deployment tool from the Rails team (37signals). It deploys Docker containers to any server with zero-downtime and automatic SSL. No Kubernetes, no PaaS, no complexity.

How Deployment Works

When you push to main (or merge a PR), Omaship's CI/CD:

  1. Builds a Docker image of your app
  2. Pushes it to GitHub Container Registry
  3. SSHs into your server via Kamal
  4. Pulls the new image
  5. Starts a new container, waits for health check
  6. Switches traffic (zero downtime)
  7. Removes the old container

Configuration

Kamal configuration lives in config/deploy.yml:

service: my-app
image: ghcr.io/myorg/my-app

servers:
  web:
    hosts:
      - 123.45.67.89

proxy:
  ssl: true
  host: mybusiness.com

registry:
  server: ghcr.io
  username: myorg
  password:
    - KAMAL_REGISTRY_PASSWORD

This is a user-owned file—customize it if you need to add servers, change proxy settings, or adjust the configuration.

Manual Commands (Optional)

If you ever need to run Kamal manually:

# Deploy latest code
kamal deploy

# View application logs
kamal app logs

# Open Rails console on server
kamal app exec -i "rails console"

# Rollback to previous version
kamal rollback

# Check container status
kamal app details

kamal-proxy

Kamal 2.0 uses kamal-proxy instead of Traefik. It handles:

  • SSL certificate provisioning (Let's Encrypt)
  • Traffic routing to containers
  • Zero-downtime deployments
  • Health checks

Learn More

kamal-deploy.org — Official Kamal documentation