Sandbox PrestaShop (Docker)

Maturité : sandbox

Environnement de test jetable, pas un livrable client. Il sert uniquement à exercer le plugin titreoepay localement (installation, checkout, webhook). Voir le tableau de maturité.

À quoi ça sert

demo-shop-prestashop/ n’est pas un produit : c’est une fausse boutique PrestaShop 8.1 que l’on lance en Docker pour avoir un vrai marchand sur lequel brancher et tester le plugin de paiement Titreo E-Pay.

Le plugin n’est pas copié dans l’image : le dossier plugins/prestashop/titreoepay/ est monté en volume dans modules/ du conteneur. Conséquence pratique : on modifie le code du plugin sur sa machine, et le changement est immédiatement visible dans la boutique — sans rebuild d’image. La sandbox sert donc de banc d’essai pour le parcours complet : panier → étape paiement → redirection vers la checkout-page → webhook → commande validée.

Elle s’inscrit dans le même docker-compose.dev.yml que le reste de l’écosystème (api, checkout-page, consoles…). Voir l’environnement de dev local et la vue d’ensemble de l’écosystème.

Ce qu’il y a dans le dossier

Fichier	Rôle
demo-shop-prestashop/Dockerfile	Image basée sur prestashop/prestashop:8.1, ajoute curl. Le module n’est pas copié dedans : il arrive par volume.
demo-shop-prestashop/README.md	Procédure de démarrage et de configuration du plugin.
demo-shop-prestashop/init-scripts/10-titreo-webhook-host.sh	Correctif dev pour que les webhooks serveur-à-serveur atteignent la boutique (voir plus bas).

Le service demo-shop-prestashop, la base MariaDB et le montage du plugin sont déclarés dans le compose racine app/docker-compose.dev.yml, aux côtés des autres briques. Le docker-compose.dev.yml cité dans le README de la brique renvoie en pratique à ce fichier racine (définition factorisée).

Lancer la boutique

La sandbox a besoin de sa base MariaDB (service à part). Depuis la racine app/ :

docker compose -f docker-compose.dev.yml up -d mariadb demo-shop-prestashop

Le service est configuré pour une installation automatique (PS_INSTALL_AUTO: 1, identifiants admin pré-remplis) ; le premier démarrage prend ~2 min le temps que PrestaShop s’initialise. Paramètres clés du conteneur :

Paramètre	Valeur
Front office	http://localhost:3600
Back office	http://localhost:3600/admin-titreo (PS_FOLDER_ADMIN: admin-titreo)
Compte admin	admin@example.com / prestashop1!
Base de données	hôte mariadb, base prestashop, user/mdp prestashop, préfixe ps_
Domaine canonique	localhost:3600 (PS_DOMAIN)

Volume persistant

Les fichiers PrestaShop vivent dans le volume prestashop-data. Pour repartir d’une boutique vierge, supprimer ce volume et mariadb-data (docker compose -f docker-compose.dev.yml down -v purge l’ensemble de la stack).

Activer et configurer le plugin

Une fois la boutique en ligne, le module est déjà présent grâce au montage en volume — il reste à l’installer depuis le back-office.

Back-office (/admin-titreo)
 └─ Modules → Module Manager
     └─ chercher "Titreo E-Pay" → Installer
         └─ engrenage (Configurer)

Configuration attendue par le plugin (cf. README de la brique) :

Champ	Valeur en sandbox	Pourquoi
API base URL	http://api:3000	Nom de service interne du backend dans le réseau Docker.
API key	tep_test_…	Clé créée côté console admin.
Webhook secret	valeur copiée depuis la console marchand	Signe/valide les webhooks entrants.
Checkout page URL	http://localhost:3100	Page de paiement vers laquelle l’acheteur est redirigé (navigateur).

Deux points de vue réseau

api:3000 est l’adresse vue par le conteneur (réseau Docker). localhost:3100 / localhost:3600 sont les adresses vues par le navigateur (ports publiés sur l’hôte). Ne pas confondre : l’URL de la checkout-page doit être joignable par le navigateur de l’acheteur, l’URL de l’API par le conteneur PrestaShop.

Points d’intégration

flowchart LR
    B["Navigateur acheteur"] -->|"front :3600"| PS["PrestaShop (demo-shop-prestashop)"]
    PS -->|"redirection paiement"| CP["checkout-page :3100"]
    PS -->|"API REST :3000 (réseau Docker)"| API["api"]
    API -->|"webhook serveur-à-serveur"| PS
    B -->|"retour confirmation"| PS

Cible du webhook

C’est le point le plus subtil de la sandbox. La console marchand (http://localhost:3500/webhooks) doit pointer vers la boutique par son nom de service interne, car c’est le conteneur api qui émet l’appel :

http://demo-shop-prestashop/index.php?fc=module&module=titreoepay&controller=webhook

Or PrestaShop redirige (301/302) toute requête dont l’en-tête Host diffère de son domaine canonique (localhost:3600), ce qui casserait la livraison du webhook (commande bloquée en « Confirmation en cours »). Le script init-scripts/10-titreo-webhook-host.sh corrige cela en dev : il écrit le hostname interne (demo-shop-prestashop) dans la colonne domain_ssl de la ligne principale de ps_shop_url. findShopByHost() matche alors la ligne principale sans rediriger pour les appels serveur-à-serveur, pendant que le navigateur continue d’utiliser localhost:3600. Le script est idempotent (rejoué à chaque démarrage).

Parcours de test complet

1. Front : http://localhost:3600 — ajouter un produit au panier, aller au checkout.
2. Étape paiement → « Payer avec Titreo E-Pay ».
3. Redirection vers la checkout-page (:3100), compléter le paiement.
4. Le webhook valide la commande côté PrestaShop (statut paiement accepté).
5. Retour sur la page de confirmation de commande.

Limites

• Sandbox de dev uniquement : SSL désactivé, secrets en clair, correctif domain_ssl non transposable en production.
• Couvre l’intégration du plugin et le contrat de webhook ; pour la logique d’orchestration côté serveur, voir le Backend.