Déployer sur un VPS avec Kamal (Guide complet)

Kamal ne tourne pas sur votre VPS. C’est un outil de déploiement que vous installez sur votre propre machine ou sur votre runner CI, et qui se connecte au serveur en SSH pour faire son travail. Basecamp l’a conçu pour livrer des applications Rails sans Kubernetes, mais il déploie tout ce qui se construit en image Docker.

Cette distinction change ce que vous cherchez. Le VPS est la cible de Kamal : il doit donc être assez grand pour votre application, ses bases de données et quelques jours de versions d’images. L’empreinte de Kamal sur le serveur, elle, est nulle.

Ce que Kamal installe réellement sur le serveur

kamal setup se connecte en SSH (en root par défaut, authentifié par votre clé SSH) et exécute trois étapes : installer Docker s’il est absent, démarrer les accessoires déclarés, puis déployer l’application. Ensuite, l’hôte fait tourner :

• kamal-proxy — un petit proxy HTTP qui occupe les ports 80 et 443, obtient les certificats Let’s Encrypt et retient les requêtes entrantes pendant un déploiement jusqu’à ce que le conteneur de remplacement soit prêt.
• Vos conteneurs applicatifs — un jeu par rôle défini dans config/deploy.yml.
• Les accessoires — Postgres, Redis ou les autres services listés dans la configuration.

Kamal lui-même est une gem (gem install kamal, 2.12.0 à ce jour) et ne laisse aucun démon derrière lui.

Prérequis

Avant de commencer, munissez-vous :

• D’un VPS avec une installation Linux propre et un accès SSH root par clé (Ubuntu 24.04 est un choix raisonnable)
• D’un registre de conteneurs depuis lequel votre serveur peut tirer les images — Docker Hub, GitHub Container Registry ou celui de votre hébergeur
• De Ruby en local pour gem install kamal ; sans Ruby, Kamal s’exécute aussi depuis une image de conteneur, avec quelques limites
• D’un Dockerfile fonctionnel pour votre application

Choisir un hébergeur VPS

Comme le serveur ne fait qu’exécuter des conteneurs, jugez les hébergeurs sur la fiabilité du réseau, la marge de disque et la rapidité avec laquelle vous pouvez reconstruire un hôte :

Pour une comparaison complète, consultez notre comparatif VPS.

DigitalOcean est ici le point de départ le plus simple, car sa documentation couvre précisément le travail au niveau de l’hôte que Kamal ne fait pas à votre place : règles de pare-feu, swap et mises à jour automatiques.

Préparer le serveur

1. Créez le VPS avec une image Ubuntu 24.04 minimale et votre clé SSH associée.
2. Vérifiez que l’accès SSH root fonctionne, puisque c’est ainsi que Kamal se connecte par défaut :

ssh root@votre-ip-vps

3. N’ouvrez que le nécessaire. kamal-proxy termine TLS sur le serveur, les ports 22, 80 et 443 suffisent donc :

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

Vous n’avez pas besoin d’installer Docker vous-même : Kamal s’en charge au premier kamal setup s’il est absent.

Installer Kamal et écrire la configuration

Sur votre machine, dans le répertoire de votre application :

gem install kamal
kamal init

kamal init crée config/deploy.yml. Une configuration minimale fonctionnelle demande un nom de service, une image et au moins un hôte :

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

Les secrets vivent dans .kamal/secrets, que Kamal lit au moment du déploiement. Il cherche d’abord .kamal/secrets-common, puis .kamal/secrets :

KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD

Gardez ce fichier hors du contrôle de version et tirez la valeur de votre environnement shell ou d’un gestionnaire de mots de passe.

Le premier déploiement

kamal setup

Cette seule commande installe Docker, démarre les accessoires, construit et pousse votre image, puis lance l’application. Tous les déploiements suivants se résument à :

kamal deploy

Pour vérifier ce qui tourne sur l’hôte :

kamal app containers

Où l’image est construite

Par défaut, Kamal construit en local, sur la machine depuis laquelle vous le lancez, puis pousse vers le registre. Le serveur ne fait que tirer. Si votre portable est en arm64 et le VPS en amd64, fixez l’architecture cible ou pointez Kamal vers un builder distant :

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

La compilation croisée par émulation est assez lente pour se remarquer à chaque déploiement. Si le VPS est votre seule machine amd64, il peut servir de builder — mais dimensionnez-le alors pour une construction Docker et non pour la seule exécution de l’application, ce qui suppose généralement de monter d’un palier.

Dimensionner le disque

Kamal conserve les anciens conteneurs et images sur le serveur afin que kamal rollback puisse relancer une version précédente sans repasser par le registre. Il les purge au bout de trois jours par défaut. Comptez les données propres à votre application plus environ trois jours de versions d’images et leurs couches de base partagées.

Une image de 1 Go déployée quelques fois par jour tient confortablement sur les 40 Go NVMe de Hetzner. Une image de 3 Go remplit un disque de 25 Go en une semaine, et un disque plein casse le déploiement suivant, pas celui en cours — ce qui rend le problème facile à manquer jusqu’à ce qu’il devienne urgent.

Bascule sans interruption

kamal-proxy ne dirige le trafic vers le nouveau conteneur que lorsque celui-ci répond 200 à GET /up. Deux conséquences :

• Votre application a besoin d’un endpoint /up. Rails en fournit un ; les autres frameworks demandent en général quelques lignes.
• Cet endpoint ne doit répondre 200 que lorsque l’application peut réellement servir des requêtes. S’il répond avant que les connexions à la base soient prêtes, les utilisateurs arrivent trop tôt sur le nouveau conteneur.

Si le contrôle de santé ne passe jamais, le déploiement expire et Kamal laisse l’ancien conteneur servir le trafic.

Sécuriser le déploiement

• Kamal se connecte en root via SSH : désactivez complètement l’authentification par mot de passe et reposez-vous sur les clés.
• Laissez kamal-proxy gérer TLS. Ajouter un second reverse proxy devant ne fait que compliquer le chemin des certificats.
• Ajoutez du swap sur les hôtes à 4 Go. Un déploiement fait tourner brièvement l’ancien et le nouveau conteneur en même temps, et un hôte qui se met à swapper à ce moment-là devient assez lent pour dépasser le délai du contrôle de santé.
• Gardez le mot de passe du registre dans .kamal/secrets plutôt que dans config/deploy.yml, qui est versionné.

Derniers conseils

• Lancez kamal deploy depuis la CI une fois le chemin manuel validé. La configuration est identique, seule la source des secrets change.
• kamal rollback [version] est instantané tant que l’ancienne image est encore sur le disque : vérifiez avec kamal app containers qu’une cible de rollback existe toujours.
• Déployer une seconde application sur le même hôte est pris en charge par Kamal 2 — kamal-proxy route par nom d’hôte, chaque application a donc simplement besoin de son propre service et de son proxy.host.

Pour approfondir le choix du serveur sous-jacent, consultez notre comparatif VPS.