112 lines
4.3 KiB
Markdown
112 lines
4.3 KiB
Markdown
# 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>` |
|