Déployer des applications web avec Kamal sur un VPS

Kubernetes résout des problèmes de coordination à grande échelle — découverte de service, autoscaling horizontal, namespaces multi-équipes — qui n'existent pas sur un VPS unique ou un petit cluster. Son plan de contrôle lui-même consomme entre 2 et 4 Go de RAM avant d'avoir lancé une seule application. Kamal occupe un terrain différent : il prend votre Dockerfile, construit l'image localement ou sur le serveur, la pousse vers un registre, l'exécute sur vos serveurs via SSH et bascule le trafic sans interruption grâce à kamal-proxy. Toute la configuration tient dans un fichier config/deploy.yml versionné avec votre code. Pas de control plane à maintenir, pas de certificats d'API à renouveler, pas de YAML interminable réparti sur dix ressources. Vous conservez la simplicité opérationnelle d'un VPS — accès SSH direct, docker ps lisible, logs dans un fichier — tout en disposant d'un workflow de déploiement professionnel avec rollback instantané, health checks et HTTPS automatique.

Côté VPS, Kamal exige Ubuntu 22.04 ou 24.04 (ou toute distribution Linux avec Docker 20.10+), un accès SSH par clé (pas de mot de passe), et au minimum 2 vCPU et 2 Go de RAM pour une application web standard avec sa base de données. Kamal peut installer Docker lui-même lors du premier kamal setup, mais le compte SSH doit disposer des droits sudo. Un port 80 et 443 ouverts en entrée et un enregistrement DNS A pointant vers l'IP du VPS sont indispensables avant d'activer le SSL. Côté machine locale, deux options existent : installer la gem Ruby (gem install kamal, requiert Ruby 3.1+) ou utiliser l'image Docker officielle. La version courante est la 2.12.0 (juin 2026). Préparez enfin un registre de conteneurs — Docker Hub, GitHub Container Registry ou un registre privé — ainsi que ses identifiants.

Kamal 2, sorti en septembre 2024 (bundlé par défaut dans Rails 8, sorti en novembre 2024), remplace Traefik par kamal-proxy, un reverse proxy développé en interne par 37signals. Le changement est structurel : Traefik est déclaratif (on lui soumet une configuration et il converge), alors que Kamal est impératif. La version 1 devait interroger l'API de Traefik en boucle pour savoir si le déploiement avait abouti — une source de raceconditions. Avec kamal-proxy, les commandes sont directes et synchrones. Côté configuration, le bloc traefik: disparaît de deploy.yml ; il est remplacé par proxy: avec les clés host, ssl et app_port. Les secrets migrent de .env vers .kamal/secrets, un fichier shell évalué qui peut appeler des CLI externes (op read, bw get). La commande kamal upgrade détecte une configuration v1 et propose un plan de migration automatisé. Enfin, Kamal 2 introduit le déploiement de plusieurs applications sur un même proxy, le mode maintenance (kamal app pause) et le support expérimental des déploiements canary.

Kamal déploie vers tous les serveurs d'un rôle en parallèle par défaut. Pour un cluster de serveurs web, listez leurs IPs sous servers: web:. Pour un déploiement progressif (rolling), ajoutez boot: limit: 2 wait: 10 — Kamal déploiera sur 2 serveurs à la fois avec 10 secondes entre chaque vague. Les rôles permettent de différencier les serveurs : sous servers: déclarez web: (serveurs HTTP) et workers: avec une commande spécifique comme bundle exec sidekiq. Chaque rôle peut avoir ses propres serveurs, secrets et variables. Un seul kamal-proxy tourne sur le serveur désigné primary (le premier de la liste web) — les autres serveurs n'ont que le conteneur applicatif. Pour plusieurs applications sur un même VPS, chacune déclare son propre service: et host: dans son deploy.yml ; kamal-proxy les distingue par hostname et route les requêtes sans configuration additionnelle.

La séparation entre variables claires et secrets est explicite dans Kamal 2. Dans deploy.yml, les variables non sensibles vont sous env: clear: (elles apparaissent dans les logs et l'inspection de conteneur), et les secrets sous env: secret: — leur valeur est lue depuis .kamal/secrets au moment du déploiement et injectée dans le conteneur sans jamais transiter en clair dans une commande shell visible. Chaque rôle (web, workers, accessoires) doit lister explicitement les secrets qu'il utilise ; un secret dans .kamal/secrets n'est pas automatiquement propagé à tous les conteneurs. La commande kamal secrets print affiche les valeurs résolues pour vérifier que la lecture depuis un gestionnaire de mots de passe fonctionne correctement avant un déploiement. Pour les environnements multiples (staging, production), .kamal/secrets.staging et .kamal/secrets.production coexistent ; le fichier .kamal/secrets-common porte les valeurs partagées.

Kamal-proxy gère le cycle de vie TLS complet : il écoute sur le port 80, répond aux défis ACME HTTP-01 de Let's Encrypt, obtient le certificat, le stocke dans un volume Docker sur le serveur et le renouvelle automatiquement avant expiration. La seule précondition est que le nom d'hôte déclaré dans proxy: host: resolve bien vers l'IP du VPS au moment du premier déploiement — le défi ACME est synchrone et bloque le démarrage si le DNS n'est pas propagé. Sur des serveurs multiples hébergeant plusieurs applications, chaque application a son propre host: ; kamal-proxy route par Server Name Indication (SNI) et gère un certificat distinct par domaine. Pour les domaines qui ne nécessitent pas de TLS (environnements internes, staging sans domaine public), il suffit de ne pas inclure ssl: true dans la section proxy: — le proxy répond alors en HTTP sur le port 80.

SSH connection timeout : vérifiez que l'IP du serveur est joignable (ssh -i votre_cle [email protected]) et que le pare-feu autorise le port 22. L'agent SSH doit être actif (eval $(ssh-agent) && ssh-add). Target failed to become healthy : le health check par défaut frappe GET /up — si votre application ne répond pas sur ce chemin, déclarez proxy: healthcheck: path: /health dans deploy.yml. Vérifiez aussi que app_port: correspond au port que le conteneur écoute réellement. Registry authentication error : kamal registry login puis relancez ; en CI, vérifiez que la variable KAMAL_REGISTRY_PASSWORD est bien exportée avant kamal deploy. Port conflict sur le serveur : si un processus externe occupe le port 80 ou 443, kamal-proxy ne peut pas démarrer. Identifiez-le avec ss -tlnp | grep -E '80|443' et arrêtez-le. Kamal setup échoue sur l'installation de Docker : le compte SSH doit avoir les droits sudo. Si l'installation automatique est refusée par la politique système, installez Docker manuellement et relancez kamal setup — il détecte Docker déjà présent et passe à l'étape suivante.

Le fichier de workflow GitHub Actions typique pour Kamal 2 s'articule en deux jobs : un job de test (exécuté sur chaque push) et un job de déploiement conditionnel (déclenché sur push vers main ou publication d'une release). Dans le job de déploiement, installez Ruby et la gem Kamal, puis lancez kamal deploy avec les secrets injectés depuis GitHub Secrets. L'essentiel du fichier .github/workflows/deploy.yml : le job déploiement dépend du job test (needs: test), configure les variables d'environnement (KAMAL_REGISTRY_PASSWORD: ${{ secrets.KAMAL_REGISTRY_PASSWORD }}), installe Kamal avec gem install kamal -v 2.12.0 pour une version épinglée, puis exécute kamal deploy. L'agent SSH est configuré via webfactory/[email protected] avec la clé privée stockée dans les secrets GitHub. Chaque déploiement est ainsi traçable dans l'onglet Actions, avec les logs complets et la possibilité de le déclencher manuellement via workflow_dispatch.

Un VPS Cloud ServOrbit sous Ubuntu 24.04 répond à tous les prérequis de Kamal dès la livraison : accès SSH par clé, réseau 1 Gbit/s et IP dédiée. Le workflow type : créez un enregistrement DNS A pointant app.votre-domaine.com vers l'IP du VPS, lancez kamal setup depuis votre machine locale — Kamal installe Docker, démarre kamal-proxy, obtient le certificat Let's Encrypt et déploie votre application en une passe. Dès lors, chaque kamal deploy depuis votre terminal ou votre pipeline CI applique la mise à jour en zero-downtime. Pour héberger plusieurs projets sur un même VPS, chacun avec son propre domaine et son propre certificat, ajoutez une application dans un second deploy.yml pointant vers le même serveur — kamal-proxy route par hostname sans reconfiguration. La facturation reste celle du VPS, sans surcoût lié au déploiement.