archicratie-edition/docs/TROUBLESHOOTING.md

TROUBLESHOOTING — Archicratie Web / NAS / Gitea

Dernière mise à jour : 2026-02-01

Ce document liste les symptômes rencontrés et les remèdes concrets.

---

0) Réflexe unique

Toujours isoler : Local, Gitea, NAS, Navigateur.

• Si ça marche sur 127.0.0.1:8082 mais pas sur le domaine → proxy/cache.
• Si ça marche après login Gitea mais pas via “Proposer” → variables PUBLIC_GITEA_*.
• Si push refusé → branch protection (normal).

---

1) “Proposer” ouvre Gitea mais retourne 404 / non autorisé

Symptôme

Nouvel onglet :

• 404 Not Found / “n’existe pas ou pas autorisé”
• ou redirect /user/login

Cause la plus fréquente

URL pointe vers mauvais owner/repo (casse sensible) :

• archicratia/archicratie-web au lieu de Archicratia/archicratie-edition

Diagnostic

Sur NAS (ou dans le HTML généré), vérifier l’URL ouverte :

• doit contenir : /Archicratia/archicratie-edition/issues/new

Fix

Dans .env de build prod (NAS) :

• PUBLIC_GITEA_OWNER=Archicratia
• PUBLIC_GITEA_REPO=archicratie-edition Puis rebuild + restart du container + smoke.

---

2) Double onglet à la validation du flow “Proposer”

Symptôme

Deux onglets s’ouvrent au moment de valider (après choix 1 / choix 2).

Causes possibles

• handler JS déclenché deux fois (bubbling)
• présence d’un window.open + a.click() simultanément
• bouton “Proposer” est un <a target=_blank> et un autre handler ouvre aussi.

Diagnostic rapide (devtools navigateur)

Chercher window.open dans la page générée :

• la commande doit retourner 0 lignes.

Sur NAS : 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

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