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`

Vérifier la santé du code et le build :
```
cd app
npm run check
npm run build
```
Mettre à jour le numéro de version dans app/package.json (ex: 2.2.0).

Commiter et créer le tag annoté :

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"

Pousser les commits ET les tags sur Forgejo :
```
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, cette étape se fait en une seule commande :

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

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) :

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) :

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>`

4.3 KiB Raw Blame History