Déployer vos applications avec Dokku sur un VPS

Là où d'autres PaaS embarquent une interface web et un orchestrateur complet, Dokku reste volontairement minimaliste : il s'agit d'un ensemble de scripts shell qui pilotent Docker. Vous poussez votre code avec git push dokku main, Dokku détecte le langage via les buildpacks Heroku ou un Dockerfile, construit l'image et met l'application en ligne. Tout se gère en ligne de commande, ce qui le rend extrêmement léger et prévisible.

Comparés à Dokku, CapRover, Coolify et Easypanel proposent tous une interface graphique, mais au prix d'une empreinte mémoire bien plus lourde. CapRover réserve Docker Swarm et son daemon de supervision ; il recommande 2 Go de RAM en configuration minimale et impose un sous-domaine dédié pour son panneau de contrôle. Coolify 4 s'appuie sur Nixpacks et une base PostgreSQL embarquée : comptez 2 Go de RAM au repos. Easypanel intègre Traefik et un builder Nixpacks, ce qui demande lui aussi 2 Go de RAM dès qu'un build est actif. Dokku, lui, tourne confortablement à partir de 512 Mo de RAM pour une application légère, et n'ajoute aucun composant de contrôle permanent. C'est le choix naturel pour les développeurs qui veulent un workflow Heroku-like sur un petit VPS, sans surcharge mémoire et sans consommer des ressources pour un tableau de bord qu'ils n'utiliseront que quelques minutes par semaine. Son écosystème de plugins officiels (PostgreSQL, Redis, Let's Encrypt, MongoDB) couvre l'essentiel des besoins.

Dokku est le PaaS le plus économe en ressources de cette série.

RAM. 512 Mo suffisent pour une application légère sans build actif. Prévoyez 1 Go de RAM pour un usage courant et 2 Go dès que vos builds utilisent des buildpacks (Node, Ruby, Python compilent en mémoire pendant la construction de l'image) ou que vous hébergez une base de données sur le même VPS. Pour plusieurs applications en parallèle avec PostgreSQL, visez 4 Go.

CPU. 1 vCPU est suffisant pour des applications légères. Les phases de build buildpack sont CPU-intensives et se déroulent à la volée lors de chaque git push : un vCPU partagé peut ralentir le déploiement mais ne bloque pas.

Disque. Comptez 20 Go de SSD minimum. Les images Docker des buildpacks peuvent peser plusieurs centaines de mégaoctets ; ajoutez l'espace pour vos volumes de données (base de données, uploads).

Swap. Sur un VPS d'1 ou 2 Go de RAM, ajoutez systématiquement 2 Go de swap. Sans swap, l'OOM killer du noyau Linux peut tuer un build Node ou Ruby en cours de compilation. La commande de référence : fallocate -l 2G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile.

Système. Ubuntu 22.04 LTS ou 24.04 LTS fraîchement installé, sans Docker ni Nginx préinstallés. Dokku installe ses propres versions. Les ports 22 (SSH), 80 et 443 doivent être ouverts.

DNS. Configurez soit un domaine par application (mon-app.votre-domaine.com), soit un domaine wildcard *.votre-domaine.com pointant vers l'IP du VPS — ce dernier simplifie l'ajout de nouvelles applications sans retouche DNS à chaque fois.

Dokku gère chaque application dans un conteneur isolé. Vous pouvez héberger autant d'applications que votre VPS peut en porter, chacune sur son propre sous-domaine ou domaine personnalisé.

Variables d'environnement. Utilisez dokku config:set pour injecter des secrets ou des paramètres de configuration :

dokku config:set mon-app NODE_ENV=production \
  SECRET_KEY=changeme \
  MAIL_HOST=smtp.votre-domaine.com

Chaque config:set redémarre le conteneur par défaut. Pour regrouper plusieurs modifications sans redémarrage intermédiaire, ajoutez --no-restart et déclenchez manuellement dokku ps:restart mon-app à la fin.

Staging vs production. La pratique courante consiste à créer deux applications sur le même serveur :

dokku apps:create mon-app-staging
dokku apps:create mon-app-production

Chaque remote Git pointe vers sa propre application. Les variables d'environnement sont définies séparément. Les bases de données peuvent être partagées (via des services différents du même plugin) ou distinctes.

Domaines personnalisés. Pour associer un domaine existant à une application :

dokku domains:add mon-app mondomaine.com
dokku domains:add mon-app www.mondomaine.com

Assurez-vous que les enregistrements DNS A de ces domaines pointent vers l'IP du VPS avant d'activer Let's Encrypt.

Dokku gère le zero-downtime via un mécanisme de checks de santé avant bascule. Par défaut, il attend que le nouveau conteneur réponde sur le port applicatif avant de rediriger le trafic. Vous pouvez affiner ce comportement avec un fichier CHECKS à la racine de votre projet :

WAIT=10
TIMEOUT=60
/healthz Application is up

Ce fichier indique à Dokku d'attendre 10 secondes, puis de vérifier que https://mon-app.votre-domaine.com/healthz retourne une réponse contenant « Application is up » dans les 60 secondes. Si le check échoue, Dokku conserve l'ancienne version en production.

Tags et rollback. Dokku conserve les images Docker des déploiements précédents sous forme de tags. Listez-les :

dokku tags:list mon-app

Pour revenir à une version antérieure, déployez le tag souhaité :

dokku tags:deploy mon-app v3

Cette commande rebascule le trafic vers l'image taguée v3 sans aucun rebuild — le rollback est quasi-instantané. Pour créer explicitement un tag de sauvegarde avant un déploiement risqué :

dokku tags:create mon-app stable-avant-migration

Processus. Vous pouvez également gérer l'échelle des processus (workers, schedulers) séparément de l'application web :

dokku ps:scale mon-app web=1 worker=2

Dokku tire sa richesse de son écosystème de plugins officiels. Voici les plus couramment utilisés.

PostgreSQL. Le plus utilisé, déjà présenté. Commandes utiles supplémentaires : dokku postgres:backup ma-base pour un dump manuel, dokku postgres:connect ma-base pour un accès psql interactif.

Redis. Même logique que PostgreSQL :

dokku plugin:install https://github.com/dokku/dokku-redis.git
dokku redis:create mon-cache
dokku redis:link mon-cache mon-app

Injecte la variable REDIS_URL dans le conteneur.

Let's Encrypt. Déjà couvert à l'étape 6. Pour voir l'état des certificats et leurs dates d'expiration :

dokku letsencrypt:list

Cron (scheduler). Dokku peut exécuter des tâches planifiées via son scheduler intégré. Créez un fichier app.json à la racine de votre projet :

{
  "cron": [
    { "command": "php artisan schedule:run", "schedule": "* * * * *" }
  ]
}

Dokku 0.26+ lit ce fichier et crée automatiquement une tâche cron dans le conteneur.

MySQL. Pour les applications qui requièrent MySQL :

dokku plugin:install https://github.com/dokku/dokku-mysql.git
dokku mysql:create ma-db-mysql
dokku mysql:link ma-db-mysql mon-app

Injecte DATABASE_URL au format mysql2://user:password@host:3306/db.

error: failed to push some refs to '[email protected]:mon-app' — permission denied.
Vérifiez que votre clé SSH est bien enregistrée : dokku ssh-keys:list. Si elle est absente, ajoutez-la avec dokku ssh-keys:add admin < ~/.ssh/id_ed25519.pub. Assurez-vous également que le port 22 n'est pas filtré par le pare-feu du VPS.

! [remote rejected] main -> main (pre-receive hook declined).
Cette erreur indique un échec du build côté Dokku. Consultez les logs détaillés avec dokku logs mon-app ou relisez la sortie du git push ligne par ligne — le buildpack affiche l'erreur précise (dépendance manquante, npm install échoué, etc.).

L'application répond 502 Bad Gateway.
Nginx reçoit la requête mais le conteneur ne répond pas. Vérifiez l'état du processus : dokku ps:report mon-app. Si le statut est exited, consultez les logs : dokku logs mon-app. Cause fréquente : l'application n'écoute pas sur le port déclaré dans le Procfile ou la variable PORT injectée par Dokku.

letsencrypt:enable échoue — challenge HTTP-01 timeout.
Le défi ACME requiert que le domaine soit résolu vers l'IP du VPS avant l'activation. Vérifiez la propagation DNS (dig +short mon-app.votre-domaine.com). Si vous êtes derrière un proxy (Cloudflare), désactivez temporairement le proxy (DNS-only) le temps de l'émission du certificat, puis réactivez-le.

Le build est tué par le noyau (OOM) — Killed.
L'OOM killer est intervenu faute de mémoire. Ajoutez du swap (voir le bloc conseil ci-dessus) ou migrez vers un VPS avec 2 Go de RAM. Pendant un build actif, la commande free -m permet de surveiller la mémoire disponible en temps réel.

Dokku couvre le déploiement d'applications à conteneur unique sur un VPS. Si votre architecture évolue vers plusieurs services interdépendants, plusieurs alternatives de la même famille complètent cette approche. CapRover ajoute une interface graphique et un mode cluster Docker Swarm pour les équipes qui préfèrent un tableau de bord. Easypanel simplifie la gestion multi-services avec Nixpacks et une marketplace d'applications. Pour un reverse proxy autonome sans PaaS complet, Caddy ou Nginx Proxy Manager s'intègrent nativement avec Docker. Chacun de ces outils fonctionne sur un VPS Cloud ServOrbit sous Ubuntu LTS.