Déployer une application Rails avec Kamal sur un VPS

AtelierFix fonctionne… sur le portable de Modou. Tant qu’il n’est pas en ligne, personne ne peut s’en servir à distance, et un disque qui lâche emporte tout. Mettre une application Rails en production a longtemps été l’étape qui décourageait : serveurs à configurer, certificats SSL à bricoler, déploiements qui cassaient à la moindre erreur. Rails 8 change la donne en intégrant Kamal, un outil qui empaquette votre application dans un conteneur Docker et la déploie sur n’importe quel serveur en deux commandes, HTTPS compris. On va mettre AtelierFix en ligne sur un VPS abordable.

À la fin, votre application répondra sur https://votredomaine, avec un certificat valide obtenu automatiquement, et déployer une nouvelle version tiendra en une seule commande.

🎯 Ce que vous allez apprendre

• Comprendre ce que Kamal fait réellement : conteneur, registre, proxy ;
• Configurer config/deploy.yml pour votre serveur et votre domaine ;
• Gérer les secrets sans les exposer dans le dépôt ;
• Persister une base SQLite entre deux déploiements ;
• Lancer le premier déploiement, puis les suivants, et lire les journaux.

🛠️ Ce que vous allez construire

AtelierFix en production : l’application servie depuis un VPS, derrière un nom de domaine, en HTTPS automatique, avec une base de données qui survit aux mises à jour. Vous repartirez avec un cycle de déploiement professionnel — celui qu’utilisent de vraies équipes Rails.

Prérequis

• AtelierFix tel que construit dans les tutoriels précédents, jusqu’à l’authentification.
• Un VPS sous Ubuntu avec accès SSH (l’adresse IP et un accès root ou sudo suffisent).
• Un nom de domaine dont l’enregistrement DNS pointe vers l’IP du VPS.
• Un compte sur un registre d’images gratuit (Docker Hub fait l’affaire).
• Docker installé sur votre machine pour construire l’image.
• ⏱️ Temps estimé : ~60 minutes (hors propagation DNS).

Ce que Kamal fait pour vous

Décortiquons le trajet d’un déploiement. Kamal construit d’abord une image Docker de votre application : une boîte autonome contenant Ruby, vos gems, votre code — tout ce qu’il faut pour tourner, à l’identique partout. Il pousse cette image vers un registre (Docker Hub), puis se connecte à votre serveur en SSH, y télécharge l’image et démarre le conteneur. Devant lui, il installe un petit proxy (kamal-proxy) qui reçoit le trafic, obtient et renouvelle le certificat HTTPS via Let’s Encrypt, et bascule sans coupure vers la nouvelle version à chaque déploiement. Vous n’éditez aucun fichier serveur à la main : tout est décrit dans un seul fichier de configuration versionné avec votre code.

Étape 1 — Configurer config/deploy.yml

Rails a généré ce fichier en créant l’application ; il ne reste qu’à le renseigner. Ouvrez config/deploy.yml et adaptez les valeurs clés à votre situation :

service: atelierfix
image: moncompte/atelierfix

servers:
  web:
    - 203.0.113.10        # l'IP de votre VPS

proxy:
  ssl: true
  host: atelierfix.sn      # votre domaine, DNS pointé vers l'IP

registry:
  username: moncompte
  password:
    - KAMAL_REGISTRY_PASSWORD

env:
  secret:
    - RAILS_MASTER_KEY

Chaque bloc a un rôle précis. service nomme votre application ; image est le nom sous lequel elle sera publiée dans le registre (préfixé par votre identifiant Docker Hub). servers liste les IP de vos serveurs web. Le bloc proxy est le plus gratifiant : ssl: true et un host renseigné suffisent pour que Kamal obtienne un certificat Let’s Encrypt — à condition que le DNS du domaine pointe déjà vers l’IP. Le registry indique où pousser l’image, et env.secret liste les variables sensibles injectées dans le conteneur sans jamais figurer dans le fichier.

Étape 2 — Renseigner les secrets

Deux secrets sont référencés mais pas encore définis : le mot de passe du registre et la clé maîtresse de Rails (celle qui déchiffre vos identifiants chiffrés). Ils vivent dans .kamal/secrets, un fichier exclu du dépôt Git :

KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
RAILS_MASTER_KEY=$(cat config/master.key)

La première ligne lit le mot de passe depuis une variable d’environnement de votre terminal — vous la définissez avant de déployer avec export KAMAL_REGISTRY_PASSWORD=... (un jeton d’accès Docker Hub, plus sûr que votre mot de passe de compte). La seconde récupère la clé maîtresse directement depuis config/master.key, un fichier que Rails a généré et qui ne doit, lui non plus, jamais partir sur Git. Cette clé est indispensable : sans elle, le conteneur ne peut pas déchiffrer ses identifiants et refuse de démarrer.

Étape 3 — Persister la base SQLite

Par défaut, AtelierFix utilise SQLite, dont les données vivent dans un fichier sous storage/. Or un conteneur est éphémère : à chaque déploiement, Kamal en démarre un neuf, et tout ce qui était à l’intérieur disparaît. Si on ne fait rien, chaque mise à jour effacerait clients et réparations. La parade est un volume : un dossier du serveur monté dans le conteneur, qui survit aux redéploiements. Ajoutez dans config/deploy.yml :

volumes:
  - "atelierfix_storage:/rails/storage"

Désormais, le fichier SQLite est écrit sur le serveur, hors du conteneur, et persiste d’une version à l’autre. C’est le réglage que tout le monde oublie au premier déploiement SQLite — et qui se traduit par un « mais où sont passées mes données ?! » après la première mise à jour. Vous, vous le savez.

✅ Point d’étape — config/deploy.yml connaît votre serveur, votre domaine et votre registre ; .kamal/secrets fournit les deux secrets ; un volume protège la base. La configuration est complète, on peut déployer.

Étape 4 — Le premier déploiement

Le tout premier déploiement prépare le serveur (installation de Docker, mise en place du proxy) en plus de lancer l’application. Kamal a une commande dédiée pour cela :

export KAMAL_REGISTRY_PASSWORD=votre_jeton_docker_hub
bin/kamal setup

Soyez patient : Kamal se connecte au VPS, y installe Docker, construit l’image en local, la pousse vers le registre, la télécharge sur le serveur, démarre le conteneur et configure le proxy. La sortie défile, étape par étape. À la fin, l’application tourne. Cette commande setup ne sert qu’une fois par serveur — pour mettre en place ce qui manque ; ensuite, on utilisera deploy.

Étape 5 — Vérifier en HTTPS

Ouvrez https://votredomaine dans le navigateur. AtelierFix répond, et le cadenas du navigateur confirme un certificat valide — obtenu et installé sans une seule manipulation de votre part. Vous tombez sur l’écran de connexion mis en place au tutoriel précédent ; identifiez-vous et naviguez. Votre atelier est en ligne, sécurisé, accessible de n’importe où.

✅ Point d’étape — L’application est servie en HTTPS depuis votre VPS. Si le certificat tarde ou échoue, c’est presque toujours le DNS : vérifiez que votredomaine pointe bien vers l’IP du serveur (la propagation peut prendre quelques minutes à quelques heures), puis relancez le déploiement.

Étape 6 — Déployer une mise à jour

C’est ici que tout le travail de configuration paie. Une fois le serveur en place, livrer une nouvelle version d’AtelierFix — un correctif, une fonctionnalité — tient en une commande :

bin/kamal deploy

Kamal reconstruit l’image, la pousse, démarre le nouveau conteneur, attend qu’il soit sain, puis bascule le trafic dessus et retire l’ancien — sans coupure visible pour l’utilisateur. Deux commandes vous seront vite indispensables pour le suivi : bin/kamal logs affiche les journaux de l’application en production, et bin/kamal console ouvre une console Rails sur le serveur, idéale pour créer le compte de Modou en production ou inspecter des données réelles.

💡 Rails 8.1 a simplifié encore les choses avec des déploiements possibles sans registre externe. Pour débuter, passer par Docker Hub reste la voie la plus documentée ; gardez en tête que l’option « sans registre » existe quand vous voudrez alléger la chaîne.

La check-list avant de lancer setup

Un premier déploiement qui échoue, c’est presque toujours un prérequis oublié, pas une erreur de Kamal. Cinq minutes de vérification valent une heure de débogage. Avant de taper bin/kamal setup, assurez-vous que :

• vous vous connectez en SSH au VPS sans mot de passe (clé SSH en place) : ssh root@203.0.113.10 doit fonctionner d’emblée ;
• l’enregistrement DNS de type A de votre domaine pointe vers l’IP du serveur — sans cela, pas de certificat HTTPS ;
• le fichier config/master.key existe bien dans votre projet (Rails le génère ; s’il manque, vos identifiants chiffrés sont inutilisables) ;
• votre jeton Docker Hub est exporté dans KAMAL_REGISTRY_PASSWORD et le nom d’image dans deploy.yml commence par votre identifiant de registre ;
• le bloc volumes: est présent si vous tenez à vos données SQLite.

Ce réflexe de check-list n’a rien d’enfantin : c’est exactement ainsi que travaillent les équipes qui déploient sereinement. Mieux vaut une minute à relire deploy.yml qu’un quart d’heure à comprendre pourquoi le conteneur redémarre en boucle. Et si malgré tout quelque chose coince, bin/kamal logs est votre premier réflexe : la cause y est presque toujours écrite noir sur blanc, en clair, dans les dernières lignes.

🐞 Pièges fréquents

🌍 Adaptation au contexte ouest-africain

Un VPS d’entrée de gamme — 1 ou 2 Go de RAM — suffit largement pour AtelierFix et coûte quelques milliers de FCFA par mois, souvent réglables par les moyens de paiement locaux selon l’hébergeur. Choisissez une région proche de vos utilisateurs : pour l’Afrique de l’Ouest, un datacenter en Europe (souvent Paris ou Francfort) offre une latence raisonnable, tandis que quelques fournisseurs proposent désormais des emplacements en Afrique. Côté domaine, un .sn, .ci ou un .com classique fonctionne identiquement avec Kamal. Enfin, comme le déploiement construit et transfère une image de plusieurs centaines de Mo, lancez le premier setup sur une bonne connexion ; les déploiements suivants ne transfèrent que les couches modifiées et sont bien plus légers.

✅ Récapitulatif

AtelierFix est passé du portable de Modou à un vrai serveur, accessible en HTTPS depuis n’importe où, avec une base qui survit aux mises à jour. Vous avez configuré un déploiement de bout en bout, compris le rôle du conteneur, du registre et du proxy, et surtout vous tenez désormais un cycle où livrer une version se résume à bin/kamal deploy. C’est l’aboutissement du parcours : une application Rails conçue, peuplée, sécurisée et mise en production.

🧾 Aide-mémoire

💪 À vous de jouer

Après le premier déploiement, créez le compte de Modou directement en production, puis connectez-vous sur le site en ligne.

bin/kamal console

User.create!(email_address: "modou@atelierfix.sn", password: "atelier2026", password_confirmation: "atelier2026")

Tutoriels frères

• Authentification Rails 8 : le générateur natif pas à pas — la sécurité qu’on met enfin en ligne ici.
• Installer Ruby et Rails : l’environnement de A à Z — revenir au début du parcours.

Pour aller plus loin

• 🔝 Retour au guide principal : Ruby on Rails : le guide complet pour débuter
• Documentation officielle : Kamal — Deploy web apps anywhere
• Temps réel : Hotwire Turbo Streams + Rails : temps réel

FAQ

Kamal, est-ce réservé à Rails ?
Non. Kamal déploie n’importe quelle application capable de tourner dans un conteneur Docker. Rails l’intègre par défaut, ce qui rend la prise en main immédiate, mais l’outil est généraliste.

Faut-il vraiment Docker pour déployer ?
Avec Kamal, oui : c’est le conteneur qui garantit que l’application tourne en production exactement comme chez vous. Vous n’avez pas besoin d’être expert Docker pour autant — Rails fournit déjà un Dockerfile prêt à l’emploi.

SQLite en production, est-ce sérieux ?
Pour une application à trafic modéré comme l’outil interne d’un atelier, oui, à condition de persister le fichier sur un volume. Rails 8 a beaucoup investi pour rendre SQLite viable en production. Si la charge grandit, vous migrerez vers PostgreSQL en changeant la configuration de base, sans toucher au reste.

Comment revenir en arrière si un déploiement casse ?
bin/kamal rollback rebascule vers la version précédente, conservée sur le serveur. C’est le filet de sécurité qui rend les déploiements sereins.