Guide de démarrage de Kamal2, l'outil génial de déploiement VPS que j'utilise

Actuellement, le framework full-stack que j'utilise principalement est Next.js 16 et Rails 8. En utilisant Rails, j'ai découvert l'outil de déploiement officiellement recommandé, Kamal. Je l'utilise habituellement pour déployer des projets sur RN et les serveurs Alibaba Cloud. Il est très pratique et simple à utiliser, donc je voudrais maintenant vous présenter les concepts de Kamal2 et comment l'utiliser pour débuter.

Cet article ne commencera pas par des choses trop complexes. Je préfère d'abord clarifier les éléments les plus essentiels de Kamal2 : ce que c'est exactement, ce qu'il peut faire pour nous, comment commencer à l'utiliser, et les opérations les plus courantes. Enfin, je donnerai un cas d'utilisation avec Next.js pour vous aider à appliquer les concepts précédents à un projet concret.

Qu'est-ce que Kamal2

Pour résumer en une phrase, Kamal2 est un outil qui **effectue le déploiement d'applications via SSH + Docker**. Il ne fournit pas une plateforme complète comme Heroku, ni un système d'orchestration lourd comme Kubernetes ; il s'agit plutôt de transformer le « déploiement d'un groupe de conteneurs Docker » en un ensemble de commandes et de configurations reproductibles.

L'idée centrale de Kamal est en fait très simple :

• Un Dockerfile standard en local.

• Utiliser config/deploy.yml pour décrire les cibles de déploiement et les informations de l'image.

• Se connecter au serveur via SSH et y préparer l'environnement Docker.

• Construire l'image localement, la pousser vers le registre, puis laisser le serveur la tirer et l'exécuter.

• Utiliser kamal-proxy pour écouter les ports 80 et 443, et basculer le trafic après que la vérification de santé du nouveau conteneur a réussi.

C'est aussi ce que j'apprécie chez Kamal. Il n'introduit pas trop d'abstractions supplémentaires ; vous savez à peu près ce qu'il fait, donc il est plus facile de diagnostiquer les problèmes.

Dans quels scénarios Kamal2 est-il adapté

Je pense que Kamal est particulièrement adapté aux situations suivantes :

• Vous utilisez déjà Docker pour empaqueter vos applications.

• Vous possédez un ou plusieurs de vos propres serveurs Linux.

• Vous souhaitez un processus de déploiement aussi simple que possible, sans devoir maintenir une plateforme complexe.

• Vous voulez que Rails, Next.js, ou même d'autres services web utilisent la même méthode de déploiement.

En d'autres termes, Kamal ne vise pas à « remplacer Docker », mais à rendre le déploiement Docker plus pratique.

Comprendre d'abord quelques concepts de base

Avant de commencer, je vous recommande de retenir les concepts les plus importants de Kamal.

config/deploy.yml

C'est le fichier de configuration principal de Kamal ; les configurations de déploiement sont lues à partir de là. Vous pouvez le considérer comme le « manuel d'instructions de ce déploiement » : le nom du service, le nom de l'image, la liste des serveurs, le registre d'images, les variables d'environnement, le builder, le proxy, etc., y sont écrits.

.kamal/secrets

C'est l'emplacement par défaut du fichier secrets ; Kamal lit les variables sensibles depuis ce fichier. Par exemple, le mot de passe du registre d'images, ou le RAILS_MASTER_KEY de Rails, ne sont généralement pas codés en dur dans deploy.yml, mais injectés via .kamal/secrets.

kamal setup

C'est la commande la plus importante pour le premier déploiement. La documentation explique clairement qu'elle se connecte au serveur, installe Docker (si nécessaire), se connecte au registre d'images, construit l'image, la pousse, la tire, démarre kamal-proxy, démarre le nouveau conteneur, et bascule le trafic après que GET /up retourne 200 OK.

kamal deploy

C'est la commande la plus courante pour les versions ultérieures. Une fois le premier setup réussi, les déploiements suivants se font généralement avec kamal deploy.

Comment installer Kamal2

Si vous avez déjà un environnement Ruby en local, la méthode d'installation la plus directe est :

gem install kamal

C'est la méthode d'installation standard donnée par la documentation officielle. Si vous n'avez pas Ruby, vous pouvez également exécuter Kamal via Docker, mais la documentation mentionne explicitement que cette méthode a certaines limitations, donc pour débuter, je recommande d'utiliser l'installation par gem.

Une fois l'installation terminée, vous pouvez vérifier la version :

kamal version

Initialiser un projet

Accédez au répertoire de votre projet, puis exécutez :

kamal init

Cette commande initialise les fichiers de base nécessaires à Kamal, les plus importants étant config/deploy.yml et .kamal/secrets.

Si votre projet possède déjà un Dockerfile, alors vous avez déjà une condition préalable cruciale. Le processus de déploiement de Kamal construit par défaut l'image à partir du Dockerfile standard situé à la racine du projet.

Configuration minimale fonctionnelle

Je recommande de commencer avec un petit config/deploy.yml. L'exemple minimal donné par la documentation officielle ressemble à ceci :

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

servers:
  - 203.0.113.10

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

builder:
  arch: amd64

env:
  secret:
    - AUTH_SECRET

Dans cette configuration, les éléments suivants sont les plus importants à comprendre :

• service : Obligatoire, utilisé comme préfixe du nom du conteneur.

• image : Nom de l'image, qui sera poussé vers le registre.

• servers : Liste des machines cibles de déploiement.

• registry : Configuration du registre d'images.

• env.secret : Variables d'environnement à lire depuis le fichier secrets.

• builder.arch : Architecture de construction, l'exemple de la documentation utilise directement amd64.

À ce stade, il ne faut pas chercher à avoir une configuration complète ; l'essentiel est d'abord de garantir que le chemin de base fonctionne.

Configurer les secrets

Ensuite, préparez .kamal/secrets. Par exemple :

KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
AUTH_SECRET=your-auth-secret

Pour un projet Rails, l'exemple de la documentation lit RAILS_MASTER_KEY à partir de config/master.key. C'est aussi l'une des raisons pour lesquelles Rails et Kamal s'intègrent naturellement : les nouveaux projets Rails sont déjà assez facilement raccordés à cette méthode de déploiement.

Ce qui se passe lors du premier déploiement

Une fois la configuration et les secrets prêts, vous pouvez exécuter :

kamal setup

Cette commande fait beaucoup de choses, mais vous pouvez la considérer comme un « déploiement initial complet ». Selon la documentation officielle, elle effectue au moins ces actions :

1. Se connecter au serveur via SSH.

2. Si Docker est manquant sur le serveur, l'installer automatiquement.

3. Se connecter au registre d'images localement et à distance.

4. Construire l'image à l'aide du Dockerfile à la racine du projet.

5. Pousser l'image vers le registre.

6. Faire tirer l'image par le serveur.

7. S'assurer que kamal-proxy fonctionne sur les ports 80/443.

8. Démarrer le nouveau conteneur.

9. Attendre que GET /up retourne 200 OK.

10. Basculer le trafic vers le nouveau conteneur.

11. Arrêter l'ancien conteneur et nettoyer les images et conteneurs inutilisés.

Il y a un point très important ici : **la vérification de santé par défaut est GET /up**. Donc, votre application devrait idéalement disposer d'une interface de vérification de santé légère, sinon le nouveau conteneur pourrait être démarré, mais Kamal ne basculera pas le trafic.

Les déploiements suivants sont beaucoup plus simples

Une fois le premier setup réussi, les mises à jour ultérieures se font généralement en exécutant :

kamal deploy

La documentation l'a clairement établi comme commande de déploiement ultérieure. Vous pouvez la considérer comme le « point d'entrée normal pour les versions » : reconstruire l'image, pousser, tirer, lancer un nouveau conteneur, vérifier la santé, basculer le trafic, arrêter l'ancien conteneur.

Donc, du point de vue de l'expérience utilisateur, ce qui est le plus agréable avec Kamal, c'est que le premier déploiement demande un peu plus de préparation, mais ensuite, tout devient beaucoup plus stable.

Opérations courantes

Pour débuter, je trouve ces commandes les plus utiles :

Initialisation

kamal init

Génère les fichiers de base de déploiement.

Premier déploiement

kamal setup

Fait fonctionner le serveur, Docker, l'image, le proxy et l'application ensemble pour la première fois.

Versions ultérieures

kamal deploy

La commande la plus couramment utilisée au quotidien.

Déploiement multi-environnements

Si par la suite vous commencez à distinguer staging et production, Kamal permet d'utiliser -d pour spécifier une destination, par exemple :

kamal deploy -d staging

La documentation officielle explique que dans ce cas, Kamal fusionne config/deploy.staging.yml avec la configuration de base.

Cette fonctionnalité est très pratique, mais si vous débutez, vous pouvez d'abord savoir qu'elle existe sans vous précipiter à l'utiliser.

Pourquoi s'intègre-t-il bien avec Rails

Les nouveaux projets Rails 8 incluent généralement déjà un Dockerfile, et le processus de déploiement de Kamal est justement basé sur le Dockerfile. De plus, l'écosystème Rails accepte naturellement la chaîne d'outils Ruby gem, donc passer de Rails à Kamal est presque une évidence.

Pour ma part, c'est précisément parce que j'ai d'abord vu cette méthode dans un projet Rails que j'ai commencé à la considérer sérieusement comme une solution de déploiement viable à long terme.

Un cas d'utilisation d'initiation avec Next.js

Pour terminer, voici un exemple plus proche de mon quotidien : si je veux déployer un projet Next.js avec Kamal, je le transforme généralement en une application Docker standard, puis je le confie à Kamal pour le publier.

Première étape : faire en sorte que Next.js génère une version standalone

La documentation de Next.js indique qu'en activant output: 'standalone', l'artefact de build génère .next/standalone, qui contient les fichiers minimaux nécessaires à l'exécution et un server.js. C'est très adapté au déploiement Docker, car cela évite de devoir copier l'intégralité de l'environnement de développement.

Dans next.config.js, vous pouvez écrire :

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
}

module.exports = nextConfig

Notez que la documentation de Next.js mentionne que output: 'standalone' est mieux utilisé avec le server.js généré, plutôt qu'avec next start.

Deuxième étape : préparer le Dockerfile

Un Dockerfile simple pour Next.js peut ressembler à ceci :

FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/static ./.next/static
EXPOSE 3000
CMD ["node", "server.js"]

L'important ici n'est pas l'astuce Docker elle-même, mais l'idée : **d'abord faire de Next.js un conteneur standard et exécutable, puis laisser Kamal gérer le déploiement.**

Troisième étape : écrire la configuration Kamal

Par exemple :

service: my-next-app
image: your-registry-user/my-next-app

servers:
  - 203.0.113.10

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

builder:
  arch: amd64

env:
  clear:
    PORT: 3000
    NODE_ENV: production

La logique de cette configuration est simple :

• Kamal connaît le nom du service.

• Kamal sait où pousser l'image.

• Kamal sait sur quel serveur déployer.

• Une fois le conteneur démarré, l'application écoute sur le port 3000, et le proxy gère le trafic externe.

Quatrième étape : ajouter une interface de vérification de santé

Comme Kamal vérifie par défaut GET /up, j'ajoute une route très simple dans Next.js, par exemple avec App Router :

export async function GET() {
  return Response.json({ ok: true })
}

Placez-la par exemple dans app/up/route.ts, ainsi /up renverra une simple réponse de succès. Cette interface doit être la plus légère possible ; son seul but est de dire à Kamal : le conteneur est prêt à recevoir du trafic.

Cinquième étape : déployer

Enfin, on revient au processus standard de Kamal :

kamal setup

Mise à jour ultérieure :

kamal deploy

Si ce processus fonctionne de manière stable pour un projet Next.js, vous vous rendrez compte que Kamal ne se soucie pas vraiment de savoir si vous utilisez Rails ; ce qui l'intéresse vraiment, c'est que vous puissiez **fournir une image Docker standard, ainsi qu'un service web dont l'état de santé peut être vérifié**.

On s'arrête là pour le moment

Si vous êtes comme moi, que vous avez découvert Kamal via Rails 8, puis que vous avez progressivement migré cette méthode vers un projet Next.js 16, alors le positionnement de Kamal2 est facile à comprendre : ce n'est pas une plateforme, mais un outil qui rend le déploiement Docker auto-hébergé plus ordonné.

Pour débuter, il suffit de maîtriser ces éléments :

• Installer Kamal.

• Initialiser les fichiers de configuration.

• Comprendre deploy.yml et .kamal/secrets.

• Savoir utiliser kamal setup pour le premier déploiement.

• Savoir utiliser kamal deploy pour les mises à jour ultérieures.

• Savoir que la vérification de santé par défaut dépend de GET /up.

Une fois que tout cela fonctionne bien, il sera plus naturel d'explorer les environnements multiples, les accessories, les hooks, les configurations proxy complexes, etc.