docs(ops): add reference + env config + git workflow
This commit is contained in:
68
docs/CONFIG-ENV.md
Normal file
68
docs/CONFIG-ENV.md
Normal file
@@ -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).
|
||||
30
docs/OPS-REFERENCE.md
Normal file
30
docs/OPS-REFERENCE.md
Normal file
@@ -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/<timestamp>/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 <port>`
|
||||
|
||||
### 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:'
|
||||
71
docs/WORKFLOW-GIT.md
Normal file
71
docs/WORKFLOW-GIT.md
Normal file
@@ -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/<sujet>` : correctif
|
||||
- `feat/<sujet>` : nouvelle fonction
|
||||
- `ops/<sujet>` : 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-<YYYYmmdd-HHMMSS>` (déjà fait).
|
||||
- Snapshots prod : `prod-snapshot-<YYYYmmdd-HHMMSS>` 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/<slug>
|
||||
# edits...
|
||||
git add -A
|
||||
git commit -m "fix: <message>"
|
||||
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.
|
||||
Reference in New Issue
Block a user