diff --git a/docs/CONFIG-ENV.md b/docs/CONFIG-ENV.md new file mode 100644 index 0000000..f68018d --- /dev/null +++ b/docs/CONFIG-ENV.md @@ -0,0 +1,68 @@ +# `docs/CONFIG-ENV.md` + +```md +# CONFIG-ENV — variables, priorités, injection build + +## 0) Ce que la prod doit garantir +Le bouton “Proposer” doit ouvrir : +- `PUBLIC_GITEA_BASE` (domaine Gitea) +- `PUBLIC_GITEA_OWNER=Archicratia` +- `PUBLIC_GITEA_REPO=archicratie-edition` + +Si un seul de ces 3 paramètres est faux → on obtient : +- 404 / redirect login inattendu +- ou un repo/owner incorrect + +## 1) Variables utilisées (publique, côté build Astro) + +- `PUBLIC_GITEA_BASE` +- `PUBLIC_GITEA_OWNER` +- `PUBLIC_GITEA_REPO` + +Elles sont consommées via `import.meta.env.PUBLIC_*` dans `EditionLayout.astro`. + +## 2) Où elles vivent (en pratique) +Sur NAS, vous avez vu des divergences entre : +- `.env` +- `.env.local` +- `.env.production` + +Règle : +- **prod build docker** doit être piloté par **`.env`** (ou `.env.production` si vous standardisez ainsi), +- mais on évite que `.env.local` “corrige en douce” un `.env` faux. + +## 3) Vérification rapide (NAS) +en sh +for f in .env .env.local .env.production .env.production.local; do + [ -f "$f" ] && echo "---- $f" && grep -nE '^PUBLIC_GITEA_(BASE|OWNER|REPO)=' "$f" || true +done + +## 4) Injection Docker (ce qui doit être vrai) + +Le build passe bien les build-args : + +--build-arg PUBLIC_GITEA_BASE=... + +--build-arg PUBLIC_GITEA_OWNER=... + +--build-arg PUBLIC_GITEA_REPO=... + +et le Dockerfile expose via ENV pour Astro build. + +## 5) Contrôle “résultat dans le HTML” + +Après build, vérifier que la page contient le bon chemin /issues/new vers le bon owner/repo : + +curl -fsS http://127.0.0.1:8082/archicratie/archicrat-ia/chapitre-4/ > /tmp/page.html +grep -nE 'issues/new|archicratie-edition|Archicratia' /tmp/page.html | head -n 40 + +## 6) Secrets (à ne pas committer) + +GITEA_TOKEN : jamais dans le repo. + +Le token peut être utilisé ponctuellement pour push non-interactif, mais doit rester dans l’environnement local/CI. + +## 7) Docker BuildKit / API (si besoin) + +Si BuildKit/buildx est instable sur la machine, vous avez déjà un protocole “fonctionnel”. +Ne documenter ici que le “standard validé” (voir DEPLOY_PROD). \ No newline at end of file diff --git a/docs/OPS-REFERENCE.md b/docs/OPS-REFERENCE.md new file mode 100644 index 0000000..274d7b9 --- /dev/null +++ b/docs/OPS-REFERENCE.md @@ -0,0 +1,30 @@ +# OPS-REFERENCE — Archicratie Édition + +Document “pivot” : liens, invariants, conventions, commandes réflexes. + +## 0) Invariants (à ne pas casser) + +- **Source de vérité Git** : `origin/main` sur :contentReference[oaicite:0]{index=0}. +- **Prod** : conteneur `archicratie-web-*` (nginx) derrière reverse proxy DSM. +- **Config “Proposer”** : dépend de `PUBLIC_GITEA_BASE`, `PUBLIC_GITEA_OWNER`, `PUBLIC_GITEA_REPO` injectés au build. +- **Branches** : `main` = travail ; `master` = legacy/compat (alignée mais protégée). +- **NAS** : shell sans `git` → usage standard : `alpine/git` en conteneur. + +## 1) Repères (chemins & objets) + +### NAS (DS220+) +- Checkout/release courant : `/volume2/docker/archicratie-web/current` (symlink vers releases/*/app) +- Releases : `/volume2/docker/archicratie-web/releases//app` +- Conteneur green (exemple) : `archicratie-web-green` → `127.0.0.1:8082->80` +- Conteneur blue (exemple) : `archicratie-web-blue` → `127.0.0.1:8081->80` +- Smoke : `/volume2/docker/archicratie-web/ops/smoke.sh ` + +### Mac Studio +- Repo de travail : `site/` (ou équivalent) +- Git natif : OK (branches, PR, tags, etc.) + +## 2) Commandes réflexes (diagnostic) + +### “Quelle version sert le domaine public ?” +```sh +curl -kI https://archicratie.trans-hands.synology.me/ | egrep -i 'etag:|last-modified:|server:' diff --git a/docs/WORKFLOW-GIT.md b/docs/WORKFLOW-GIT.md new file mode 100644 index 0000000..262da03 --- /dev/null +++ b/docs/WORKFLOW-GIT.md @@ -0,0 +1,71 @@ +# WORKFLOW-GIT — branches, PR, tags (standard “main”) + +## 0) Objectif +- Tout le monde (toi compris) suit un protocole unique. +- Zéro ambigüité entre “ce qui tourne” et “ce qui est versionné”. + +## 1) Branches : politique + +### main (branche de travail) +- Branche par défaut du repo. +- Tout changement passe idéalement par PR (même si tu es seul). + +### master (legacy/compat) +- Doit rester alignée sur main (si vous gardez master). +- Protégée contre push accidentel (pas de force-push, pas de push direct). +- N’est **pas** un axe de travail. + +### branches de feature +Conventions recommandées : +- `fix/` : correctif +- `feat/` : nouvelle fonction +- `ops/` : infra, déploiement, scripts, docs ops + +## 2) PR (même si tu es seul) +- Créer une PR → vérifier CI (Actions) → merge. +- Règle : “Prevent merge if checks fail” activée (bonne pratique). +- Approvals : 0 (si tu es seul). + +## 3) Tags +- Tags d’archives : `archive-master-` (déjà fait). +- Snapshots prod : `prod-snapshot-` si besoin. + +## 4) Commandes standard (Mac) + +### Se mettre parfaitement à jour +en sh : +git checkout main +git fetch origin --prune --tags +git reset --hard origin/main +git clean -fd # optionnel : supprime untracked + +### Publier un changement +git checkout -b fix/ +# edits... +git add -A +git commit -m "fix: " +git push -u origin HEAD +# PR via UI, merge + +## 5) Remote case-sensitive (piège déjà rencontré) + +Le repo peut exister avec Owner en casse différente (ex: Archicratia vs archicratia). +Standard : remote doit être : + +https://.../Archicratia/archicratie-edition.git + +Vérifier : +git remote -v + +## 6) NAS : pas de git natif + +Sur NAS, on n’installe pas forcément git dans le shell. +Standard : utiliser alpine/git en conteneur (cf. OPS-SYNC-TRIPLE-SOURCE). + +## 7) Interdits (pour éviter l’enfer) + +Éditer des fichiers du repo via FileStation “pour aller vite” (sauf hotfix d’urgence, puis backport immédiat Git). + +Pousser sur master (sauf opération contrôlée d’alignement). + +Force-push sur main. \ No newline at end of file