Deploy web applications with Kamal on a VPS

Kubernetes solves large-scale coordination problems — service discovery, horizontal autoscaling, multi-team namespaces — that simply do not exist on a single VPS or a small cluster. Its control plane alone consumes between 2 and 4 GB of RAM before a single application has launched. Kamal targets a different space: it takes your Dockerfile, builds the image locally or on the server, pushes it to a registry, runs it on your servers over SSH and switches traffic without downtime using kamal-proxy. All configuration lives in a single config/deploy.yml file versioned alongside your code. No control plane to maintain, no API certificates to renew, no YAML spread across ten resource types. You keep the operational simplicity of a VPS — direct SSH access, readable docker ps, logs in a file — while gaining a professional deployment workflow with instant rollback, health checks and automatic HTTPS.

On the VPS side, Kamal requires Ubuntu 22.04 or 24.04 (or any Linux distribution with Docker 20.10+), SSH key access (no password), and at minimum 2 vCPU and 2 GB RAM for a standard web application with its database. Kamal can install Docker itself during the first kamal setup, but the SSH account must have sudo rights. Ports 80 and 443 open inbound and a DNS A record pointing to the VPS IP are required before enabling SSL. On your local machine, two options exist: install the Ruby gem (gem install kamal, requires Ruby 3.1+) or use the official Docker image. The current version is 2.12.0 (June 2026). You also need a container registry — Docker Hub, GitHub Container Registry or a private registry — and its credentials.

Kamal 2, released in September 2024 (bundled by default in Rails 8, released November 2024), replaces Traefik with kamal-proxy, an in-house reverse proxy developed by 37signals. The change is structural: Traefik is declarative (you submit a configuration and it converges), while Kamal is imperative. Version 1 had to poll Traefik's API repeatedly to determine whether a deployment had succeeded — a source of race conditions. With kamal-proxy, commands are direct and synchronous. In terms of configuration, the traefik: block disappears from deploy.yml and is replaced by proxy: with keys host, ssl and app_port. Secrets move from .env to .kamal/secrets, a shell-evaluated file that can call external CLI tools (op read, bw get). The kamal upgrade command detects a v1 configuration and offers an automated migration plan. Kamal 2 also introduces multiple applications on a single proxy, maintenance mode (kamal app pause) and experimental canary deployment support.

Kamal deploys to all servers in a role in parallel by default. For a web cluster, list their IPs under servers: web:. For rolling deployments, add boot: limit: 2 wait: 10 — Kamal will deploy to 2 servers at a time with 10 seconds between batches. Roles let you differentiate servers: under servers: declare web: (HTTP servers) and workers: with a specific command like bundle exec sidekiq. Each role can have its own servers, secrets and variables. A single kamal-proxy runs on the primary server (first in the web list) — other servers only run the application container. For multiple applications on a single VPS, each has its own service: and host: in its deploy.yml; kamal-proxy distinguishes them by hostname and routes requests without additional configuration.

The separation between clear variables and secrets is explicit in Kamal 2. In deploy.yml, non-sensitive variables go under env: clear: (they appear in logs and container inspection), and secrets under env: secret: — their value is read from .kamal/secrets at deploy time and injected into the container without ever appearing in plain text in a visible shell command. Each role (web, workers, accessories) must explicitly list the secrets it uses; a secret in .kamal/secrets is not automatically propagated to all containers. The kamal secrets print command displays resolved values to verify that reading from a password manager works correctly before deploying. For multiple environments (staging, production), .kamal/secrets.staging and .kamal/secrets.production coexist; .kamal/secrets-common holds shared values.

Kamal-proxy manages the complete TLS lifecycle: it listens on port 80, responds to Let's Encrypt ACME HTTP-01 challenges, obtains the certificate, stores it in a Docker volume on the server and renews it automatically before expiration. The only prerequisite is that the hostname declared in proxy: host: resolves to the VPS IP at the time of the first deployment — the ACME challenge is synchronous and blocks startup if DNS has not propagated. On multi-app servers each with their own domain, each application has its own host:; kamal-proxy routes by Server Name Indication (SNI) and manages a separate certificate per domain. For domains that do not require TLS (internal environments, staging without a public domain), simply omit ssl: true from the proxy: section — the proxy then responds in HTTP on port 80.

SSH connection timeout: verify the server IP is reachable (ssh -i your_key [email protected]) and that the firewall allows port 22. The SSH agent must be running (eval $(ssh-agent) && ssh-add). Target failed to become healthy: the default health check hits GET /up — if your application does not respond on that path, declare proxy: healthcheck: path: /health in deploy.yml. Also verify app_port: matches the port your container actually listens on. Registry authentication error: run kamal registry login then retry; in CI, verify the KAMAL_REGISTRY_PASSWORD variable is exported before kamal deploy. Port conflict on the server: if an external process occupies port 80 or 443, kamal-proxy cannot start. Identify it with ss -tlnp | grep -E '80|443' and stop it. Kamal setup fails on Docker installation: the SSH account must have sudo rights. If automatic installation is blocked by system policy, install Docker manually and rerun kamal setup — it detects existing Docker and moves to the next step.

A typical GitHub Actions workflow for Kamal 2 has two jobs: a test job (run on every push) and a conditional deployment job (triggered on push to main or release publication). In the deployment job, install Ruby and the Kamal gem, then run kamal deploy with secrets injected from GitHub Secrets. Key elements of .github/workflows/deploy.yml: the deploy job depends on the test job (needs: test), configures environment variables (KAMAL_REGISTRY_PASSWORD: ${{ secrets.KAMAL_REGISTRY_PASSWORD }}), installs Kamal with a pinned version (gem install kamal -v 2.12.0), then runs kamal deploy. The SSH agent is configured via webfactory/[email protected] with the private key stored in GitHub Secrets. Each deployment is traceable in the Actions tab, with full logs and the option to trigger manually via workflow_dispatch.

A ServOrbit Cloud VPS running Ubuntu 24.04 meets all Kamal prerequisites out of the box: SSH key access, 1 Gbit/s network and a dedicated IP. The typical workflow: create a DNS A record pointing app.your-domain.com to the VPS IP, then run kamal setup from your local machine — Kamal installs Docker, starts kamal-proxy, obtains the Let's Encrypt certificate and deploys your application in one pass. From that point, every kamal deploy from your terminal or CI pipeline applies the update with zero downtime. To host multiple projects on the same VPS, each with its own domain and certificate, add an application in a second deploy.yml pointing to the same server — kamal-proxy routes by hostname without reconfiguration. Billing remains that of the VPS, with no additional deployment overhead.