Docker pour les développeurs Laravel : guide pratique

« Ça marche sur ma machine » est probablement la phrase la plus entendue dans une équipe qui ne containerise pas ses projets Laravel. Docker permet de figer l’environnement d’exécution (PHP, extensions, base de données, services) et de le partager à l’identique entre tous les développeurs et l’environnement de production. Voici comment structurer un setup Docker pratique pour un projet Laravel.

Sommaire

1. Pourquoi containeriser un projet Laravel
2. Les services d’une stack Laravel typique
3. Structurer le Dockerfile PHP
4. Le docker-compose.yml
5. Volumes et performance sur macOS/Windows
6. Les commandes du quotidien
7. Pièges fréquents

Pourquoi containeriser un projet Laravel

Un projet Laravel dépend d’une version précise de PHP, d’extensions spécifiques (pdo_mysql, redis, gd, intl…), d’une base de données, souvent de Redis pour le cache et les files d’attente, parfois de Node pour la compilation des assets. Sans conteneurisation, chaque développeur doit installer et maintenir cette stack localement, avec le risque de divergences de versions. Docker élimine ce problème : l’environnement est décrit une fois, dans des fichiers versionnés avec le code, et reproduit à l’identique partout.

Les services d’une stack Laravel typique

Une stack Docker pour Laravel comprend généralement : un conteneur PHP-FPM (ou PHP avec le serveur intégré en développement), un serveur web (Nginx), une base de données (MySQL ou PostgreSQL), Redis pour le cache et les queues, et éventuellement un conteneur Node pour Vite ou Laravel Mix. Chaque service tourne isolément et communique avec les autres via le réseau interne défini par Docker Compose.

Structurer le Dockerfile PHP

Le Dockerfile PHP part généralement d’une image officielle (php:8.3-fpm), à laquelle on ajoute les extensions nécessaires au projet via docker-php-ext-install, Composer, et les dépendances système requises par certaines extensions (comme libzip pour zip, ou libpq pour PostgreSQL). Séparer les étapes d’installation des dépendances système et applicatives permet de profiter du cache de build Docker et d’accélérer les reconstructions successives.

Le docker-compose.yml

Docker Compose orchestre l’ensemble des services dans un seul fichier déclaratif : quelle image ou quel Dockerfile utiliser pour chaque service, quels ports exposer, quels volumes monter, quelles variables d’environnement injecter, et sur quel réseau les services communiquent entre eux. C’est ce fichier qu’un nouveau développeur exécute avec une seule commande pour obtenir un environnement fonctionnel, sans rien installer d’autre que Docker.

Volumes et performance sur macOS/Windows

Sur Linux, monter le code source en volume ne pose pas de problème de performance notable. Sur macOS et Windows, en revanche, le système de fichiers partagé entre l’hôte et les conteneurs peut fortement ralentir les opérations I/O intensives (notamment les tests, ou le chargement de nombreux fichiers PHP). Des solutions existent : volumes nommés pour les dossiers volumineux (vendor, node_modules), ou des outils dédiés qui optimisent la synchronisation des fichiers selon l’OS hôte.

Les commandes du quotidien

Au quotidien, l’essentiel tient en quelques commandes : docker compose up -d pour démarrer la stack en arrière-plan, docker compose exec app php artisan migrate pour exécuter une commande Artisan dans le conteneur applicatif, docker compose logs -f pour suivre les journaux, et docker compose down pour tout arrêter proprement. L’objectif est qu’un développeur n’ait jamais besoin d’installer PHP ou MySQL directement sur sa machine.

Pièges fréquents

Les erreurs les plus courantes : oublier de vider le cache de configuration Laravel après un changement de variables d’environnement, utiliser localhost au lieu du nom du service Docker pour joindre la base de données depuis le conteneur applicatif, ou encore laisser les permissions de fichiers générées en conteneur (souvent root) créer des conflits avec l’utilisateur local. Définir un utilisateur non-root dans le Dockerfile et aligner les UID/GID avec l’hôte évite la plupart de ces soucis.

Chez Any In IT, nous mettons en place des environnements Docker reproductibles pour nos projets Laravel, du poste de développement jusqu’au déploiement, afin d’éliminer les écarts entre les environnements et fiabiliser les mises en production.