Deploying with Kamal

You are an expert in deploying applications with Kamal. Your goal is to run safe, predictable deploys: build and ship the right version to the right hosts, understand what each command does before running it, and manage the deploy lock so concurrent commands never collide.

Before You Start

Read the project's Kamal config before asking the user questions — it tells you the roles, hosts, and destinations you can target.

• config/deploy.yml — the default config file. It defines your servers, roles, registry, and build settings.
• config/deploy.<destination>.yml — destination-specific config (for example config/deploy.staging.yml), selected with -d, --destination.
• .kamal/secrets — where deploy secrets (registry password, env secrets) are read from.

Kamal deploys the currently checked-out Git version by default, and only builds files committed to your Git repository. Commit your changes before deploying, or the deploy will ship stale code.

What kamal deploy Does

kamal deploy builds and deploys your app to all servers, using kamal-proxy to move traffic from the old version to the new one without downtime. The sequence is:

1. Log in to the Docker registry locally and on all servers.
2. Build the app image, push it to the registry, and pull it onto the servers.
3. Ensure kamal-proxy is running and accepting traffic on ports 80 and 443.
4. Start a new container with the version matching the current Git version hash.
5. Tell kamal-proxy to route traffic to the new container once it responds with 200 OK to GET /up on port 80.
6. Stop the old container running the previous version.
7. Prune unused images and stopped containers so servers don't fill up.

If GET /up never returns 200 OK, traffic is not cut over to the new container — your health-check endpoint is what makes the deploy safe.

Walk-Through: A Standard Deploy

# 1. Make sure the version you want to ship is committed and checked out.
git status

# 2. Deploy the checked-out version to all servers.
kamal deploy

# 3. Watch the output. Kamal builds, pushes, pulls, boots the new
#    container, waits for GET /up, cuts traffic over, and prunes.

The deploy takes a lock automatically while it runs (see [Managing the Deploy Lock](#managing-the-deploy-lock)). If another deploy is already running, it fails immediately unless you pass --lock-wait.

First deploy to a fresh server? Use kamal setup instead — it installs Docker, boots accessories, and then runs the deploy. kamal redeploy can only be used after kamal deploy has succeeded at least once.

Targeting Hosts, Roles, and Versions

By default a deploy runs against all hosts and roles. Narrow it with these flags:

# Deploy only the web role
kamal deploy --roles=web

# Deploy to a subset of hosts by wildcard
kamal deploy --hosts='web-*'

# Deploy to the staging destination
kamal deploy -d staging

--version runs the command against a specific app version rather than the checked-out Git hash. To roll back to a previous image instead, use the rollback skill.

Faster Iterations: kamal redeploy

kamal redeploy deploys your app but skips bootstrapping servers, starting kamal-proxy, pruning, and registry login:

kamal redeploy

Use it for repeat deploys to servers that are already set up and already have kamal-proxy running — it's quicker because it does less. You must have run kamal deploy at least once first. redeploy accepts the same targeting flags as deploy.

Skipping the Build or Hooks

# Image is already built and pushed — just roll it out
kamal deploy --skip-push

# Deploy without running pre/post-deploy hooks
kamal deploy --skip-hooks

--skip-push is useful when the image for this version already exists in the registry (for example, built earlier in CI). For what hooks run and when, see the hooks skill.

For the full kamal deploy option list — including --verbose, --quiet, and --config-file — see [references/deploy-options.md](references/deploy-options.md).

Managing the Deploy Lock

Commands that are unsafe to run concurrently take a deploy lock while they run. The lock is an atomically created directory in the .kamal directory on the primary server. Use kamal lock to inspect or manage it directly — for clearing a leftover lock from a failed command, or to block deploys during a maintenance window.

# See whether a lock is held
kamal lock status

# Block deploys during a maintenance window
kamal lock acquire -m "Maintenance in progress"

# Clear the lock when you're done
kamal lock release

When a lock is held, kamal lock status reports who holds it, the version, and the message:

Locked by: Deployer at 2024-04-05T08:32:46Z
Version: 75bf6fa40b975cbd8aec05abf7164e0982f185ac
Message: Maintenance in progress

Waiting for the Lock

kamal deploy and other commands that take the lock automatically fail immediately if the lock is already held. Pass --lock-wait to make them poll and retry until it's released:

kamal deploy --lock-wait

--lock-wait only waits on locks another command took automatically while running. A lock set manually with kamal lock acquire is not waited on — the command fails immediately with Deploy lock held manually, not waiting. This is by design: a manual lock means "humans, stay out."

Tune the wait with:

kamal deploy --lock-wait --lock-wait-timeout 300 --lock-wait-interval 10

For the full lock reference and worked example, see [references/lock-reference.md](references/lock-reference.md).

Quick Reference

Related Skills

• build: For building and pushing app images (kamal build), which kamal deploy and kamal redeploy call indirectly.
• hooks: For the pre/post-deploy scripts that run during a deploy and how --skip-hooks affects them.
• rollback: For reverting to a previous image with kamal rollback after a bad deploy.
• app: For managing already-running containers — logs, exec, maintenance mode, and start/stop with kamal app.