Skip to content
Get packs

Guide · Open source

How to use Kamal: deploy web apps to your own servers

Updated · written with AI from the project's own documentation and checked against our catalogue data

Kamal is an open-source tool from Basecamp that takes a web app packaged in Docker and puts it onto servers you control, such as bare metal machines or cloud VMs. This guide explains what Kamal does, what you need before starting, and the steps to get a first deployment running. It is written for developers who are comfortable with Docker and want to self-host without using a managed platform.

Kamalbasecamp/kamal · ★ 14.7k · MIT

Quick start

  1. 1Check prerequisites. Confirm Docker is available and that you have SSH access to every server you plan to deploy to.
  2. 2Containerize your app. Make sure your web app runs in a Docker container, since Kamal deploys containerized apps.
  3. 3Clone the repository. Run git clone https://github.com/basecamp/kamal to get the source.
  4. 4Read the installation docs. Follow the installation page at kamal-deploy.org/docs/installation for setup details.
  5. 5Configure your servers. Use the configuration docs at kamal-deploy.org/docs/configuration to describe your servers and app.
  6. 6Run commands. Use the commands reference at kamal-deploy.org/docs/commands to deploy and manage your app.

What Kamal does and who it is for

Kamal deploys web apps to one or more servers you control. It uses kamal-proxy to switch requests between old and new containers, which the project describes as a way to avoid interrupting users during updates. It uses SSHKit to run commands across multiple servers.

Kamal was originally built for Rails apps, but the README says it works with any type of web app that can be containerized with Docker.

  • Good fit: developers who want to self-host without a managed platform, teams running one app across several servers over SSH, and Rails developers.
  • Poor fit: people without Docker experience, anyone who wants a hosted platform with no server management, and non-web workloads.

What you need before you install Kamal

The README lists two prerequisites: Docker, and SSH access to the servers you will deploy to. Your app should already run in a Docker container, because Kamal assumes containerized apps.

  • Docker
  • SSH access to each target server

Install Kamal from the repository

The README's install step is to clone the repository from GitHub. For full installation instructions, the project points to the installation page on kamal-deploy.org.

git clone https://github.com/basecamp/kamal

Configure and run your first deployment

Kamal's configuration and commands are documented at kamal-deploy.org under the configuration and commands pages. Follow those pages for the exact file layout and command syntax, since this guide does not reproduce them.

Use the documentation to define the servers and the container image for your app, then run the deploy from your project. Kamal switches traffic through kamal-proxy as new containers come up.

Get help improving the docs

The documentation lives in the basecamp/kamal-site repository. The project asks for help improving it there.

What people use it for

  • Deploying a Rails app to a bare metal server or cloud VM you manage
  • Running the same containerized web app across several servers over SSH
  • Self-hosting a Docker-based web app without a managed platform
  • Updating a running web app with minimal interruption to users

Frequently asked questions

Is Kamal free?

Yes. Kamal is released under the MIT License, a permissive open-source licence. Your costs are the servers you run it on.

What do I need to use Kamal?

The README lists Docker and SSH access to your target servers as prerequisites. Your web app should be containerizable with Docker.

Can Kamal deploy apps that are not Rails?

Yes. The README says Kamal was originally built for Rails but works with any type of web app that can be containerized with Docker.

How do I install Kamal?

The README's install step is to clone the repository with git clone https://github.com/basecamp/kamal. The installation guide at kamal-deploy.org has the full setup.

Does Kamal cause downtime when I deploy?

The README describes zero-downtime deployment. Kamal uses kamal-proxy to switch requests between containers so users are not interrupted during updates.

How does Kamal compare to Dokku, Coolify or Caprover?

Dokku, Coolify and Caprover are comparable self-hosted deployment projects. This source does not include a feature comparison, so check each project's documentation to decide which fits your workflow.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Kamal suits developers and teams who already use Docker and want to deploy web apps to servers they manage over SSH, especially Rails developers. If you want a hosted platform with no server management, or your workload is not a web app, pick a different tool.

Install options & downloads