ObsiGate/desktop/README.md

# 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)
   - 💡 *Premier lancement recommandé depuis un terminal* pour voir le mot de passe admin généré
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 créé automatiquement (voir [Compte administrateur](#compte-administrateur))
5. **Sélectionne le dossier parent de tes vaults** Obsidian via le sélecteur natif
6. L'indexation démarre automatiquement

### Compte administrateur

Au premier démarrage, un compte administrateur est créé automatiquement :

- **Login** : `admin` (modifiable via la variable d'environnement `OBSIGATE_ADMIN_USER`)
- **Mot de passe** : généré aléatoirement (16 caractères) et affiché **une seule fois** dans les logs

Le mot de passe apparaît dans la sortie du terminal sous cette forme :
```
============================================================
PREMIER DÉMARRAGE — Compte admin créé automatiquement
  Utilisateur : admin
  Mot de passe : XXXXXXXXXXXXXXXX
CHANGEZ CE MOT DE PASSE dès la première connexion !
============================================================
```

> ⚠️ **Note le mot de passe immédiatement** — il n'est affiché qu'une seule fois.
> Si tu rates les logs, supprime le dossier `data/` et relance l'application pour
> régénérer un nouveau compte.

**Prédéfinir le mot de passe** (recommandé) :

Avant le premier lancement, définis les variables d'environnement suivantes :

- **Windows** (PowerShell) : `$env:OBSIGATE_ADMIN_PASSWORD="MonMotDePasse"`
- **Linux** : `export OBSIGATE_ADMIN_PASSWORD="MonMotDePasse"`

Tu peux aussi définir `OBSIGATE_ADMIN_USER` pour changer le nom d'utilisateur.

### 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
{
  "vaults_path": "/home/bruno/Documents",
  "backend_port": 17890,
  "theme": "system"
}
```

---

## 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 lue
  automatiquement par `build-windows.bat` / `build-linux.sh` ; en CI, via les
  secrets Gitea `TAURI_SIGNING_PRIVATE_KEY` / `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`.
- 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
```