Stack Dev Docker sur VPS : environnement prêt pour coder

Un environnement de développement local fonctionne, mais il reste lié à une seule machine : changement de poste, onboarding d'un nouveau collaborateur ou accès depuis un autre pays deviennent des frictions. En centralisant votre stack Docker sur un VPS, vous disposez d'un serveur de développement partagé, toujours allumé, accessible via SSH ou navigateur depuis n'importe où. Vous gagnez également en reproductibilité : chaque service est défini dans un fichier docker-compose.yml, ce qui élimine le fameux problème « ça marche chez moi ».

Une stack complète avec PostgreSQL, Redis, Nginx et une application consomme en pratique 4 Go de RAM minimum — en dessous, l'OOM killer Docker interrompt PostgreSQL ou Redis en cours de migration, sans message d'erreur applicatif. Le VPS doit tourner sous Ubuntu 22.04 LTS ou Debian 12, avec Docker Engine 26+ et Docker Compose v2.22+ installés (la commande s'écrit docker compose, sans tiret). Vérifiez la version avec docker compose version : la fonctionnalité watch utilisée plus loin requiert v2.22 au minimum, sortie en septembre 2023.

La stack de référence déployée par ServOrbit assemble six services complémentaires.

Nginx joue le rôle de reverse proxy frontal : il reçoit les requêtes HTTP sur le port 80 et les route vers PHP-FPM (via FastCGI) ou vers un serveur Node.js. La configuration nginx/default.conf est montée en volume pour rester modifiable sans reconstruire l'image.

PHP-FPM 8.3 (ou Node.js 22 selon le profil de stack) exécute le code applicatif. Les deux variantes sont disponibles dans le Marketplace ServOrbit ; le fichier docker-compose.yml inclut les deux services, désactivez celui dont vous n'avez pas besoin avec profiles.

PostgreSQL 16 stocke les données persistantes. Le port 5432 n'est pas exposé sur l'hôte par défaut — seul le réseau Docker interne dev_net y a accès, ce qui évite toute exposition accidentelle sur l'IP publique du VPS.

Redis 7 sert de cache et de courtier de messages. Comme PostgreSQL, il reste sur le réseau interne (port 6379) et est accessible depuis le code applicatif via le nom de service redis.

Mailpit 1.x remplace un serveur SMTP réel en développement : il capture tous les e-mails sortants et les expose dans une interface web sur le port 8025. Aucune configuration SMTP spéciale côté application — on pointe simplement sur mailpit:1025.

Adminer (port 8080) offre une interface web légère pour gérer PostgreSQL ou MySQL sans client lourd. Il est accessible uniquement depuis la machine elle-même ou via SSH tunnel.

Le docker-compose.yml de la stack déclare trois volumes nommés — postgres_data, redis_data et app_data — montés respectivement dans /var/lib/postgresql/data, /data et /var/www/html. Ces volumes survivent à un docker compose down : les données de la base et les fichiers uploadés restent intacts entre les redémarrages.

Tous les services partagent le réseau interne dev_net de type bridge. Nginx est le seul service à exposer un port sur l'hôte (80) ; les autres restent isolés et communiquent par leur nom de service — postgres, redis, mailpit.

Les variables sensibles (mot de passe PostgreSQL, clé secrète applicative) ne sont jamais écrites en dur dans le docker-compose.yml. Elles sont lues depuis /opt/docker-dev-stack/.env via la directive env_file. Ce fichier est exclu du dépôt Git par .gitignore. Les variables d'environnement non sensibles (port, version PHP, nom de base) peuvent en revanche figurer directement dans le fichier Compose sous la clé environment, pour qu'elles soient visibles à la relecture.

PostgreSQL, Adminer et Redis ne sont pas exposés sur l'IP publique du VPS. Pour y accéder depuis votre poste local, ouvrez un tunnel SSH : ssh -L 5432:localhost:5432 -L 8080:localhost:8080 root@<IP_VPS> crée deux forwards locaux — le port 5432 de votre laptop pointe vers PostgreSQL, et le port 8080 vers Adminer. Votre client SQL habituel se connecte alors sur localhost:5432 comme si la base tournait en local.

Pour les services HTTP (Nginx, Mailpit), deux approches sont possibles. Si vous disposez d'un nom de domaine, configurez un enregistrement A vers l'IP du VPS et adaptez la configuration Nginx pour servir dev.votredomaine.com en HTTP simple (sans TLS, puisque c'est un environnement de développement). Si vous travaillez sans domaine, le tunnel SSH suffit : ssh -L 8025:localhost:8025 root@<IP_VPS> donne accès à Mailpit sur localhost:8025.

En développement, le fichier .env concentre tous les secrets. En production, les secrets Docker (docker secret) ou un gestionnaire de secrets externe (Vault, AWS Secrets Manager) remplacent le fichier plat — un .env versionné par accident expose des credentials dans l'historique Git.

Les limites de ressources (deploy.resources.limits) méritent d'être posées dès le dev : PostgreSQL peut consommer toute la RAM disponible si une requête dérive. Commencez avec memory: 512m sur PostgreSQL, memory: 256m sur Redis et memory: 256m sur PHP-FPM, puis ajustez selon les profils d'utilisation réels.

Ne montez jamais le socket Docker (/var/run/docker.sock) dans un conteneur applicatif sauf nécessité absolue : un conteneur qui accède au socket peut lancer d'autres conteneurs avec des privilèges root sur l'hôte. En développement ce risque est limité, mais l'habitude prise ici sera reproduite en production.

Port déjà occupé. L'erreur Bind for 0.0.0.0:80 failed: port is already allocated indique qu'un service hôte (Apache, nginx système) écoute déjà sur le port 80. Arrêtez le service système (systemctl stop nginx ou systemctl stop apache2) ou changez le port hôte dans docker-compose.yml ("8080:80") et accédez à la stack sur le port 8080.

Permissions de volume. L'erreur Permission denied sur un volume monté provient souvent d'un uid/gid de conteneur différent de celui de l'hôte. Ajoutez user: "1000:1000" dans le service concerné, ou changez les permissions du répertoire hôte avec chown -R 1000:1000 /opt/docker-dev-stack/app.

Réseau bridge introuvable. Le message network dev_net declared as external, but could not be found apparaît si vous utilisez external: true sur un réseau non encore créé. Retirez external: true : Docker Compose crée le réseau automatiquement au premier docker compose up.

RAM insuffisante. PostgreSQL affiche FATAL: out of memory ou redémarre en boucle si le VPS est sous-dimensionné. Vérifiez avec free -m : il faut au moins 4 Go disponibles pour la stack complète. Réduisez shared_buffers dans la configuration PostgreSQL (command: postgres -c shared_buffers=128MB) ou passez à une offre VPS supérieure.