docs: add comprehensive YunoHost packaging & release guide

2026-08-16 22:54:53 -04:00
parent e4d9920ac9
commit bfc52f734d
1 changed files with 111 additions and 0 deletions
@@ -0,0 +1,111 @@
+# Guide de Packaging et de Mise à Jour YunoHost (JWE)
+
+Ce document formalise la procédure standard pour maintenir, packager et mettre à jour l'application **JWE** sur **YunoHost** sans erreur de checksum ou de déploiement.
+
+---
+
+## 1. Comprendre la mécanique des Checksums Forgejo / Gitea
+
+> [!IMPORTANT]
+> **Pourquoi le checksum d'un `git archive` local ne correspond pas à Forgejo ?**
+> Forgejo/Gitea génère dynamiquement les archives `.tar.gz` des tags avec ses propres entêtes gzip (timestamps, UID/GID virtuels, flags).
+> **Règle d'or** : Le `sha256` dans `manifest.toml` doit **toujours** être calculé directement sur le fichier `.tar.gz` téléchargé depuis l'instance Forgejo **après** avoir poussé le tag Git.
+
+---
+
+## 2. Procédure Standard de Release (Étape par Étape)
+
+### Étape 1 : Valider et commiter sur le dépôt principal `JWE`
+1. Vérifier la santé du code et le build :
+   ```bash
+   cd app
+   npm run check
+   npm run build
+   ```
+2. Mettre à jour le numéro de version dans `app/package.json` (ex: `2.2.0`).
+3. Commiter et créer le tag annoté :
+   ```bash
+   git add app/package.json
+   git commit -m "chore(release): bump version to v2.2.0"
+   git tag -a v2.2.0 -m "v2.2.0: Description des nouveautés"
+   ```
+4. **Pousser les commits ET les tags sur Forgejo** :
+   ```bash
+   git push origin master --tags
+   ```
+
+---
+
+### Étape 2 : Mettre à jour le paquet YunoHost `jwe_ynh`
+
+Grâce au script d'automatisation [`jwe_ynh/scripts/update-release.sh`](file:///home/sucupira/NHEDKXONE/Activités/2_oki/3_Projets/JWE/jwe_ynh/scripts/update-release.sh), cette étape se fait en une seule commande :
+
+```bash
+cd jwe_ynh
+./scripts/update-release.sh v2.2.0
+```
+
+*Ce script effectue automatiquement :*
+- Le téléchargement de l'archive officielle depuis `https://labola.o-k-i.net/ORGANISATION-KA-INTERNATIONALE/JWE/archive/v2.2.0.tar.gz`.
+- Le calcul du `sha256` réel de l'archive Forgejo.
+- La mise à jour de `version = "2.2.0~ynh1"`, de l'URL et du `sha256` dans `manifest.toml`.
+
+---
+
+### Étape 3 : Commiter et publier le paquet YunoHost
+
+```bash
+cd jwe_ynh
+git add manifest.toml scripts/update-release.sh
+git commit -m "2.2.0~ynh1 — bump upstream v2.2.0"
+git push origin master
+```
+
+---
+
+### Étape 4 : Déployer / Mettre à jour sur le serveur YunoHost
+
+Sur le serveur de production (ou via l'interface Web d'administration YunoHost) :
+
+```bash
+sudo yunohost app upgrade jwe -u https://labola.o-k-i.net/ORGANISATION-KA-INTERNATIONALE/jwe_ynh
+```
+
+Pour forcer la mise à jour même si la version est identique (par ex. pour tester une correction de packaging) :
+```bash
+sudo yunohost app upgrade jwe -u https://labola.o-k-i.net/ORGANISATION-KA-INTERNATIONALE/jwe_ynh --force
+```
+
+---
+
+## 3. Structure du Paquet YunoHost (Format v2)
+
+```
+jwe_ynh/
+├── manifest.toml             # Métadonnées v2, dépendances, ressources et questions
+├── conf/
+│   ├── nginx.conf            # Reverse-proxy Nginx avec WebSockets et en-têtes de cache
+│   └── systemd.service       # Service systemd démarrant 'node build'
+├── scripts/
+│   ├── install               # Déploiement initial : npm ci, build, services
+│   ├── upgrade               # Mise à jour transparente sans perte de configuration
+│   ├── backup                # Sauvegarde instance
+│   ├── restore               # Restauration instance
+│   ├── remove                # Nettoyage propre
+│   ├── change_url            # Changement de domaine
+│   └── update-release.sh     # Outil de mise à jour du sha256 Forgejo
+└── doc/
+    ├── DESCRIPTION.md        # Description bilingue
+    ├── ADMIN.md              # Guide administrateur YunoHost
+    └── PACKAGING_GUIDE.md    # Guide de maintenance
+```
+
+---
+
+## 4. Dépannage et Bonnes Pratiques
+
+| Problème rencontré | Cause | Solution |
+|---|---|---|
+| `Failed to update sources : checksum mismatch` | Le SHA256 dans `manifest.toml` a été calculé en local ou le tag Git a été déplacé sur Forgejo | Relancer `./scripts/update-release.sh <tag>` puis `git push` dans `jwe_ynh` |
+| `Node build failure: memory limit` | RAM de build insuffisante pour Vite | S'assurer que `ram.build = "800M"` est bien présent dans `manifest.toml` |
+| `Mapillary images not loading` | Mode street actif sans token | Configurer `mapillary_token` via `yunohost app setting jwe mapillary_token -v <TOKEN>` |