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-scripts sur le premier composer install : exécuter les scripts Composer (souvent liés à artisan) avant que le code applicatif ne soit copié casserait le build, puisque artisan n'existe pas encore à ce stage.
  • php artisan config:cache dans 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 que config:cache fige 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 .env diffé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 lancer config:cache dans 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 fichier opcache.ini dédié qui active opcache.validate_timestamps=0 en 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.