Deployen naar een VPS met Kamal (Volledige Gids)

Kamal draait niet op je VPS. Het is een deploytool die je op je eigen machine of CI-runner installeert en die via SSH verbinding maakt met de server. Basecamp bouwde het om Rails-applicaties zonder Kubernetes uit te rollen, maar het deployt alles wat je in een Docker-image kunt bouwen.

Dat onderscheid verandert waar je naar zoekt. De VPS is Kamals doel en moet dus groot genoeg zijn voor je applicatie, de bijbehorende databases en een paar dagen aan imageversies. Kamal zelf legt geen beslag op de server.

Wat Kamal daadwerkelijk op de server achterlaat

kamal setup maakt verbinding via SSH (standaard als root, geauthenticeerd met je SSH-sleutel) en voert drie stappen uit: Docker installeren als het ontbreekt, de opgegeven accessories starten en dan de applicatie deployen. Daarna draait op de host:

• kamal-proxy — een kleine HTTP-proxy die poorten 80 en 443 in beslag neemt, Let’s Encrypt-certificaten ophaalt en inkomende verzoeken tijdens een deploy vasthoudt tot de vervangende container klaar is.
• Je app-containers — één set per rol uit config/deploy.yml.
• Accessories — de Postgres, Redis of andere diensten die je in de configuratie hebt opgegeven.

Kamal zelf is een gem (gem install kamal, momenteel 2.12.0) en laat geen daemon achter.

Vereisten

Voordat je begint heb je nodig:

• Een VPS met een schone Linux-installatie en root-toegang via SSH-sleutel (Ubuntu 24.04 is een verstandige keuze)
• Een container registry waar je server images kan ophalen — Docker Hub, GitHub Container Registry of die van je provider
• Ruby lokaal voor gem install kamal; zonder Ruby kun je Kamal ook vanuit een container image draaien, met enkele beperkingen
• Een werkende Dockerfile voor je applicatie

Een VPS-provider kiezen

Omdat de server alleen containers draait, beoordeel je providers op netwerkbetrouwbaarheid, schijfruimte en hoe snel je een host opnieuw kunt opbouwen:

Voor een volledige vergelijking, zie onze VPS-vergelijking.

DigitalOcean is hier het makkelijkste startpunt, omdat de documentatie precies het werk op hostniveau behandelt dat Kamal niet voor je doet: firewallregels, swap en automatische updates.

De server voorbereiden

1. Zet de VPS op met een minimale Ubuntu 24.04-image en je SSH-sleutel eraan gekoppeld.
2. Controleer of root via SSH werkt, want zo maakt Kamal standaard verbinding:

ssh root@jouw-vps-ip

3. Open alleen wat nodig is. kamal-proxy handelt TLS op de server af, dus poorten 22, 80 en 443 volstaan:

ufw allow 22,80,443/tcp && ufw enable

Docker hoef je niet zelf te installeren. Kamal doet dat bij de eerste kamal setup als het ontbreekt.

Kamal installeren en de configuratie schrijven

Op je eigen machine, in de map van je applicatie:

gem install kamal
kamal init

kamal init maakt config/deploy.yml aan. Een minimaal werkende configuratie heeft een servicenaam, een image en minstens één host nodig:

service: myapp
image: your-registry-user/myapp

servers:
  web:
    hosts:
      - 203.0.113.10

registry:
  username: your-registry-user
  password:
    - KAMAL_REGISTRY_PASSWORD

proxy:
  ssl: true
  host: app.example.com

Secrets staan in .kamal/secrets, dat Kamal tijdens het deployen leest. Het zoekt eerst .kamal/secrets-common en daarna .kamal/secrets:

KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD

Houd dat bestand buiten versiebeheer en haal de waarde uit je shell-omgeving of een wachtwoordmanager.

De eerste deploy

kamal setup

Dat ene commando installeert Docker, start de accessories, bouwt en pusht je image en start de applicatie. Elke volgende deploy is:

kamal deploy

Om te zien wat er op de host draait:

kamal app containers

Waar de image wordt gebouwd

Standaard bouwt Kamal lokaal, op de machine waarvandaan je het start, en pusht daarna naar de registry. De server haalt alleen op. Is je laptop arm64 en de VPS amd64, leg dan de doelarchitectuur vast of wijs Kamal naar een remote builder:

builder:
  arch: amd64
  remote: ssh://[email protected]

Cross-builden via emulatie is traag genoeg om bij elke deploy op te vallen. Is de VPS je enige amd64-machine, dan kan hij ook als builder dienen — maar kies dan de grootte voor een Docker-build en niet alleen voor het draaien van de app, wat meestal een pakket hoger betekent.

De schijf op maat kiezen

Kamal bewaart oude containers en images op de server zodat kamal rollback een vorige versie kan starten zonder opnieuw uit de registry te halen. Standaard ruimt het ze na drie dagen op. Reken op de eigen data van je applicatie plus zo’n drie dagen aan imageversies en hun gedeelde baselagen.

Een image van 1 GB die je een paar keer per dag uitrolt past ruim op de 40 GB NVMe van Hetzner. Een image van 3 GB vult een schijf van 25 GB binnen een week, en een volle schijf breekt de volgende deploy, niet de huidige — waardoor het probleem makkelijk te missen is tot het urgent wordt.

Omschakelen zonder downtime

kamal-proxy stuurt het verkeer pas naar de nieuwe container zodra die GET /up met een 200 beantwoordt. Daaruit volgen twee dingen:

• Je applicatie heeft een /up-endpoint nodig. Rails levert er een; andere frameworks vragen meestal een paar regels.
• Dat endpoint mag pas 200 teruggeven als de applicatie echt verzoeken kan afhandelen. Antwoordt het voordat de databaseverbindingen klaar zijn, dan komen gebruikers te vroeg op de nieuwe container terecht.

Slaagt de health check nooit, dan loopt de deploy in een timeout en laat Kamal de oude container het verkeer bedienen.

De deploy beveiligen

• Kamal verbindt als root via SSH, dus schakel wachtwoordauthenticatie volledig uit en werk met sleutels.
• Laat kamal-proxy TLS afhandelen. Een tweede reverse proxy ervoor maakt alleen het certificaatpad ingewikkelder.
• Voeg swap toe op hosts met 4 GB. Tijdens een deploy draaien de oude en nieuwe container kort tegelijk, en een host die dan gaat swappen wordt traag genoeg om de health-checktimeout te overschrijden.
• Houd het registrywachtwoord in .kamal/secrets in plaats van in config/deploy.yml, dat wel wordt ingecheckt.

Tot slot

• Draai kamal deploy vanuit CI zodra het handmatige pad werkt. De configuratie blijft gelijk; alleen de bron van de secrets verandert.
• kamal rollback [versie] is direct klaar zolang de oude image nog op schijf staat, dus controleer met kamal app containers of er nog een rollbackdoel bestaat.
• Een tweede applicatie op dezelfde host wordt in Kamal 2 ondersteund — kamal-proxy routeert op hostnaam, dus elke applicatie heeft alleen een eigen service en proxy.host nodig.

Meer over het kiezen van de onderliggende server vind je in onze VPS-vergelijking.