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