Files
ObsiGate/desktop/README.md
T
bruno f77b0e6574
CI / lint (push) Failing after 29s
CI / test (push) Skipped
CI / build (push) Skipped
CI / e2e (push) Skipped
CI / security (push) Failing after 16s
feat: desktop — connexion compte central + environnement prod/dev (#230)
Liaison d'appareil sur og/og-dev, validation du jeton draco et ouverture de la session de l'admin local. Sélecteur prod/dev (Configuration + premier lancement), admin local par défaut admin/chab30, sans impact sur le web Docker. Inclut BUG-126 (runtime python-embed/_pth + copie de backend/frontend + signature updater opt-in) et BUG-127 (retour /liaison même hôte).
2026-11-20 07:19:08 -05:00

372 lines
12 KiB
Markdown

# ObsiGate Desktop
Application desktop native pour [ObsiGate](https://git.dracodev.net/Projets/ObsiGate) — construite avec [Tauri](https://tauri.app/) (Rust + webview système).
> 🚧 **Version 2.0.0 — les binaires sont en cours de stabilisation.** Le build depuis les sources est la méthode recommandée pour le moment.
## Table des matières
- [Installation (binaires pré-buildés)](#installation-binaires-pre-buildes)
- [Build depuis les sources](#build-depuis-les-sources)
- [Démarrage](#demarrage)
- [Configuration des vaults](#configuration-des-vaults)
- [Architecture](#architecture)
- [Fonctionnalités natives](#fonctionnalites-natives)
- [Signature de code Windows](#signature-de-code-windows)
- [Dépannage](#depannage)
---
## Installation (binaires pré-buildés)
Les releases sont publiées sur [Gitea](https://git.dracodev.net/Projets/ObsiGate/releases).
### Linux
```bash
# .deb (Debian/Ubuntu/Deepin) — installation système
sudo dpkg -i obsigate_2.0.0_amd64.deb
# Lancement : menu applications → ObsiGate, ou :
obsigate-desktop
# .AppImage (toute distribution) — portable, pas d'installation
chmod +x ObsiGate_2.0.0_amd64.AppImage
./ObsiGate_2.0.0_amd64.AppImage
```
Dépendances runtime (normalement déjà présentes) :
```bash
sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0 libayatana-appindicator3-1
```
### Windows
```cmd
:: .msi — installation standard
:: Double-cliquer sur ObsiGate_2.0.0_x64.msi
:: → Crée un raccourci bureau + entrée menu Démarrer
:: .exe NSIS — installateur interactif
:: Mêmes options, inclut le raccourci
```
> **Binaires non signés** : les releases ne sont pas signées avec un certificat
> Windows. Au premier lancement, SmartScreen affiche « Windows a protégé votre
> PC » → cliquer **Informations complémentaires → Exécuter quand même**.
> Voir [Signature de code](#signature-de-code-windows) pour les alternatives.
### macOS
> Non supporté pour le moment (priorité Linux/Windows).
---
## Build depuis les sources
### Prérequis communs
- [Rust](https://rustup.rs/) stable ≥ 1.75
- Tauri CLI : `cargo install tauri-cli`
- Python 3.11+
- Git
### Linux
```bash
# 1. Dépendances système
sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev curl
# 2. Cloner le projet
git clone https://git.dracodev.net/Projets/ObsiGate.git
cd ObsiGate/desktop
# 3. Build (tout-en-un)
chmod +x build-linux.sh
./build-linux.sh
```
Le script s'occupe de :
1. Vérifier Rust + Tauri CLI + dépendances système
2. Créer l'environnement Python (venv + requirements)
3. Copier le frontend
4. Builder Tauri en mode release
Produits :
- `target/release/bundle/deb/obsigate_2.0.0_amd64.deb`
- `target/release/bundle/appimage/ObsiGate_2.0.0_amd64.AppImage`
### Windows (via Scoop)
```powershell
# 1. Installer Scoop (si pas déjà fait)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
irm get.scoop.sh | iex
# 2. Prérequis via Scoop
scoop install rustup curl git
rustup default stable
cargo install tauri-cli
# 3. Cloner
git clone https://git.dracodev.net/Projets/ObsiGate.git
cd ObsiGate\desktop
# 4. Build
.\build-windows.bat
```
Le script télécharge automatiquement Python 3.11 embed et les dépendances backend.
Produits :
- `target\release\bundle\msi\ObsiGate_2.0.0_x64.msi`
- `target\release\bundle\nsis\ObsiGate_2.0.0_x64-setup.exe`
---
## Démarrage
### Premier lancement
1. **Lance l'application** (menu ou ligne de commande)
2. Le backend Python démarre automatiquement → health check sur `127.0.0.1:17890`
3. La fenêtre s'ouvre sur l'interface ObsiGate (écran de connexion si l'auth est activée)
4. **Connecte-toi** avec le compte admin local **ou** avec ton compte central (voir ci-dessous)
5. **Sélectionne le dossier parent de tes vaults** Obsidian via le sélecteur natif
6. L'indexation démarre automatiquement
### Compte administrateur local
Au premier démarrage, un compte administrateur local est créé automatiquement :
- **Login** : `admin` (modifiable via `OBSIGATE_ADMIN_USER`)
- **Mot de passe** : `chab30` (défaut desktop, à changer dès la première connexion)
> Ce compte est un **secours local** : le backend n'écoute que sur `127.0.0.1`.
> Il reste utilisable même sans connexion au site central. Pour choisir un autre
> mot de passe initial, définis `OBSIGATE_ADMIN_PASSWORD` avant le tout premier
> lancement (le compte n'est créé qu'une fois).
### Connexion avec un compte central (#230)
L'écran de connexion propose **« Se connecter avec mon compte central »** :
1. L'app ouvre la page d'approbation du site central choisi (`og.dracodev.net`
en production, `og-dev.dracodev.net` en développement).
2. Connecte-toi au central si nécessaire, puis **approuve** la liaison
(code affiché dans l'app).
3. Le desktop ouvre la session de l'admin local : aucun mot de passe central
n'est saisi dans la fenêtre.
Le **même environnement** pilote la barre inter-apps : une fois connecté au
central via le navigateur, les autres applications (Flowdeck, TikTak…) s'ouvrent
avec le SSO. L'environnement se choisit au premier lancement et dans
**Configuration → Vaults & dossiers (Desktop)** ; le backend redémarre après le
changement. Aucun impact sur l'application web Docker.
### Lancements suivants
- L'application mémorise le dernier dossier configuré
- Le backend démarre en ~2 secondes
- Les vaults sont ré-indexées au démarrage (incrémental si inchangé)
### Arrêt
- **Icône tray → Quitter** (recommandé) : SIGTERM → arrêt propre du backend → fermeture webview
- **Fermeture fenêtre (X)** : minimise dans le tray (backend continue de tourner)
- **Ctrl+C** dans le terminal (si lancé en dev) : arrêt immédiat
### Mode développement
```bash
cd desktop
cargo tauri dev
# → Lance le backend Python + ouvre la webview avec hot-reload
```
---
## Configuration des vaults
Au premier lancement, le sélecteur de dossier natif te demande le **dossier parent** contenant tes vaults Obsidian. Exemple :
```
/home/bruno/Documents/
├── Obsidian-Recettes/ ← vault #1
├── Obsidian-IT/ ← vault #2
└── Obsidian-Perso/ ← vault #3
```
Tous les sous-dossiers contenant un dossier `.obsidian` sont automatiquement détectés comme vaults.
### Configuration avancée
Le fichier de config desktop est stocké dans :
- **Linux** : `~/.config/obsigate-desktop/config.json`
- **Windows** : `%APPDATA%\ObsiGate\config.json`
```json
{
"vault_path": "C:\\Users\\bruno\\ObsiGate",
"vaults": [{ "name": "ObsiGate", "path": "C:\\Users\\bruno\\ObsiGate" }],
"dirs": [],
"environment": "prod",
"wizard_done": true
}
```
---
## Architecture
```
desktop/
├── Cargo.toml # Dépendances Rust (Tauri 2, plugins)
├── tauri.conf.json # Config Tauri (fenêtre, bundle, plugins)
├── build.rs # Script build Tauri
├── src/
│ └── main.rs # Point d'entrée Rust : spawn backend + webview
├── python-embed/
│ ├── venv/ # Environnement Python isolé
│ └── ... # site-packages gelés
├── build-linux.sh # Script build Linux (.deb + .AppImage)
├── build-windows.bat # Script build Windows (.msi + NSIS)
└── icons/ # Icônes desktop (.ico, .png, .icns)
```
### Cycle de vie
```
Démarrage :
1. Tauri lance python-embed/venv/bin/python → uvicorn backend.main:app
2. Health check GET /api/health (timeout 15s)
3. Webview ouvre http://127.0.0.1:17890
Arrêt (tray → Quitter ou Ctrl+C) :
1. SIGTERM envoyé au processus Python
2. Backend s'arrête proprement (10s timeout)
3. Tauri ferme la webview
4. Processus nettoyé — aucun résidu
```
---
## Fonctionnalités desktop natives
| Fonctionnalité | Web (Docker) | Desktop (Tauri) |
|---|---|---|
| Accès fichiers local | Via upload | Natif (sélecteur dossier) |
| Thème | Manuel (toggle) | Auto (suit OS dark/light) |
| Notifications | Service Worker | Natif OS |
| Associations `.md` | ❌ | ✅ « Ouvrir avec ObsiGate » |
| Tray icon | ❌ | ✅ Barre des tâches |
| Auto-update | ❌ (docker pull) | ✅ Vérifie releases Gitea |
| Mode hors-ligne | Limité | Complet (backend local) |
| RAM au repos | ~150 MB (Docker) | ~80 MB (natif) |
| Démarrage à froid | ~5s (Docker) | ~2s |
---
## Signature de code Windows
La signature de code est **optionnelle** : sans elle, l'application fonctionne,
mais SmartScreen affiche un avertissement au premier lancement. Les binaires
ObsiGate sont actuellement distribués **non signés**.
### Signer localement
Le script `scripts/sign-windows.ps1` signe le binaire et les installeurs après un
`cargo tauri build`. Il lit les identifiants depuis l'environnement (jamais
commités) et est un **no-op explicite** si aucun certificat n'est fourni :
```powershell
$env:OBSIGATE_SIGN_CERT_PFX = "C:\certs\obsigate.pfx"
$env:OBSIGATE_SIGN_CERT_PASSWORD = "..."
$env:OBSIGATE_SIGN_TIMESTAMP_URL = "http://timestamp.digicert.com"
.\scripts\sign-windows.ps1
```
### Alternatives au certificat
| Option | Coût indicatif | Effet SmartScreen |
|---|---|---|
| **Livrer non signé** (statu quo) | 0 € | Avertissement → « Exécuter quand même » |
| **SignPath.io** (projet open source) | Gratuit si éligible OSS | Réputation gérée par le service |
| **Certum Open Source Code Signing** | ~70-100 €/an | Réputation progressive |
| **Certificat OV** | ~150-400 €/an | Avertit tant que la réputation n'est pas établie |
| **Certificat EV** | ~300-700 €/an + token USB/HSM | Réputation **immédiate** |
| **Azure Trusted Signing** | ~10 $/mois | Bonne réputation, signature cloud |
| **Certificat auto-signé** | 0 € | Inutile en distribution publique |
### Signature de l'auto-update (gratuite)
Indépendante de la signature Windows, la signature des mises à jour Tauri repose
sur une paire de clés que vous générez vous-même :
```bash
cargo tauri signer generate -w obsigate-updater.key
```
- La **clé publique** est déjà renseignée dans `plugins.updater.pubkey`
(`tauri.conf.json`).
- La **clé privée** (`desktop/obsigate-updater.key`, gitignorée) est utilisée
automatiquement par `build-windows.bat` / `build-linux.sh` **à condition** que
son mot de passe soit fourni via `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` ; en CI,
via les secrets Gitea `TAURI_SIGNING_PRIVATE_KEY` / `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`.
Sans ce mot de passe, le build se poursuit **sans `.sig`** et sans aucune invite
interactive (`--ci`).
- Le CLI produit des `.sig` par artefact (`*.exe.sig`, `*.AppImage.sig`, …).
**Manifeste `latest.json`** (détection des mises à jour) :
```powershell
python scripts\updater_manifest.py --tag vX.Y.Z # ou via publish_release.py
```
`publish_release.py` le génère et l'ajoute aux assets ; il reste à **committer
`desktop/latest.json` sur `main`**. L'updater lit ce fichier versionné :
`https://git.dracodev.net/Projets/ObsiGate/raw/branch/main/desktop/latest.json`.
Détail : [DEVELOPMENT_AND_RELEASES §2bis](../docs/DEVELOPMENT_AND_RELEASES.md#2bis-signature-des-mises-à-jour-updater-tauri).
---
## Dépannage
### Le backend ne démarre pas
```bash
# Vérifier que le port 17890 est libre
ss -tlnp | grep 17890
# Lancer le backend manuellement pour voir les logs
cd ObsiGate
python -m uvicorn backend.main:app --host 127.0.0.1 --port 17890 --log-level debug
```
### La fenêtre reste blanche
- Vérifier que le backend répond : `curl http://127.0.0.1:17890/api/health`
- Si "connection refused" → le backend n'a pas démarré (voir section précédente)
- Si le healthcheck répond mais la webview est blanche → problème CSP ou webview
### Erreur libwebkit2gtk non trouvé
```bash
# Ubuntu/Debian/Deepin
sudo apt install libwebkit2gtk-4.1-0
# Si l'erreur persiste, installer la version dev
sudo apt install libwebkit2gtk-4.1-dev
```
### Build échoue sur Linux
```bash
# Nettoyer et rebuild
cargo clean
rm -rf python-embed/venv
./build-linux.sh
# Si erreur de linking, vérifier les -dev packages
sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev libssl-dev
```