Update README with comprehensive documentation and change default port to 2020
This commit is contained in:
parent
e76e9ea962
commit
819193a080
354
README.md
354
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.
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://www.docker.com/)
|
||||
[](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*
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user