Docker PrestaShop Headless : Architecture multi-conteneurs pour la production

Monter un Docker PrestaShop headless qui fonctionne sur votre machine locale, c'est l'affaire d'une heure. Le faire tenir en production sans crash à froid, sans fuite de secrets et sans race condition au redémarrage, c'est une autre histoire. Après 193 projets PrestaShop livrés, j'ai constaté que la majorité des architectures Docker que j'audite tombent dans les mêmes pièges — des pièges qui ne se révèlent qu'en conditions réelles, jamais dans un tutoriel Hello World.

Si vous cherchez d'abord à comprendre pourquoi découpler PrestaShop d'un frontend Nuxt et ce que cette stack apporte en termes de performance et de flexibilité, je vous recommande de lire d'abord les coulisses de mon Hub Pro headless. L'article que vous lisez maintenant plonge dans le comment technique DevOps : la conception du docker-compose.yml, le câblage réseau, la persistance des données et les healthchecks qui font la différence entre un POC fragile et un setup de production fiable. Voici le plan : diagnostic des erreurs classiques, architecture détaillée des 5 services, isolation réseau et volumes, puis les solutions concrètes pour fiabiliser l'ensemble.

Les problématiques courantes d'une architecture Docker PrestaShop naïve

Cet article fait partie de notre dossier PrestaShop Headless.

Problématique	Cause principale	Impact métier
Crash au démarrage à froid (erreur 500 générique)	PrestaShop tente de se connecter à MariaDB avant que la base ne soit initialisée — aucun healthcheck ni depends_on conditionnel	Downtime à chaque redémarrage VPS ou déploiement, perte de commandes en cours
Base de données ou Redis accessibles depuis l'extérieur	Services exposés sur 0.0.0.0 par défaut, ports publiés sans restriction	Surface d'attaque élargie, risque d'exfiltration de données clients (RGPD)
Volumes mal montés : perte de modules custom au rebuild	Confusion entre bind mounts et volumes anonymes, chemins erronés dans le docker-compose.yml	Régression fonctionnelle en production, heures de debug pour retrouver les fichiers
Secrets commités dans le dépôt Git	Fichier .env non exclu du versioning, mots de passe en clair dans le YAML ou dans les layers de l'image	Compromission des accès BDD et back-office — 38 % des vecteurs d'attaque cloud sont liés à des secrets mal gérés selon le Sysdig 2024 Cloud-Native Security Report
Assets Nuxt servis par Node au lieu de Nginx	Absence de reverse proxy dédié aux fichiers statiques	TTFB dégradé, consommation mémoire Node inutile, scores Core Web Vitals en chute

Anatomie du docker-compose.yml : les 5 services clés

Selon le Stack Overflow Developer Survey 2024, 87 % des développeurs utilisent Docker en environnement de développement. Pourtant, la transition vers une architecture multi-conteneurs de production exige une rigueur que le mode dev ne demande pas. Voici la structure que j'utilise sur mon propre Hub Pro et que je déploie chez mes clients.

Les cinq services et leur rôle précis dans la chaîne :

1. MariaDB — le moteur de persistance. Volume nommé mariadb_data pour garantir la survie des données entre les rebuilds. Aucun port publié vers l'hôte : il n'écoute que sur le réseau interne Docker.
2. Redis — cache objet et cache de sessions PrestaShop. Même logique d'isolation réseau. Il accélère les requêtes API consommées par le frontend Nuxt et réduit la charge sur MariaDB.
3. PrestaShop (PHP-FPM) — le back-office et l'API webservices. Il expose son socket PHP-FPM à Nginx via un réseau partagé, mais n'est jamais directement accessible depuis l'extérieur. Les modules custom sont montés en bind mount depuis le répertoire hôte.
4. Nuxt (Node SSR) — le frontend headless. Il consomme l'API PrestaShop pour le rendu côté serveur (SSR), ce qui permet de réduire le TTFB de 40 à 60 % par rapport à un thème PrestaShop classique, d'après mes mesures terrain sur le Hub Pro — un chiffre cohérent avec les benchmarks Core Web Vitals de web.dev.
5. Nginx — le seul point d'entrée exposé (ports 80/443). Il sert de reverse proxy vers PHP-FPM et Node, et distribue directement les assets statiques générés par Nuxt (.output/public).

Networking Docker : isoler pour sécuriser

C'est le point que je vois le plus souvent bâclé. Par défaut, Docker Compose crée un réseau bridge unique où tous les services se voient. En production, c'est une faille : si le conteneur Nginx est compromis, l'attaquant a un accès direct à MariaDB. La documentation officielle Docker sur les réseaux bridge recommande explicitement de segmenter les services.

La bonne pratique est de définir deux réseaux dans votre docker-compose.yml :

• frontend_net — réseau partagé entre Nginx, PrestaShop (PHP-FPM) et Nuxt. C'est le seul réseau connecté à l'hôte via les ports publiés de Nginx.
• backend_net — réseau interne (internal: true) réservé à MariaDB, Redis et PrestaShop. MariaDB et Redis n'ont aucune route vers l'extérieur. PrestaShop est le seul service présent sur les deux réseaux, car il doit à la fois répondre à Nginx et interroger la base.

Concrètement, cela donne dans la section networks du Compose :

networks:
  frontend_net:
    driver: bridge
  backend_net:
    driver: bridge
    internal: true

Avec cette topologie, même un scan de ports agressif depuis l'extérieur ne verra jamais MariaDB (3306) ni Redis (6379). C'est une mesure simple qui élimine une surface d'attaque majeure, conforme aux Docker security best practices.

Volumes et persistance : ce qu'il faut monter, et comment

Trois stratégies de montage coexistent dans cette architecture :

• Volume nommé pour MariaDB (mariadb_data:/var/lib/mysql) — géré par Docker, sauvegardable via docker volume inspect, insensible aux docker-compose down sans le flag -v.
• Bind mount pour les modules PrestaShop custom (./modules/custom:/var/www/html/modules/custom) — le code source reste sur l'hôte, versionné dans Git. Au rebuild, les modules sont immédiatement disponibles sans copie manuelle.
• Assets statiques Nuxt servis par Nginx — le dossier .output/public de Nuxt est monté en lecture seule dans Nginx. Les fichiers JS, CSS et images sont servis directement sans passer par Node, ce qui libère le processus SSR pour le rendu dynamique.

Healthchecks et ordre de démarrage : la leçon apprise à la dure

Sur mon propre Hub Pro, j'ai perdu 3 heures à déboguer un crash au démarrage. PrestaShop tentait de se connecter à MariaDB avant que la base ne soit initialisée. Le symptôme était trompeur : une erreur 500 générique dans les logs PHP, sans mention explicite de la base de données. Le conteneur MariaDB affichait pourtant un statut running — mais running ne signifie pas ready.

La solution définitive repose sur deux mécanismes combinés, documentés dans la référence officielle des services docker-compose :

services:
  mariadb:
    image: mariadb:11
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 30s
    volumes:
      - mariadb_data:/var/lib/mysql
    networks:
      - backend_net
    env_file: .env

  prestashop:
    depends_on:
      mariadb:
        condition: service_healthy
      redis:
        condition: service_healthy

Le start_period de 30 secondes laisse le temps à MariaDB d'initialiser les tablespaces InnoDB au premier lancement. Le depends_on avec condition: service_healthy garantit que PrestaShop ne démarre qu'une fois la base réellement prête à accepter des connexions. Depuis cette mise en place, zéro crash à froid en production, y compris après les redémarrages automatiques du VPS.

Dans un projet récent pour un client e-commerce dans le secteur du mobilier (catalogue de 12 000 références), la même race condition provoquait des erreurs intermittentes en staging. L'ajout du healthcheck a non seulement résolu le problème, mais a aussi réduit le temps de déploiement perçu par l'équipe : plus besoin de relancer manuellement les conteneurs après un docker-compose up.

Les solutions pour fiabiliser votre architecture Docker PrestaShop headless

Solution	Complexité	Gain estimé
Healthchecks MariaDB/Redis + depends_on: condition	Faible	Élimination des crashs au démarrage à froid — fiabilité 100 % au reboot
Double réseau Docker (frontend_net / backend_net interne)	Faible	Suppression de la surface d'attaque réseau sur les services de données
Volumes nommés pour MariaDB + bind mounts pour le code custom	Faible	Zéro perte de données au rebuild, workflow Git préservé pour les modules
Fichier .env exclu du versioning + env_file dans le Compose	Faible	Secrets hors du dépôt Git — conformité sécurité et RGPD
Nginx comme unique point d'entrée + assets Nuxt en lecture seule	Moyenne	Réduction du TTFB de 40-60 %, décharge du processus Node SSR
Restart policy unless-stopped sur tous les services	Faible	Reprise automatique après crash OOM ou reboot serveur

"By default, Docker starts a container with a restricted set of capabilities. […] Manage secrets in a way that makes it difficult to accidentally expose them. Use Docker secrets or environment variables loaded from files."

— Docker Documentation, Docker security (2025)

Conclusion : de l'architecture Docker au pipeline de déploiement

Structurer une architecture Docker PrestaShop headless pour la production ne se résume pas à empiler des services dans un fichier YAML. Les décisions qui comptent sont celles qu'on ne voit pas dans un tutoriel : l'isolation réseau qui bloque une attaque latérale, le healthcheck qui évite 3 heures de debug à froid, le volume nommé qui sauve vos données quand un docker-compose down -v accidentel survient. Chaque choix documenté dans cet article est issu de situations réelles rencontrées en production.

Cette architecture Docker est le socle technique. L'étape suivante est de l'automatiser : construire un pipeline CI/CD avec GitHub Actions qui build, teste et déploie cette stack à chaque push. C'est la suite logique de ce parcours technique.

Vous souhaitez structurer ou auditer votre architecture Docker PrestaShop headless pour la production ? Discutons de votre projet : contact@alexandrecarette.fr