Un Dockerfile qui fonctionne très bien en développement local (image unique, php artisan serve, volume monté sur le code source) devient rapidement un problème en production : image de plusieurs gigaoctets, dépendances de build présentes dans l'image finale, migrations lancées de façon incertaine au démarrage du conteneur, cache de configuration jamais régénéré après un déploiement. Dockeriser pour la production n'est pas la même tâche que dockeriser pour le confort de développement, et les deux méritent des Dockerfiles différents plutôt qu'un seul fichier avec des branches conditionnelles.
Pourquoi l'image de dev ne doit jamais aller en production
Une image de développement typique installe Composer, Node, les extensions PHP de debug (Xdebug), et monte le code en volume pour le hot-reload. Si cette même image part en production :
- Elle embarque les dépendances de dev de Composer (
--dev) et parfois des outils de build Node, ce qui gonfle l'image et élargit la surface d'attaque. - Elle recalcule l'autoload et la configuration à chaque démarrage de conteneur au lieu de les avoir pré-générés au build, ce qui ralentit chaque déploiement et chaque scaling horizontal.
- Elle n'a souvent aucune séparation entre le serveur web et le runtime PHP, ce qui empêche de scaler les deux indépendamment.
Le build multi-stage résout le premier point en séparant explicitement l'environnement de build (Composer, outils de compilation) de l'image finale, qui ne contient que le runtime strictement nécessaire.
Dockerfile multi-stage pour Laravel
# syntax=docker/dockerfile:1
# --- Stage 1 : dépendances Composer (sans dev) ---
FROM composer:2.7 AS vendor
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install \
--no-dev \
--no-interaction \
--no-scripts \
--optimize-autoloader \
--no-plugins
# --- Stage 2 : build des assets front (si Vite/Mix) ---
FROM node:20-alpine AS assets
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY resources resources
COPY vite.config.js ./
RUN npm run build
# --- Stage 3 : image finale PHP-FPM ---
FROM php:8.3-fpm-alpine AS production
RUN apk add --no-cache icu-dev libzip-dev oniguruma-dev postgresql-dev \
&& docker-php-ext-install pdo_pgsql opcache intl zip bcmath
COPY --from=vendor /app/vendor /var/www/html/vendor
COPY --from=assets /app/public/build /var/www/html/public/build
COPY . /var/www/html
WORKDIR /var/www/html
RUN composer dump-autoload --optimize --classmap-authoritative --no-dev \
&& php artisan config:cache \
&& php artisan route:cache \
&& php artisan view:cache
RUN chown -R www-data:www-data /var/www/html/storage /var/www/html/bootstrap/cache
USER www-data
EXPOSE 9000
CMD ["php-fpm"]
Points qui méritent d'être soulignés :
--no-scriptssur le premiercomposer install: exécuter les scripts Composer (souvent liés àartisan) avant que le code applicatif ne soit copié casserait le build, puisqueartisann'existe pas encore à ce stage.php artisan config:cachedans l'image, pas au démarrage du conteneur : une erreur fréquente consiste à lancer ces commandes dans un entrypoint au démarrage. Le problème est queconfig:cachefige les valeurs des variables d'environnement lues au moment du cache ; si l'image est buildée une fois et déployée sur plusieurs environnements avec des.envdifférents, ce cache contiendra les mauvaises valeurs. La bonne pratique est soit de builder une image par environnement avec les bonnes variables injectées au build, soit de lancerconfig:cachedans l'entrypoint si et seulement si les variables d'environnement sont injectées au runtime (ce qui est le cas le plus courant avec Kubernetes/ECS).opcache: l'extension est installée mais pas encore configurée avec un fichieropcache.inidédié qui activeopcache.validate_timestamps=0en production, ce qui évite de recalculer les checksums de fichiers à chaque requête.
Séparer Nginx et PHP-FPM plutôt qu'un conteneur "tout-en-un"
Un conteneur qui lance à la fois Nginx et PHP-FPM via un superviseur de process (supervisord) simplifie le déploiement initial mais empêche de scaler les deux composants indépendamment et complique la collecte des logs (deux process qui écrivent dans le même stdout). Pour une architecture conteneurisée sérieuse, Nginx et PHP-FPM sont deux services distincts qui communiquent par FastCGI :
# docker-compose.yml (exemple de topologie de prod, orchestré ensuite par k8s/ECS en vrai)
services:
nginx:
image: nginx:1.25-alpine
volumes:
- ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
- static_assets:/var/www/html/public:ro
ports:
- "8080:80"
depends_on:
- app
app:
build:
context: .
target: production
volumes:
- static_assets:/var/www/html/public
environment:
- APP_ENV=production
depends_on:
- postgres
- redis
postgres:
image: postgres:16-alpine
environment:
POSTGRES_DB: app
POSTGRES_USER: app
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- pgdata:/var/lib/postgresql/data
redis:
image: redis:7-alpine
volumes:
static_assets:
pgdata:
La configuration Nginx pointe vers app:9000 via FastCGI plutôt que de servir PHP directement :
server {
listen 80;
root /var/www/html/public;
index index.php;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
fastcgi_pass app:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
location ~ /\.(?!well-known).* {
deny all;
}
}
Le cas Symfony : mêmes principes, cache différent
Pour Symfony, le découpage est identique (build multi-stage, Nginx/PHP-FPM séparés), mais le mécanisme de cache diffère : bin/console cache:warmup --env=prod doit tourner après composer install --no-dev et avant de figer l'image, avec APP_ENV=prod explicitement positionné pour que le warmup génère le bon cache (le cache de dev et de prod ne sont pas interchangeables, Symfony distingue les deux par répertoire).
FROM php:8.3-fpm-alpine AS production
# ... extensions identiques à l'exemple Laravel ...
COPY --from=vendor /app/vendor /var/www/html/vendor
COPY . /var/www/html
WORKDIR /var/www/html
ENV APP_ENV=prod
RUN composer dump-autoload --optimize --classmap-authoritative --no-dev \
&& php bin/console cache:clear --env=prod --no-debug \
&& php bin/console cache:warmup --env=prod --no-debug
RUN chown -R www-data:www-data var/cache var/log
USER www-data
EXPOSE 9000
CMD ["php-fpm"]
Les migrations de base de données : jamais dans le CMD du conteneur applicatif
Un piège fréquent est de lancer php artisan migrate ou php bin/console doctrine:migrations:migrate dans l'ENTRYPOINT du conteneur applicatif. Le problème survient dès qu'on scale horizontalement : si trois réplicas démarrent en même temps après un déploiement, les trois lancent la migration simultanément, ce qui peut créer des conditions de course sur des migrations non idempotentes (ajout de colonne en double, verrou de table concurrent).
La pratique robuste est de traiter la migration comme une étape de déploiement séparée et unique, par exemple un Job Kubernetes dédié ou une étape explicite de la pipeline CI/CD, exécutée une seule fois avant que les nouveaux pods applicatifs ne soient mis en route :
# exemple d'étape CI (GitLab CI)
migrate:
stage: deploy
script:
- docker run --rm --env-file .env.production $IMAGE php artisan migrate --force
environment:
name: production
Ce que le Dockerfile seul ne résout pas
Dockeriser correctement l'application ne résout ni la gestion des sessions (qui doit passer par Redis plutôt que le filesystem local dès qu'il y a plus d'un réplica, sous peine de déconnecter aléatoirement les utilisateurs), ni le stockage des fichiers uploadés (qui doit aller vers S3/object storage plutôt qu'un volume local non partagé entre réplicas), ni la configuration des healthchecks (HEALTHCHECK Docker ou probes Kubernetes doivent cibler un endpoint applicatif réel, pas juste vérifier que PHP-FPM répond). Ces sujets sont indépendants du Dockerfile et doivent être traités explicitement dans la configuration applicative avant de considérer le passage en conteneurs comme terminé.
À retenir
Un Dockerfile de production se construit en plusieurs stages pour exclure les dépendances de build de l'image finale, pré-génère les caches de configuration au build plutôt qu'au démarrage, et sépare Nginx de PHP-FPM pour permettre un scaling indépendant. Les migrations de base de données sortent du cycle de vie du conteneur applicatif et deviennent une étape de déploiement explicite et unique, jamais un réflexe de CMD ou d'entrypoint.
