393 lines
11 KiB
Markdown
393 lines
11 KiB
Markdown
# ObsiGate
|
||
|
||
**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.
|
||
|
||
[](https://opensource.org/licenses/MIT)
|
||
[](https://www.docker.com/)
|
||
[](https://www.python.org/)
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ [🔍 Recherche...] [☀/🌙 Thème] ObsiGate │
|
||
├──────────────┬──────────────────────────────────────────┤
|
||
│ SIDEBAR │ CONTENT AREA │
|
||
│ ▼ Recettes │ 📄 Titre du fichier │
|
||
│ 📁 Soupes │ Tags: #recette #rapide │
|
||
│ 📄 Pizza │ [Contenu Markdown rendu] │
|
||
│ ▼ IT │ │
|
||
│ 📁 Docker │ │
|
||
│ Tags Cloud │ │
|
||
└──────────────┴──────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 Table des matières
|
||
|
||
- [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)
|
||
|
||
---
|
||
|
||
## ✨ 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.)
|
||
|
||
---
|
||
|
||
## ⚡ Installation rapide
|
||
|
||
### 1. Cloner le dépôt
|
||
|
||
```bash
|
||
git clone https://git.dracodev.net/Projets/ObsiGate.git
|
||
cd ObsiGate
|
||
```
|
||
|
||
### 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 local de l'image + démarrage
|
||
docker-compose up -d --build
|
||
|
||
# Vérifier les logs
|
||
docker-compose logs -f obsigate
|
||
```
|
||
|
||
> **Note** : ObsiGate est construit localement depuis le `Dockerfile` du projet. Sans build local, Docker essaiera de télécharger une image distante `obsigate:latest` qui n'existe pas forcément.
|
||
|
||
### 4. Accéder à l'interface
|
||
|
||
Ouvrez votre navigateur sur : **http://localhost:2020**
|
||
|
||
---
|
||
|
||
## ⚙️ 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
|
||
services:
|
||
obsigate:
|
||
build:
|
||
context: .
|
||
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 .
|
||
|
||
# Puis démarrer le service
|
||
docker-compose up -d --build
|
||
|
||
# Ou utilisez le script de build multi-platform
|
||
chmod +x build.sh
|
||
./build.sh
|
||
```
|
||
|
||
> **Compatibilité Docker** : l'image utilise la variante minimale de `uvicorn` et une version de `fastapi` compatible (`0.110.3`) afin d'éviter certaines dépendances optionnelles natives (`watchfiles`, `uvloop`, `httptools`, `fastapi-cli`, etc.) qui peuvent échouer au build sur certaines plateformes comme Alpine, ARM ou i386.
|
||
|
||
---
|
||
|
||
## 🌍 Variables d'environnement
|
||
|
||
Les vaults sont configurées par paires de variables `VAULT_N_NAME` / `VAULT_N_PATH` (N = 1, 2, 3…) :
|
||
|
||
| Variable | Description | Exemple |
|
||
|----------|-------------|---------|
|
||
| `VAULT_1_NAME` | Nom affiché de la vault | `Recettes` |
|
||
| `VAULT_1_PATH` | Chemin dans le conteneur | `/vaults/Obsidian-RECETTES` |
|
||
| `VAULT_2_NAME` | Nom affiché de la vault | `IT` |
|
||
| `VAULT_2_PATH` | Chemin dans le conteneur | `/vaults/Obsidian_IT` |
|
||
|
||
**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
|
||
|
||
### Méthode 1 : Édition directe
|
||
|
||
1. **Arrêtez le conteneur** :
|
||
```bash
|
||
docker-compose down
|
||
```
|
||
|
||
2. **Ajoutez un volume** dans `docker-compose.yml` :
|
||
```yaml
|
||
volumes:
|
||
- /nouveau/chemin/vault:/vaults/NouvelleVault:ro
|
||
```
|
||
|
||
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 --build
|
||
```
|
||
|
||
### 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 --build
|
||
```
|
||
3. **Rechargez l'index** via l'interface ou l'API :
|
||
```bash
|
||
curl http://localhost:2020/api/index/reload
|
||
```
|
||
|
||
---
|
||
|
||
## 🔨 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
|
||
```
|
||
|
||
**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)
|
||
|
||
**Pour un build local uniquement :**
|
||
```bash
|
||
docker buildx build --platform linux/amd64 --load -t obsigate:latest .
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 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-slim
|
||
- **Base de données** : Aucune (index en mémoire uniquement)
|
||
- **Architecture** : SPA + API REST
|
||
|
||
---
|
||
|
||
## 📝 Développement
|
||
|
||
### 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
|
||
|
||
---
|
||
|
||
## 📄 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*
|