Déploiement de CMonChoix Platform¶

Cette page explique comment mettre en production une version de CMonChoix sans improviser. Elle est volontairement détaillée pour une personne qui reprend le projet et ne connaît pas encore Git, Docker ou le fonctionnement du VPS.

À quoi sert un déploiement ?¶

Un déploiement consiste à faire passer le serveur de production d'une version validée du code à une autre version validée.

Le but n'est pas simplement de « récupérer les derniers fichiers ». Un déploiement correct doit permettre de répondre à quatre questions :

quelle version exacte veut-on mettre en production ?
l'environnement est-il sain avant l'opération ?
comment vérifier que la nouvelle version fonctionne ?
comment revenir en arrière si quelque chose se passe mal ?

Cette procédure est la source de vérité pour le déploiement depuis Git.

Petit lexique¶

Commit¶

Un commit est une version précise et immuable du dépôt Git. Il est identifié par un SHA, par exemple :

e1180daa7a9718b650038ef356522a80ca3d4c58

Déployer un SHA connu permet de savoir exactement quel code tourne sur le serveur.

Branche¶

Une branche est une ligne d'évolution du dépôt. Une branche de travail sert à préparer des changements ; elle ne doit pas être déployée en production tant qu'elle n'a pas été validée et intégrée dans la branche de référence prévue par le projet.

CI¶

La CI (Continuous Integration) regroupe les contrôles automatiques exécutés par GitHub : tests, audits ou autres garde-fous. Une CI rouge signifie que le changement n'est pas considéré comme validé.

VPS¶

Le VPS est le serveur qui héberge CMonChoix.

Docker / conteneur¶

Docker exécute les différents services de CMonChoix dans des conteneurs isolés : WordPress, worker, MariaDB, documentation, etc.

Source canonique du plugin¶

La seule source versionnée du plugin industriel est :

plugins/ccx-feeds-industrial/

Docker monte cette source en lecture seule dans WordPress et dans le worker sous :

/var/www/html/wp-content/plugins/ccx-feeds-industrial/

Le chemin hôte suivant doit rester absent :

wordpress/wp-content/plugins/ccx-feeds-industrial/

Pourquoi cette règle est importante¶

Si une deuxième copie du plugin existe dans wordpress/, deux versions pourraient diverger. Une correction appliquée à l'une ne serait pas forcément appliquée à l'autre.

Il faut donc toujours modifier la source canonique dans Git, jamais une copie locale dans un conteneur.

Avant toute chose : distinguer code et données¶

Un déploiement de code et une migration de données ne sont pas la même chose.

Changer de commit peut revenir à une ancienne version du code. En revanche, si une migration a supprimé ou transformé des données, revenir au commit précédent ne restaure pas automatiquement la base.

C'est pourquoi toute opération destructive sur les données doit avoir sa propre sauvegarde et sa propre procédure de restauration.

Conditions obligatoires avant déploiement¶

Ne pas commencer tant que les conditions suivantes ne sont pas réunies :

le commit ciblé est celui qui a été validé dans le workflow prévu par le projet ;
les contrôles CI obligatoires sont verts ;
le dépôt du VPS est propre ;
le fichier .env existe et ne contient aucun placeholder CHANGE_ME ;
une sauvegarde récente et restaurable existe ;
le commit actuellement déployé est noté ;
le commit de retour arrière est noté ;
CCX_ACTIVE_FEEDS ne contient que les marchands réellement certifiés et autorisés.

Les secrets, dumps, feeds marchands, uploads et données Runtime ne doivent jamais être ajoutés à Git.

Important : la branche de production peut évoluer avec l'organisation du projet. Toujours vérifier la branche cible réellement utilisée avant d'exécuter une procédure copiée d'un ancien document.

Étape 1 — Prévol¶

Le prévol est le contrôle effectué avant de modifier quoi que ce soit.

Depuis la racine du dépôt sur le VPS :

git status --short
git rev-parse HEAD
docker compose config --quiet
make container-policy
bash scripts/runtime-readonly-guard.sh --runtime

Comment lire les résultats¶

git status --short

aucune sortie = dépôt propre ;
une ou plusieurs lignes = fichiers modifiés ou non suivis ; il faut comprendre pourquoi avant de déployer.

git rev-parse HEAD

affiche le SHA exact du code actuellement checkouté.

docker compose config --quiet

vérifie que la configuration Docker Compose est syntaxiquement valide.

make container-policy

vérifie les règles de conteneur imposées par le projet.

Résultat attendu :

COMPOSE_POLICY_STATUS=PASS

runtime-readonly-guard.sh

vérifie les garde-fous Runtime attendus.

Résultat attendu :

RUNTIME_GUARD_STATUS=PASS

Règle de sécurité¶

Une erreur bloque le déploiement. Ne pas la masquer avec :

|| true

Cette construction forcerait le terminal à continuer même après une erreur et détruirait précisément le rôle du garde-fou.

Étape 2 — Déployer le commit validé¶

Remplacer <COMMIT_VALIDE> par le SHA complet qui a réellement été validé.

La procédure canonique historique utilise la branche de production configurée par le projet :

git fetch --prune origin
git switch main
git pull --ff-only origin main
test "$(git rev-parse HEAD)" = "<COMMIT_VALIDE>"
composer install --no-dev --no-interaction --prefer-dist --classmap-authoritative
python3 -m venv .venv-docs
.venv-docs/bin/pip install --requirement requirements-docs.txt
make docs-build PYTHON=.venv-docs/bin/python
docker compose config --quiet
docker compose up -d --remove-orphans
make doctor

Ce que fait chaque commande¶

git fetch --prune origin

récupère l'état du dépôt distant et nettoie les références distantes obsolètes.

git switch main

sélectionne la branche de production prévue par cette procédure. Si l'organisation du dépôt a changé, vérifier la branche réellement autorisée avant exécution.

git pull --ff-only origin main

met à jour la branche sans créer de merge implicite sur le serveur.

test "$(git rev-parse HEAD)" = "<COMMIT_VALIDE>"

bloque la suite si le serveur n'est pas exactement sur le SHA prévu.

composer install ...

installe les dépendances PHP prévues par le projet pour la production.

python3 -m venv .venv-docs

crée l'environnement Python dédié à la documentation.

pip install --requirement requirements-docs.txt

installe les dépendances MkDocs déclarées par le projet.

make docs-build ...

reconstruit la documentation.

docker compose up -d --remove-orphans

applique la configuration des conteneurs en arrière-plan et supprime les anciens services qui ne font plus partie de la configuration.

make doctor

exécute le diagnostic global après déploiement.

Étape 3 — Vérifier après déploiement¶

Un déploiement n'est pas terminé simplement parce que Docker a redémarré.

Il est terminé seulement lorsque les contrôles confirment que la plateforme fonctionne.

make doctor vérifie notamment :

l'état des services ;
la réponse HTTP de WordPress ;
la réponse de la documentation ;
la cohérence entre le commit Git et le commit de documentation servi ;
les conteneurs WordPress et worker ;
le montage en lecture seule de la source canonique ;
le chargement WordPress et l'activation du plugin ;
la connexion à MariaDB ;
la présence des fonctions CCX attendues ;
l'absence récente de marqueur finalize_sql_error.

Ensuite, vérifier également :

les métriques ;
les journaux ;
le dernier run marchand ;
les pages ou fonctionnalités directement touchées par le changement.

Règle importante sur les marchands¶

Ne pas profiter d'un déploiement pour activer en même temps un marchand encore non validé.

Un changement à la fois rend les problèmes beaucoup plus faciles à diagnostiquer.

Si le déploiement échoue¶

Avant toute action, répondre à ces questions :

l'échec concerne-t-il Git, les dépendances, Docker, WordPress, MariaDB ou le Pipeline ?
les données ont-elles été modifiées ?
les services sont-ils encore disponibles ?
le problème est-il reproductible ?
un retour arrière du code suffit-il réellement ?

Ne pas lancer plusieurs corrections différentes en même temps.

Retour arrière du code¶

Le rollback est le retour vers une version précédente stable.

Si seules les sources ont changé et que les données restent compatibles, on peut remettre le code sur le commit stable précédemment noté.

Remplacer <COMMIT_STABLE> par le SHA complet :

git fetch --prune origin
git switch --detach "<COMMIT_STABLE>"
composer install --no-dev --no-interaction --prefer-dist --classmap-authoritative
python3 -m venv .venv-docs
.venv-docs/bin/pip install --requirement requirements-docs.txt
make docs-build PYTHON=.venv-docs/bin/python
docker compose config --quiet
docker compose up -d --remove-orphans
make doctor

Que signifie `--detach` ?¶

Git place le dépôt directement sur le commit demandé sans déplacer une branche. Cela permet de remettre temporairement en service une version précise.

Une fois l'incident résolu, revenir sur la branche de production uniquement après validation du correctif :

git switch main
git pull --ff-only origin main

Quand le rollback de code ne suffit pas¶

Si le changement a entraîné une migration destructive, un nettoyage ou une transformation irréversible de données, ne pas supposer qu'un changement de commit annule l'opération.

Dans ce cas :

qualifier l'incident ;
stopper ou figer les écritures si nécessaire ;
préserver les preuves ;
identifier la sauvegarde pertinente ;
suivre la procédure de restauration adaptée ;
vérifier la plateforme après reprise.

Voir Sauvegarde et contrôle de restauration.

Ce qu'il ne faut jamais faire¶

Ne jamais :

modifier directement le code à l'intérieur d'un conteneur ;
copier le plugin dans l'arbre wordpress/ ;
déployer un dépôt sale sans comprendre ses modifications ;
déployer une branche de travail simplement parce qu'elle « fonctionne chez moi » ;
modifier les données de production sans sauvegarde et procédure dédiée ;
masquer un garde-fou en erreur ;
activer plusieurs changements risqués dans le même déploiement ;
conclure qu'un déploiement est réussi sans contrôles post-déploiement.

Checklist simple pour une reprise du projet¶

Avant :

[ ] Je connais le SHA que je veux déployer.
[ ] Je connais le SHA de retour arrière.
[ ] Le dépôt VPS est propre.
[ ] La sauvegarde est récente et vérifiée.
[ ] Les contrôles bloquants passent.

Pendant :

[ ] Je ne modifie pas le code directement dans Docker.
[ ] Je vérifie le SHA après le pull.
[ ] Je ne mélange pas un autre changement risqué au déploiement.

Après :

[ ] make doctor passe.
[ ] Le site répond.
[ ] Les journaux ne montrent pas de nouvelle erreur critique.
[ ] Le comportement métier concerné est vérifié.
[ ] Le rollback reste possible si une régression apparaît.