Bonnes pratiques d'exploitation¶

Cette page rassemble les réflexes à adopter au quotidien pour exploiter CMonChoix sans créer de dette invisible ni prendre de risque inutile.

À quoi sert cette page ?¶

Les autres pages Operations expliquent des procédures précises. Celle-ci répond à une question plus simple : « Comment travailler proprement sur le VPS et la production ? »

Elle est particulièrement utile lorsqu'on débute sur le projet, car elle donne les habitudes à prendre avant même de connaître tous les détails techniques.

1. Comprendre avant d'agir¶

Avant toute intervention, répondre à quatre questions :

Quel est le symptôme observé ?
Quelle couche semble responsable ?
L'action envisagée lit-elle ou écrit-elle des données ?
Comment vérifier que l'intervention a réellement fonctionné ?

Si une de ces réponses manque, il vaut mieux commencer par un diagnostic en lecture seule.

2. Toujours savoir où l'on se trouve¶

Avant une commande Git, Docker, WP-CLI ou make, vérifier le répertoire courant et la branche active.

Sur le VPS, le dépôt est exploité depuis :

/mnt/data/cmonchoix-platform

Une commande exécutée dans le mauvais répertoire peut viser un autre fichier docker-compose, un autre dépôt ou simplement échouer de façon trompeuse.

Pour Git :

pwd
git status --short
git branch --show-current
git rev-parse HEAD

Ces commandes sont en lecture seule.

3. Ne pas confondre code et données¶

Le code est versionné dans Git.

Les données de production vivent principalement dans les volumes, MariaDB, uploads et autres stockages persistants.

Un rollback Git ne restaure donc pas automatiquement les données modifiées par une migration ou une écriture métier.

C'est une distinction fondamentale avant tout déploiement ou incident.

4. Privilégier les mécanismes officiels¶

Lorsqu'une procédure versionnée existe, l'utiliser au lieu d'inventer une commande manuelle équivalente.

Exemples :

make doctor

pour vérifier le runtime, ou :

CCX_BACKUP_ROOT=/chemin/absolu make backup

pour créer une sauvegarde.

Pourquoi ? Parce qu'une commande officielle encode généralement plusieurs contrôles que l'on pourrait oublier en reproduisant l'opération à la main.

5. Lecture avant écriture¶

Quand un problème apparaît, suivre ce principe :

observer → auditer → comprendre → simuler → écrire

Une requête SQL de lecture, un git diff, docker compose ps ou un audit ne doivent pas être remplacés immédiatement par une commande destructive.

Une intervention qui modifie l'état du système doit être explicitement identifiée comme telle.

6. Faire un seul changement logique à la fois¶

Si l'on modifie simultanément plusieurs choses, il devient difficile de savoir laquelle a corrigé ou aggravé le problème.

Préférer :

petit changement
    ↓
validation
    ↓
changement suivant

C'est aussi la raison pour laquelle les refactorings, migrations et activations de marchands doivent être progressifs.

7. Préparer le retour arrière avant l'intervention¶

Avant une action risquée, connaître :

le commit stable précédent ;
la sauvegarde utilisable ;
les données touchées ;
la procédure de rollback ou de reconstruction ;
le test qui confirmera le retour à la normale.

Le meilleur moment pour réfléchir au rollback est avant d'en avoir besoin.

8. Ne jamais modifier le code directement dans un conteneur¶

Les conteneurs sont des environnements d'exécution.

Le code canonique est celui du dépôt Git. Modifier un fichier directement dans un conteneur crée une différence invisible qui disparaîtra au prochain redémarrage ou déploiement.

Le flux correct est :

Git → validation → déploiement → conteneur

Pas l'inverse.

9. Garder le dépôt propre¶

Avant un déploiement ou une intervention importante :

git status --short

Une sortie vide signifie qu'aucune modification locale suivie ou non suivie n'est détectée.

Un dépôt sale ne doit pas être considéré comme un état normal de production, car il devient difficile de savoir si le code exécuté correspond réellement au commit Git annoncé.

10. Mesurer avant d'optimiser¶

Une lenteur perçue n'indique pas automatiquement où se trouve le problème.

Avant d'optimiser, mesurer :

durée totale ;
nombre d'éléments traités ;
CPU ;
mémoire ;
requêtes SQL ;
temps de réponse ;
évolution par rapport à une mesure précédente.

Une optimisation sans mesure avant/après n'est pas démontrée.

11. Ne pas déplacer une règle métier pour gagner du temps¶

Une optimisation ou un dépannage ne justifie jamais de mettre une règle métier :

dans le Frontend ;
dans le Runtime ;
dans une requête SQL isolée ;
dans un Adapter ;
dans un script d'exploitation.

La responsabilité doit rester dans la couche qui possède la vérité métier.

12. Sauvegarder avant une intervention sur des données critiques¶

Avant une migration, une réparation ou une opération SQL destructive, disposer d'une sauvegarde récente et testée.

Créer une archive ne suffit pas. Voir Sauvegarde et contrôle de restauration.

13. Conserver les preuves en cas de problème¶

Lors d'un incident, ne pas supprimer trop vite :

logs ;
identifiants de run ;
dumps ou exports de diagnostic ;
métriques ;
état Git ;
messages d'erreur exacts.

Ces éléments permettent de comprendre la cause au lieu de seulement constater le symptôme.

14. Vérifier systématiquement après une intervention¶

Une opération n'est pas terminée au moment où la commande rend la main.

Il faut vérifier le résultat attendu.

Selon le cas :

make doctor

puis contrôler les métriques, logs, runs, projections ou pages concernées.

Un exit code 0 signifie seulement que la commande pense avoir terminé correctement. Il ne prouve pas que le résultat métier attendu est correct.

15. Documenter pendant que l'information est fraîche¶

Une modification significative doit mettre à jour la documentation dans le même chantier.

Ne pas compter sur la mémoire quelques semaines plus tard.

Pour une intervention opérationnelle importante, conserver :

pourquoi elle a été faite ;
ce qui a été modifié ;
les commandes utilisées ;
comment elle a été validée ;
comment revenir en arrière.

16. Savoir quand demander une seconde vérification¶

Une seconde lecture est particulièrement utile avant :

restauration de production ;
requête SQL destructive ;
suppression de volumes ;
changement de secrets ;
migration importante ;
activation d'un nouveau marchand ;
modification d'une source de vérité métier.

Plus une action est difficile à annuler, plus le niveau de preuve attendu doit être élevé.

Anti-patterns à reconnaître¶

Un anti-pattern est une habitude qui semble pratique à court terme mais produit généralement des problèmes à long terme.

À éviter :

« Je corrige directement en base et on verra après » ;
« Je modifie le frontend pour que ça ait l'air correct » ;
« Je redémarre tout Docker sans savoir quel service pose problème » ;
« Je change trois choses puis je teste » ;
« La sauvegarde existe, donc elle doit être restaurable » ;
« La commande n'a pas affiché d'erreur, donc tout va bien » ;
« Cette procédure est dans une vieille note, donc elle est forcément encore active ».

Routine minimale avant une intervention¶

[ ] Je suis dans le bon dépôt
[ ] Je connais la branche et le commit
[ ] Le dépôt est propre
[ ] Je sais si l'action lit ou écrit
[ ] Je connais le composant responsable
[ ] J'ai une sauvegarde si des données critiques sont touchées
[ ] Je sais comment revenir en arrière
[ ] Je sais comment valider le résultat

Routine minimale après une intervention¶

[ ] La commande a terminé sans erreur
[ ] Les contrôles techniques passent
[ ] Le comportement fonctionnel attendu est vérifié
[ ] Les métriques/logs ne montrent pas de nouvelle anomalie
[ ] Le dépôt est dans l'état attendu
[ ] La documentation est à jour