ObsiGate/docs/DEVELOPMENT_AND_RELEASES.md

Guide de Développement, Build Local & Publication des Releases Gitea — ObsiGate

Ce guide décrit la procédure pas-à-pas pour tester, compiler localement l'application Desktop (Windows et Linux), effectuer les commits & pushs, puis publier les binaires sur la section Releases / Publications de Gitea (https://git.dracodev.net/Projets/ObsiGate/releases).

---

1. Tests et Prévisualisation Locale

A. Backend & Frontend (Tests unitaires & Linting)

# Tests backend Python (FastAPI)
.\.venv\Scripts\python.exe -m pytest tests/

# Linting backend (ruff & mypy)
.\.venv\Scripts\python.exe -m ruff check backend/
.\.venv\Scripts\python.exe -m mypy backend/ --ignore-missing-imports

# Validation & tests unitaires frontend
node tests/frontend/validate-imports.mjs
node tests/frontend/unit.test.mjs

B. Mode Développement Desktop (Tauri 2 Live Preview)

Pour développer l'application desktop avec rechargement à chaud (Hot Reload) :

cd desktop
cargo tauri dev

Le backend Python et l'interface WebView Tauri démarreront automatiquement sur http://127.0.0.1:17890.

---

2. Compilation Locale de l'Application Desktop

A. Windows (Installeur .exe NSIS et Paquet .msi)

1. Ouvrez un terminal PowerShell ou CMD sur votre machine Windows.
2. Déplacez-vous dans le dossier desktop/ et exécutez le script :

   cd desktop
   .\build-windows.bat
   

3. Binaires générés dans desktop/target/x86_64-pc-windows-msvc/release/bundle/ :
   • ObsiGate_x.y.z_x64-setup.exe (Installeur utilisateur NSIS)
   • ObsiGate_x.y.z_x64_en-US.msi (Paquet d'installation MSI)

B. Linux (Exécutable .AppImage et Paquet .deb)

1. Ouvrez un terminal Bash (Machine Linux ou WSL2 / Conteneur Docker).
2. Déplacez-vous dans le dossier desktop/ et exécutez le script :

   cd desktop
   chmod +x build-linux.sh
   ./build-linux.sh
   

3. Binaires générés dans desktop/target/x86_64-unknown-linux-gnu/release/bundle/ :
   • ObsiGate_x.y.z_amd64.AppImage (Exécutable portable Linux)
   • obsigate_x.y.z_amd64.deb (Paquet Debian/Ubuntu)

---

2bis. Signature des mises à jour (updater Tauri)

La signature de l'auto-update Tauri est indépendante de la signature de code Windows et gratuite. Elle garantit qu'une mise à jour téléchargée provient bien de vous. Elle repose sur une paire de clés minisign :

• La clé publique est embarquée dans desktop/tauri.conf.json (plugins.updater.pubkey).
• La clé privée signe les artefacts au build. Elle ne doit jamais être commitée (ignorée par .gitignore).

A. Générer la paire de clés (une seule fois)

cd desktop
cargo tauri signer generate -w obsigate-updater.key
# La clé publique s'affiche et est écrite dans obsigate-updater.key.pub

⚠️ Conservez la clé privée en lieu sûr (gestionnaire de secrets). Si vous la perdez, les mises à jour ne pourront plus être signées. Pour la protéger par mot de passe : ajoutez -p "<mot de passe>".

Copiez le contenu de obsigate-updater.key.pub dans desktop/tauri.conf.json → plugins.updater.pubkey.

B. Build local signé

# Windows PowerShell
$env:TAURI_SIGNING_PRIVATE_KEY = Get-Content -Raw .\obsigate-updater.key
# $env:TAURI_SIGNING_PRIVATE_KEY_PASSWORD = "<mot de passe>"  # si la clé en a un
cargo tauri build --bundles nsis,msi

# Linux / Bash
export TAURI_SIGNING_PRIVATE_KEY="$(cat obsigate-updater.key)"
# export TAURI_SIGNING_PRIVATE_KEY_PASSWORD="<mot de passe>"
cargo tauri build --bundles appimage,deb

Le CLI produit des fichiers .sig à côté de chaque artefact (*.exe.sig, *.msi.sig, *.AppImage.sig, *.deb.sig).

Sans clé définie, createUpdaterArtifacts est actif et le build échoue : dans le CI, l'étape désactive automatiquement les artefacts de mise à jour si le secret est absent.

C. Secrets CI (Gitea)

Dans Dépôt → Paramètres → Actions → Secrets, créez :

Secret	Valeur
TAURI_SIGNING_PRIVATE_KEY	contenu intégral du fichier .key
TAURI_SIGNING_PRIVATE_KEY_PASSWORD	mot de passe de la clé (vide si aucun)

Le workflow .gitea/workflows/desktop-build.yml les expose aux étapes de build ; les fichiers .sig sont uploadés comme artefacts.

D. Manifeste de mise à jour (latest.json)

Le CLI Tauri génère les .sig mais pas le manifeste JSON consommé par l'updater. Celui-ci est produit par scripts/updater_manifest.py :

# Windows — après build-windows.bat
.\.venv\Scripts\python.exe scripts\updater_manifest.py --tag v2.3.0

publish_release.py l'appelle automatiquement : il écrit desktop/latest.json, l'ajoute aux assets de la release, et rappelle la dernière étape manuelle.

Flux complet de release :

1. desktop\build-windows.bat (build + signature .sig) ;
2. python scripts\publish_release.py --tag vX.Y.Z (checksums + latest.json + upload) ;
3. commit de desktop/latest.json sur main puis git push.

L'endpoint de l'updater (desktop/tauri.conf.json) pointe vers ce fichier versionné :

https://git.dracodev.net/Projets/ObsiGate/raw/branch/main/desktop/latest.json

Document produit (URLs construites vers les assets de la release) :

{
  "version": "2.3.0",
  "notes": "…",
  "pub_date": "2026-09-12T00:00:00Z",
  "platforms": {
    "windows-x86_64": { "signature": "<contenu .exe.sig>", "url": "<URL du .exe>" },
    "linux-x86_64":   { "signature": "<contenu .AppImage.sig>", "url": "<URL .AppImage>" }
  }
}

Seules les plateformes dont l'artefact signé est présent sont incluses. Sans desktop/latest.json à jour sur main, l'updater ne détecte aucune mise à jour (la signature, elle, reste opérationnelle).

---

3. Commit, Push & Tagging Git

Une fois les modifications testées et validées :

1. Commit et Push du code source :

   git add .
   git commit -m "feat: préparation release v2.0.0"
   git push origin main
   

   Ceci déclenchera la vérification CI standard sur Gitea (lint, tests unitaires, build Docker).

2. Création du Tag de Version :

   git tag -a v2.0.0 -m "Release v2.0.0"
   git push origin v2.0.0
   

Bump automatisé (recommandé)

scripts/bump_version.sh calcule la prochaine version depuis les commits (Conventional Commits), synchronise la version desktop (tauri.conf.json, Cargo.toml, Cargo.lock), crée un commit de release puis le tag :

scripts/bump_version.sh --dry-run          # prévisualiser la prochaine version
scripts/bump_version.sh                    # bump + commit + tag (local)
scripts/bump_version.sh --push             # idem + push branche & tag

La version desktop doit être synchronisée avec le tag pour que l'updater Tauri détecte les mises à jour (latest.json reprend la version de tauri.conf.json). --no-files conserve l'ancien comportement (tag seul).

---

4. Publication des Binaires sur Gitea Releases

Un script automatisé (scripts/publish_release.py) se charge de téléverser vos binaires compilés localement et de générer l'empreinte cryptographique checksums.txt (SHA256).

A. Obtenir un Jeton d'Accès Gitea (Une seule fois)

1. Connectez-vous sur votre instance Gitea : https://git.dracodev.net.
2. Cliquez sur votre Profil \rightarrow Paramètres \rightarrow Applications.
3. Dans Gérer les jetons d'accès personnels, entrez le nom ObsiGate-Release et cochez le jeton avec accès en écriture sur les dépôts (repo).
4. Copiez le jeton généré.

B. Exécution de la Publication

Option 1 — Définir la variable d'environnement (Recommandé) :

• Windows PowerShell :

  $env:GITEA_TOKEN="votre_jeton_gitea_ici"
  .\.venv\Scripts\python.exe scripts/publish_release.py --tag v2.0.0
  

• Linux / Bash :

  export GITEA_TOKEN="votre_jeton_gitea_ici"
  python3 scripts/publish_release.py --tag v2.0.0
  

Option 2 — Utiliser l'option --token :

.\.venv\Scripts\python.exe scripts/publish_release.py --tag v2.0.0 --token "votre_jeton_gitea_ici"

Option 3 — Tester à blanc avec --dry-run (Sans modifier Gitea) :

.\.venv\Scripts\python.exe scripts/publish_release.py --tag v2.0.0 --dry-run

---

5. Résultat Attendu dans Gitea

Une fois le script exécuté, visitez la page ObsiGate Releases.

Vous y trouverez la section de publication officielle contenant :

• 📦 ObsiGate_2.0.0_x64-setup.exe (Installeur Windows)
• 📦 ObsiGate_2.0.0_x64_en-US.msi (Package MSI Windows)
• 📦 ObsiGate_2.0.0_amd64.AppImage (Executable autonome Linux)
• 📦 obsigate_2.0.0_amd64.deb (Paquet Debian/Ubuntu)
• 🔐 checksums.txt (Empreintes de sécurité SHA-256)
• 📄 Code source .zip / .tar.gz (générés automatiquement)