docs: guides d'utilisation, capture reelle et README ameliores
This commit is contained in:
@@ -0,0 +1,236 @@
|
||||
# 🚀 Guide de prise en main
|
||||
|
||||
Ce guide vous fait passer d'une installation fraîche à une utilisation courante
|
||||
d'ObsiGate : première connexion, découverte de l'interface, navigation dans vos
|
||||
vaults Obsidian et raccourcis essentiels.
|
||||
|
||||
> **Public :** tous les utilisateurs · **Durée de lecture :** ~10 min
|
||||
> **Voir aussi :** [Déploiement Docker](./DEPLOIEMENT_DOCKER.md) ·
|
||||
> [Recherche, PDF & Excalidraw](./RECHERCHE_PDF_EXCALIDRAW.md) ·
|
||||
> [API REST](./API_REST.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. Qu'est-ce qu'ObsiGate ?
|
||||
|
||||
ObsiGate est une **porte d'entrée web ultra-légère** vers vos vaults Obsidian.
|
||||
Il indexe vos notes en mémoire, les rend accessibles depuis n'importe quel
|
||||
navigateur (ordinateur, tablette, téléphone) et ajoute une couche moderne :
|
||||
recherche avancée, lecture Markdown, liens `[[wikilinks]]`, images, PDF,
|
||||
Excalidraw, Mermaid, assistant IA, collaboration temps réel.
|
||||
|
||||
Points clés :
|
||||
|
||||
- **Aucune modification de vos vaults** : les volumes sont montés en lecture seule (`:ro`) par défaut.
|
||||
- **Pas de base de données** : tout l'état tient dans des fichiers JSON sous `data/`.
|
||||
- **Temps réel** : un watcher surveille le système de fichiers et met l'index à jour à chaud.
|
||||
- **Multi-vault** : plusieurs vaults peuvent être affichés et recherchés simultanément.
|
||||
|
||||
---
|
||||
|
||||
## 2. Prérequis
|
||||
|
||||
| Composant | Version | Remarque |
|
||||
|---|---|---|
|
||||
| Docker | ≥ 20.10 | ou Node/`uv` pour un lancement manuel |
|
||||
| docker-compose | ≥ 2.0 | inclus avec Docker Desktop |
|
||||
| Navigateur | récent | Chrome, Edge, Firefox, Safari |
|
||||
|
||||
Vous aurez aussi besoin du **chemin absolu** de chaque vault Obsidian sur la
|
||||
machine qui héberge Docker.
|
||||
|
||||
---
|
||||
|
||||
## 3. Lancer ObsiGate en 3 étapes
|
||||
|
||||
> La procédure complète (reverse proxy, HTTPS, mises à jour) est détaillée dans le
|
||||
> [Guide de déploiement Docker](./DEPLOIEMENT_DOCKER.md).
|
||||
|
||||
### 3.1 Cloner le dépôt
|
||||
|
||||
```bash
|
||||
git clone https://git.dracodev.net/Projets/ObsiGate.git
|
||||
cd ObsiGate
|
||||
```
|
||||
|
||||
### 3.2 Déclarer vos vaults
|
||||
|
||||
Éditez `docker-compose.yml` pour monter vos dossiers (chemins absolus, lecture seule) :
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- /home/user/Documents/Obsidian-Recettes:/vaults/Recettes:ro
|
||||
- /home/user/Documents/Obsidian-IT:/vaults/IT:ro
|
||||
- ./data:/app/data # persistance auth/config
|
||||
environment:
|
||||
- VAULT_1_NAME=Recettes
|
||||
- VAULT_1_PATH=/vaults/Recettes
|
||||
- VAULT_2_NAME=IT
|
||||
- VAULT_2_PATH=/vaults/IT
|
||||
```
|
||||
|
||||
Créez le fichier de secrets à partir du modèle :
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Éditez .env (mot de passe admin, options d'auth…)
|
||||
```
|
||||
|
||||
### 3.3 Construire et démarrer
|
||||
|
||||
```bash
|
||||
chmod +x build.sh # une seule fois
|
||||
./build.sh
|
||||
```
|
||||
|
||||
`build.sh` vérifie Docker, valide les volumes, construit l'image et démarre le
|
||||
conteneur. Ouvrez ensuite **http://localhost:2020**.
|
||||
|
||||
> Options utiles : `./build.sh --help`, `./build.sh --cache` (rebuild rapide),
|
||||
> `./build.sh --build-only` (construire sans démarrer).
|
||||
|
||||
---
|
||||
|
||||
## 4. Premier accès
|
||||
|
||||
### 4.1 Si l'authentification est désactivée (défaut)
|
||||
|
||||
Vous arrivez directement sur l'interface. Toutes les fonctionnalités sont
|
||||
accessibles sans compte — **à réserver à un usage sur réseau de confiance**.
|
||||
|
||||
### 4.2 Si l'authentification est activée
|
||||
|
||||
L'écran de connexion s'affiche. Au **tout premier démarrage**, ObsiGate crée un
|
||||
compte admin et affiche le mot de passe **une seule fois dans les logs** :
|
||||
|
||||
```bash
|
||||
docker compose logs obsigate | grep -A4 "FIRST"
|
||||
```
|
||||
|
||||
Changez ce mot de passe dès la première connexion (menu → profil →
|
||||
*Changer le mot de passe*). La gestion complète des comptes, du MFA et des
|
||||
permissions est décrite dans le
|
||||
[Guide Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md).
|
||||
|
||||
---
|
||||
|
||||
## 5. Découvrir l'interface
|
||||
|
||||
L'interface se compose de trois zones principales.
|
||||
|
||||
### 5.1 L'en-tête (header)
|
||||
|
||||
| Élément | Rôle |
|
||||
|---|---|
|
||||
| 🔍 **Barre de recherche globale** | Recherche dans toutes les vaults autorisées |
|
||||
| Filtre | Restreint la recherche (type, tag, vault…) |
|
||||
| Sélecteur de vault | Bascule l'arborescence sur une vault ou « Toutes les vaults » |
|
||||
| Utilisateur | Nom du compte connecté (si auth activée) |
|
||||
| Version | Version courante d'ObsiGate |
|
||||
| ⚙️ **Options** | Configuration, thème, guide d'utilisation, administration |
|
||||
|
||||
### 5.2 La barre latérale (sidebar)
|
||||
|
||||
Elle regroupe les vues principales via des icônes :
|
||||
|
||||
- **Arborescence** — parcourt les dossiers et fichiers de la vault sélectionnée.
|
||||
- **Graphe** — vue force-directed des liens entre notes.
|
||||
- **Récents** — derniers fichiers ouverts.
|
||||
- **Signets** — vos fichiers et recherches enregistrés.
|
||||
- **Partagés** — liens de partage public que vous avez créés.
|
||||
|
||||
Un champ **« Filtrer fichiers… »** restreint l'arborescence en temps réel, et le
|
||||
bouton **Aa** ajuste l'affichage des libellés.
|
||||
|
||||
### 5.3 La zone de contenu
|
||||
|
||||
Elle affiche l'onglet actif : tableau de bord **Statistiques**, **Bookmarks**,
|
||||
**Récents**, **Partagés**, ou le document ouvert. Les documents s'ouvrent dans
|
||||
des **onglets** (avec possibilité de vue multi-panneaux / split view).
|
||||
|
||||
---
|
||||
|
||||
## 6. Navigation et lecture
|
||||
|
||||
1. **Déployez une vault** dans la sidebar (clic sur son nom).
|
||||
2. **Cliquez sur un dossier** pour l'ouvrir, sur un **fichier** pour l'afficher.
|
||||
3. Le **breadcrumb** en haut du document permet de remonter rapidement.
|
||||
4. Les **wikilinks** `[[note]]` sont cliquables ; les images et diagrammes
|
||||
s'affichent automatiquement.
|
||||
5. Utilisez **Ctrl + clic** sur un lien pour l'ouvrir en aperçu rapide selon le
|
||||
contexte, ou ouvrir le graphe centré sur un nœud.
|
||||
|
||||
### Créer et modifier
|
||||
|
||||
- **Bouton « Editer »** : ouvre le document dans l'éditeur Markdown (CodeMirror).
|
||||
- **Bouton « Forge »** (éditeur avancé) : ouvre la version enrichie avec
|
||||
assistant IA intégré. Voir [Assistant IA & Forge](./ASSISTANT_IA_FORGE.md).
|
||||
- **Nouveau fichier / dossier** : depuis les actions de la sidebar ou la palette
|
||||
de commandes.
|
||||
- **Sauvegarde** : `Ctrl + S` (et auto-sauvegarde dans l'éditeur IA).
|
||||
|
||||
> Selon le mode, la lecture et l'édition se remplacent : `Editer` et `Forge`
|
||||
> prennent la place de la vue lecture ; revenez avec `✓` / `×` ou `Échap`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Rechercher
|
||||
|
||||
La recherche est un point fort d'ObsiGate : index inversé TF-IDF, stemming
|
||||
français, normalisation des accents, facettes et pagination. La syntaxe complète
|
||||
(`tag:`, `#`, `vault:`, `title:`, `path:`, `ext:`, phrases exactes) est décrite
|
||||
dans le [Guide Recherche, PDF & Excalidraw](./RECHERCHE_PDF_EXCALIDRAW.md).
|
||||
|
||||
Démarrage rapide :
|
||||
|
||||
- Tapez dans la barre de recherche, `Ctrl + K` pour y revenir.
|
||||
- `/` focalise la recherche hors champ de saisie.
|
||||
- `/` + `↑`/`↓` navigue dans les suggestions.
|
||||
|
||||
---
|
||||
|
||||
## 8. Apparence et confort
|
||||
|
||||
- **Thème clair/sombre** : bascule persistée en `localStorage` ; le desktop suit
|
||||
aussi le thème du système.
|
||||
- **Thèmes** : clair, sombre, contraste élevé, sépia — import/export possible.
|
||||
- **Responsive** : l'interface s'adapte au mobile (éditeur tactile, barre
|
||||
d'outils flottante).
|
||||
- **PWA** : installable comme application native, mode hors-ligne partiel.
|
||||
|
||||
Voir [PWA & mode hors-ligne](./PWA_HORS_LIGNE.md).
|
||||
|
||||
---
|
||||
|
||||
## 9. Raccourcis clavier essentiels
|
||||
|
||||
| Action | Raccourci |
|
||||
|---|---|
|
||||
| Palette de commandes | `Ctrl + Shift + Space` |
|
||||
| Palette de fichiers (navigation rapide) | `Ctrl + Alt + Space` |
|
||||
| Focus barre de recherche | `Ctrl + K` |
|
||||
| Recherche rapide (hors champ texte) | `/` |
|
||||
| Sauvegarder le fichier ouvert | `Ctrl + S` |
|
||||
| Rechercher dans le document | `Ctrl + F` |
|
||||
| Completion IA inline (éditeur) | `Ctrl + J` |
|
||||
| Insertion rapide (éditeur Forge) | `Alt + I` |
|
||||
| Fermer l'éditeur / modale | `Échap` |
|
||||
| Aide de l'éditeur Forge | `F1` |
|
||||
| Naviguer dans les suggestions | `↑` / `↓` |
|
||||
| Lancer la recherche / valider | `Entrée` |
|
||||
|
||||
> Le panneau **Raccourcis & Astuces** du tableau de bord Statistiques récapitule
|
||||
> ces raccourcis directement dans l'application.
|
||||
|
||||
---
|
||||
|
||||
## 10. Et ensuite ?
|
||||
|
||||
| Objectif | Guide |
|
||||
|---|---|
|
||||
| Mieux chercher, lire PDF et Excalidraw | [Recherche, PDF & Excalidraw](./RECHERCHE_PDF_EXCALIDRAW.md) |
|
||||
| Utiliser l'IA intégrée | [Assistant IA & Forge](./ASSISTANT_IA_FORGE.md) |
|
||||
| Éditer à plusieurs | [Édition & collaboration](./COLLABORATION.md) |
|
||||
| Sécuriser l'accès | [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md) |
|
||||
| Automatiser via API/MCP | [API REST](./API_REST.md) · [MCP](./MCP.md) |
|
||||
| Installer l'application native | [Desktop (Tauri)](./DESKTOP.md) |
|
||||
Reference in New Issue
Block a user