From 214f930e56cae1922ea5e589c042e2a737d990e2 Mon Sep 17 00:00:00 2001 From: Archicratia Date: Sun, 1 Feb 2026 14:47:22 +0100 Subject: [PATCH] docs(ops): add triple-source sync + troubleshooting + proposer spec --- docs/FEATURE-PROPOSER.md | 2 +- docs/OPS-SYNC-TRIPLE-SOURCE.md | 33 ++++++- docs/TROUBLESHOOTING.md | 159 ++++++++++++++++++++++++++++++++- 3 files changed, 190 insertions(+), 4 deletions(-) diff --git a/docs/FEATURE-PROPOSER.md b/docs/FEATURE-PROPOSER.md index 8f99d45..a95721c 100644 --- a/docs/FEATURE-PROPOSER.md +++ b/docs/FEATURE-PROPOSER.md @@ -100,4 +100,4 @@ Créer l’issue → vérifier le traitement CI/runner 2 onglets : double handler (bubbling + ouverture multiple) -pas de favicon : cache ou absence dans public/ → rebuild \ No newline at end of file +pas de favicon : cache ou absence dans public/ → rebuild diff --git a/docs/OPS-SYNC-TRIPLE-SOURCE.md b/docs/OPS-SYNC-TRIPLE-SOURCE.md index a42c6f8..1185493 100644 --- a/docs/OPS-SYNC-TRIPLE-SOURCE.md +++ b/docs/OPS-SYNC-TRIPLE-SOURCE.md @@ -71,8 +71,8 @@ Ce document décrit la synchronisation **sans ambiguïté** entre : ### Étape B — NAS : aligner `current` sur `origin/main` Sur NAS, git n’est pas forcément installé : on utilise un conteneur git. +en sh : -```sh APP="/volume2/docker/archicratie-web/current" U_ID="$(id -u)"; G_ID="$(id -g)" @@ -89,3 +89,34 @@ git checkout -B main git reset --hard origin/main git status -sb ' + +### Étape C — NAS : rebuild du slot inactif + smoke + bascule + +Rebuild de l’image (slot inactif recommandé). + +docker compose up -d --force-recreate --no-build web_green (ou blue) + +smoke test via script ou curl + +bascule DSM vers le port du slot actif + +## 4) Checkpoints rapides (sanity) +### 4.1 Vérifier que NAS = origin/main + +git rev-parse --short HEAD sur NAS (via alpine/git) + +doit égaler origin/main. + +### 4.2 Vérifier “Proposer” (points minimum) + +PUBLIC_GITEA_OWNER=Archicratia (casse sensible) + +PUBLIC_GITEA_REPO=archicratie-edition + +Flow : Proposer → choix 1 → choix 2 → onglet Gitea /issues/new?... OK + +## 5) Rollback + +DSM reverse proxy : repasser sur l’autre port (8081/8082). + +En cas de code cassé : réaligner NAS sur origin/main précédent (tag/release) ou repointer /current vers une release précédente. \ No newline at end of file diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 082e4d5..e29c713 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -53,6 +53,161 @@ Chercher `window.open` dans la page générée : - la commande doit retourner 0 lignes. Sur NAS : -```sh +en sh : + curl -fsS http://127.0.0.1:8082/archicratie/archicrat-ia/chapitre-4/ > /tmp/page.html -grep -n "window.open" /tmp/page.html | head \ No newline at end of file +grep -n "window.open" /tmp/page.html | head + +Fix + +garder un seul mécanisme d’ouverture + +sur click : preventDefault() + stopImmediatePropagation() + +## 3) Favicon 504 / erreurs console sur favicon +# Symptôme + +Console navigateur : GET /favicon.ico 504 + +# Cause fréquente + +Cache du navigateur (ancienne erreur conservée). + +# Diagnostic + +Comparer : + +curl -I http://127.0.0.1:8082/favicon.ico + +curl -kI https:///favicon.ico + +Si curl = 200 et navigateur = 504 → cache. + +# Fix + +Désactiver cache dans l’onglet Réseau (devtools) + +hard refresh + +vérifier droits fichiers dans dist/ + +## 4) Sur NAS : git: command not found +# Symptôme + +git fetch impossible sur le NAS. + +# Cause + +Git non installé sur DSM shell. + +# Fix standard (recommandé) + +Utiliser un conteneur git : + +APP="/volume2/docker/archicratie-web/current" +U_ID="$(id -u)"; G_ID="$(id -g)" + +sudo docker run --rm --network host \ + -u "$U_ID:$G_ID" -e HOME=/tmp \ + -v "$APP":/repo -w /repo \ + --entrypoint sh alpine/git -lc ' +set -eu +git config --global --add safe.directory /repo +git config http.sslVerify false +git fetch origin --prune +git status -sb +' + +## 5) Git : “dubious ownership in repository” +# Symptôme + +fatal: detected dubious ownership + +# Fix + +Dans le conteneur git (ou machine locale) : +git config --global --add safe.directory /repo + +## 6) Git : non-fast-forward au push +# Symptôme + +rejected (non-fast-forward) + +# Cause + +Ta branche locale est en retard vs remote. + +# Fix + +En général : + +on fait une PR depuis une branche + +ou on rebase/merge origin/main avant push + +Sur une branche de travail : +git fetch origin +git rebase origin/main +# ou +git merge origin/main + +## 7) Gitea : “Not allowed to push to protected branch main” +# Symptôme + +pre-receive hook declined + +# Cause + +Protection de branche (normal/attendu). + +# Fix + +Push sur une branche + +Ouvrir PR + +Merger via UI Gitea + +## 8) Docker build : BuildKit / buildx / API version +# Symptômes typiques + +the --network option requires BuildKit + +BuildKit is enabled but the buildx component is missing + +client version ... too new. Maximum supported API version ... + +# Fix “robuste” (principe) + +installer buildx si nécessaire + +si DSM/docker API ancienne : définir DOCKER_API_VERSION= (selon ton environnement) + +garder le build en --network host si nécessaire + +## 9) Container Manager / Docker : “database is locked” (logging driver db) +# Symptôme + +failed to initialize logging driver : database is locked + +# Cause + +Le driver de logs Docker est db (Synology) et sa DB est verrouillée. + +# Fix rapide + +Redémarrer “Container Manager” depuis le centre de paquets DSM. + +Vérifier que le conteneur redémarre ensuite. + +## 10) Checklist “tout marche” + +curl -I http://127.0.0.1:8082/ => 200 + +curl -kI https:/// => 200 + +PUBLIC_GITEA_* corrects + +“Proposer” : 1 onglet, pas de 404, issue pré-remplie + +CI passe sur PR merge \ No newline at end of file -- 2.49.1