From 819193a080a05662919c16a40a61774ae6740112 Mon Sep 17 00:00:00 2001 From: Bruno Charest Date: Sat, 21 Mar 2026 10:01:00 -0400 Subject: [PATCH] Update README with comprehensive documentation and change default port to 2020 --- README.md | 354 ++++++++++++++++++++++++++++++++++++++------- docker-compose.yml | 2 +- 2 files changed, 304 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index 386bf0a..3f2b598 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ # ObsiGate -**Visionneur multi-vault Obsidian ultra-léger** — naviguez, recherchez et lisez vos notes Obsidian depuis n'importe quel appareil via une interface web moderne. +**Porte d'entrée web ultra-léger pour vos vaults Obsidian** — Accédez, naviguez et recherchez dans toutes vos notes Obsidian depuis n'importe quel appareil via une interface web moderne et responsive. + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/) +[![Python](https://img.shields.io/badge/Python-3.11+-green.svg)](https://www.python.org/) ``` ┌─────────────────────────────────────────────────────────┐ @@ -18,44 +22,138 @@ --- -## Fonctionnalités +## 📋 Table des matières -- **Multi-vault** : visualisez plusieurs vaults Obsidian simultanément -- **Navigation arborescente** : parcourez vos dossiers et fichiers dans la sidebar -- **Recherche fulltext** : recherche instantanée dans le contenu et les titres -- **Tag cloud** : filtrage par tags extraits des frontmatters YAML -- **Wikilinks** : les `[[liens internes]]` Obsidian sont cliquables -- **Syntax highlight** : coloration syntaxique des blocs de code -- **Thème clair/sombre** : toggle persisté en localStorage -- **Docker multi-platform** : linux/amd64, linux/arm64, linux/arm/v7, linux/386 -- **Lecture seule** : aucune écriture sur vos vaults +- [Fonctionnalités](#-fonctionnalités) +- [Prérequis](#-prérequis) +- [Installation rapide](#-installation-rapide) +- [Configuration détaillée](#-configuration-détaillée) +- [Variables d'environnement](#-variables-denvironnement) +- [Ajouter une nouvelle vault](#-ajouter-une-nouvelle-vault) +- [Build multi-platform](#-build-multi-platform) +- [Utilisation](#-utilisation) +- [API](#-api) +- [Dépannage](#-dépannage) +- [Stack technique](#-stack-technique) --- -## Prérequis +## ✨ Fonctionnalités +- **🗂️ Multi-vault** : Visualisez plusieurs vaults Obsidian simultanément +- **🌳 Navigation arborescente** : Parcourez vos dossiers et fichiers dans la sidebar +- **🔍 Recherche fulltext** : Recherche instantanée dans le contenu et les titres +- **🏷️ Tag cloud** : Filtrage par tags extraits des frontmatters YAML +- **🔗 Wikilinks** : Les `[[liens internes]]` Obsidian sont cliquables +- **🎨 Syntax highlight** : Coloration syntaxique des blocs de code +- **🌓 Thème clair/sombre** : Toggle persisté en localStorage +- **🐳 Docker multi-platform** : linux/amd64, linux/arm64, linux/arm/v7, linux/386 +- **🔒 Lecture seule** : Aucune écriture sur vos vaults (sécurité maximale) + +--- + +## 🚀 Prérequis + +### Système requis - **Docker** >= 20.10 - **docker-compose** >= 2.0 +- **Espace disque** : ~200MB pour l'image Docker + +### Systèmes supportés +- Linux (Ubuntu, Debian, CentOS, etc.) +- macOS (Intel et Apple Silicon) +- Windows (avec Docker Desktop) +- NAS compatibles Docker (Synology, QNAP, etc.) --- -## Déploiement rapide +## ⚡ Installation rapide + +### 1. Cloner le dépôt ```bash -# 1. Build l'image -docker build -t obsigate:latest . - -# 2. Adaptez les volumes dans docker-compose.yml - -# 3. Lancez -docker-compose up -d +git clone https://git.dracodev.net/Projets/ObsiGate.git +cd ObsiGate ``` -L'interface est accessible sur **http://localhost:8080** +### 2. Configurer vos vaults + +Éditez le fichier `docker-compose.yml` pour ajouter vos vaults Obsidian : + +```yaml +volumes: + - /chemin/absolu/vers/votre/vault:/vaults/NomDeVotreVault:ro +``` + +> **Important** : Le chemin doit être absolu et le volume en lecture seule (`:ro`) + +### 3. Lancer l'application + +```bash +# Build et démarrage +docker-compose up -d + +# Vérifier les logs +docker-compose logs -f obsigate +``` + +### 4. Accéder à l'interface + +Ouvrez votre navigateur sur : **http://localhost:2020** --- -## Variables d'environnement +## ⚙️ Configuration détaillée + +### Étape 1 : Préparation des vaults + +1. **Localisez vos vaults Obsidian** sur votre système +2. **Notez les chemins absolus** vers chaque dossier `.obsidian` +3. **Vérifiez les permissions** : Docker doit pouvoir lire ces dossiers + +### Étape 2 : Configuration docker-compose.yml + +Voici un exemple complet : + +```yaml +version: "3.9" + +services: + obsigate: + image: obsigate:latest + container_name: obsigate + restart: unless-stopped + ports: + - "2020:8080" # Port local 2020 → Port conteneur 8080 + volumes: + # Exemples de vaults (adaptez à vos chemins) + - /home/user/Documents/Obsidian-Recettes:/vaults/Recettes:ro + - /home/user/Documents/Obsidian-IT:/vaults/IT:ro + - /home/user/Documents/Obsidian-Perso:/vaults/Perso:ro + environment: + # Configuration des vaults + - VAULT_1_NAME=Recettes + - VAULT_1_PATH=/vaults/Recettes + - VAULT_2_NAME=IT + - VAULT_2_PATH=/vaults/IT + - VAULT_3_NAME=Perso + - VAULT_3_PATH=/vaults/Perso +``` + +### Étape 3 : Construction de l'image + +```bash +# Build l'image Docker +docker build -t obsigate:latest . + +# Ou utilisez le script de build multi-platform +chmod +x build.sh +./build.sh +``` + +--- + +## 🌍 Variables d'environnement Les vaults sont configurées par paires de variables `VAULT_N_NAME` / `VAULT_N_PATH` (N = 1, 2, 3…) : @@ -66,68 +164,222 @@ Les vaults sont configurées par paires de variables `VAULT_N_NAME` / `VAULT_N_P | `VAULT_2_NAME` | Nom affiché de la vault | `IT` | | `VAULT_2_PATH` | Chemin dans le conteneur | `/vaults/Obsidian_IT` | -Ajoutez autant de paires `VAULT_N_*` que nécessaire. +**Règles de nommage :** +- Utilisez uniquement des lettres, chiffres et tirets +- Pas d'espaces ou caractères spéciaux +- Le nom doit correspondre au chemin dans le conteneur --- -## Ajouter une nouvelle vault +## ➕ Ajouter une nouvelle vault -1. Ajoutez un volume dans `docker-compose.yml` : - ```yaml - - /chemin/local/vers/vault:/vaults/MaVault:ro +### Méthode 1 : Édition directe + +1. **Arrêtez le conteneur** : + ```bash + docker-compose down ``` -2. Ajoutez les variables d'environnement : +2. **Ajoutez un volume** dans `docker-compose.yml` : ```yaml - - VAULT_6_NAME=MaVault - - VAULT_6_PATH=/vaults/MaVault + volumes: + - /nouveau/chemin/vault:/vaults/NouvelleVault:ro ``` -3. Redémarrez : +3. **Ajoutez les variables d'environnement** : + ```yaml + environment: + - VAULT_4_NAME=NouvelleVault + - VAULT_4_PATH=/vaults/NouvelleVault + ``` + +4. **Redémarrez** : ```bash docker-compose up -d ``` +### Méthode 2 : Hot-reload (recommandé) + +1. **Ajoutez le volume et les variables** comme ci-dessus +2. **Appliquez les changements** : + ```bash + docker-compose up -d + ``` +3. **Rechargez l'index** via l'interface ou l'API : + ```bash + curl http://localhost:2020/api/index/reload + ``` + --- -## Build multi-platform +## 🔨 Build multi-platform + +Pour les architectures multiples (Raspberry Pi, NAS, etc.) : ```bash +# Rendre le script exécutable chmod +x build.sh + +# Lancer le build multi-platform ./build.sh ``` -Cela utilise `docker buildx` pour compiler l'image pour : -- `linux/amd64` (PC, serveurs) -- `linux/arm64` (Raspberry Pi 4, Apple Silicon) -- `linux/arm/v7` (Raspberry Pi 3) -- `linux/386` (Intel Atom i686) +**Architectures supportées :** +- `linux/amd64` (PC, serveurs standards) +- `linux/arm64` (Raspberry Pi 4, Apple Silicon, NAS modernes) +- `linux/arm/v7` (Raspberry Pi 3, anciens NAS) +- `linux/386` (Systèmes 32-bit legacy) -> **Note** : `--load` ne fonctionne qu'en single-platform. Pour du multi-platform, utilisez `--push` vers un registry. +**Pour un build local uniquement :** +```bash +docker buildx build --platform linux/amd64 --load -t obsigate:latest . +``` --- -## Stack technique +## 📖 Utilisation + +### Interface web + +1. **Navigation** : Cliquez sur les vaults dans la sidebar pour les développer +2. **Recherche** : Utilisez la barre de recherche pour chercher dans toutes les vaults +3. **Tags** : Cliquez sur les tags pour filtrer les contenus +4. **Wikilinks** : Les liens `[[page]]` sont cliquables et navigables +5. **Thème** : Basculez entre thème clair/sombre avec l'icône 🌙/☀️ + +### Raccourcis clavier + +| Action | Raccourci | +|--------|-----------| +| Recherche | `Ctrl + K` ou `/` | +| Toggle thème | `Ctrl + T` | +| Focus recherche | `Esc` | + +--- + +## 🔌 API + +ObsiGate expose une API REST complète : + +| Endpoint | Description | Méthode | +|----------|-------------|---------| +| `/api/vaults` | Liste des vaults configurées | GET | +| `/api/browse/{vault}?path=` | Navigation dans les dossiers | GET | +| `/api/file/{vault}?path=` | Contenu rendu d'un fichier .md | GET | +| `/api/search?q=&vault=&tag=` | Recherche fulltext | GET | +| `/api/tags?vault=` | Tags uniques avec compteurs | GET | +| `/api/index/reload` | Force un re-scan des vaults | GET | + +**Exemple d'utilisation :** +```bash +# Lister les vaults +curl http://localhost:2020/api/vaults + +# Rechercher +curl "http://localhost:2020/api/search?q=recette&vault=all" + +# Obtenir un fichier +curl "http://localhost:2020/api/file/Recettes?path=pizza.md" +``` + +--- + +## 🔧 Dépannage + +### Problèmes courants + +**Port déjà utilisé :** +```bash +# Vérifier qui utilise le port +sudo netstat -tulpn | grep 2020 +# Changer le port dans docker-compose.yml +ports: + - "2021:8080" +``` + +**Vault non trouvée :** +- Vérifiez que les chemins sont absolus +- Assurez-vous que les permissions permettent la lecture +- Redémarrez le conteneur après modification + +**Build échoue :** +```bash +# Nettoyer et rebuild +docker system prune -f +docker-compose down +docker build --no-cache -t obsigate:latest . +docker-compose up -d +``` + +**Logs pour debugging :** +```bash +# Logs en temps réel +docker-compose logs -f obsigate + +# Logs détaillés +docker-compose logs --tail=100 obsigate +``` + +### Performance + +- **Indexation** : Première utilisation peut prendre quelques secondes +- **Mémoire** : ~50-100MB par 1000 fichiers (index en mémoire) +- **CPU** : Minimal, sauf lors des recherches fulltext + +--- + +## 🏗️ Stack technique - **Backend** : Python 3.11 + FastAPI + Uvicorn - **Frontend** : Vanilla JS + HTML + CSS (zéro framework, zéro build) - **Rendu Markdown** : mistune 3.x -- **Image Docker** : python:3.11-alpine (~150MB) -- **Pas de base de données** : index en mémoire uniquement +- **Image Docker** : python:3.11-alpine (~200MB) +- **Base de données** : Aucune (index en mémoire uniquement) +- **Architecture** : SPA + API REST --- -## API +## 📝 Développement -| Endpoint | Description | -|----------|-------------| -| `GET /api/vaults` | Liste des vaults configurées | -| `GET /api/browse/{vault}?path=` | Navigation dans les dossiers | -| `GET /api/file/{vault}?path=` | Contenu rendu d'un fichier .md | -| `GET /api/search?q=&vault=&tag=` | Recherche fulltext | -| `GET /api/tags?vault=` | Tags uniques avec compteurs | -| `GET /api/index/reload` | Force un re-scan des vaults | +### Structure du projet +``` +ObsiGate/ +├── backend/ # API FastAPI +│ ├── main.py # Point d'entrée +│ ├── indexer.py # Indexation des vaults +│ ├── search.py # Moteur de recherche +│ └── requirements.txt +├── frontend/ # Interface web +│ ├── index.html # Page principale +│ ├── app.js # Logique SPA +│ └── style.css # Styles +├── Dockerfile # Configuration Docker +├── docker-compose.yml # Déploiement +└── build.sh # Build multi-platform +``` + +### Contribuer + +1. Fork le projet +2. Créer une branche `feature/nouvelle-fonctionnalite` +3. Commit vos changements +4. Push vers la branche +5. Créer une Pull Request --- -*Projet : ObsiGate | Auteur : Bruno Beloeil | Licence : MIT* +## 📄 Licence + +Ce projet est sous licence **MIT** - voir le fichier [LICENSE](LICENSE) pour les détails. + +--- + +## 🤝 Support + +- **Issues** : [git.dracodev.net/Projets/ObsiGate/issues](https://git.dracodev.net/Projets/ObsiGate/issues) +- **Documentation** : [git.dracodev.net/Projets/ObsiGate/wiki](https://git.dracodev.net/Projets/ObsiGate/wiki) +- **Auteur** : Bruno Beloeil + +--- + +*Projet : ObsiGate | Version : 1.0.0 | Dernière mise à jour : 2025* diff --git a/docker-compose.yml b/docker-compose.yml index 6c1784b..2f5eea4 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -6,7 +6,7 @@ services: container_name: obsigate restart: unless-stopped ports: - - "8080:8080" + - "2020:8080" volumes: - /NFS/OBSIDIAN_DOC/Obsidian-RECETTES:/vaults/Obsidian-RECETTES:ro - /NFS/OBSIDIAN_DOC/Obsidian_IT:/vaults/Obsidian_IT:ro