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
|
# 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
|
- [Fonctionnalités](#-fonctionnalités)
|
||||||
- **Navigation arborescente** : parcourez vos dossiers et fichiers dans la sidebar
|
- [Prérequis](#-prérequis)
|
||||||
- **Recherche fulltext** : recherche instantanée dans le contenu et les titres
|
- [Installation rapide](#-installation-rapide)
|
||||||
- **Tag cloud** : filtrage par tags extraits des frontmatters YAML
|
- [Configuration détaillée](#-configuration-détaillée)
|
||||||
- **Wikilinks** : les `[[liens internes]]` Obsidian sont cliquables
|
- [Variables d'environnement](#-variables-denvironnement)
|
||||||
- **Syntax highlight** : coloration syntaxique des blocs de code
|
- [Ajouter une nouvelle vault](#-ajouter-une-nouvelle-vault)
|
||||||
- **Thème clair/sombre** : toggle persisté en localStorage
|
- [Build multi-platform](#-build-multi-platform)
|
||||||
- **Docker multi-platform** : linux/amd64, linux/arm64, linux/arm/v7, linux/386
|
- [Utilisation](#-utilisation)
|
||||||
- **Lecture seule** : aucune écriture sur vos vaults
|
- [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** >= 20.10
|
||||||
- **docker-compose** >= 2.0
|
- **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
|
```bash
|
||||||
# 1. Build l'image
|
git clone https://git.dracodev.net/Projets/ObsiGate.git
|
||||||
docker build -t obsigate:latest .
|
cd ObsiGate
|
||||||
|
|
||||||
# 2. Adaptez les volumes dans docker-compose.yml
|
|
||||||
|
|
||||||
# 3. Lancez
|
|
||||||
docker-compose up -d
|
|
||||||
```
|
```
|
||||||
|
|
||||||
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…) :
|
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_NAME` | Nom affiché de la vault | `IT` |
|
||||||
| `VAULT_2_PATH` | Chemin dans le conteneur | `/vaults/Obsidian_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` :
|
### Méthode 1 : Édition directe
|
||||||
```yaml
|
|
||||||
- /chemin/local/vers/vault:/vaults/MaVault:ro
|
1. **Arrêtez le conteneur** :
|
||||||
|
```bash
|
||||||
|
docker-compose down
|
||||||
```
|
```
|
||||||
|
|
||||||
2. Ajoutez les variables d'environnement :
|
2. **Ajoutez un volume** dans `docker-compose.yml` :
|
||||||
```yaml
|
```yaml
|
||||||
- VAULT_6_NAME=MaVault
|
volumes:
|
||||||
- VAULT_6_PATH=/vaults/MaVault
|
- /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
|
```bash
|
||||||
docker-compose up -d
|
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
|
```bash
|
||||||
|
# Rendre le script exécutable
|
||||||
chmod +x build.sh
|
chmod +x build.sh
|
||||||
|
|
||||||
|
# Lancer le build multi-platform
|
||||||
./build.sh
|
./build.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
Cela utilise `docker buildx` pour compiler l'image pour :
|
**Architectures supportées :**
|
||||||
- `linux/amd64` (PC, serveurs)
|
- `linux/amd64` (PC, serveurs standards)
|
||||||
- `linux/arm64` (Raspberry Pi 4, Apple Silicon)
|
- `linux/arm64` (Raspberry Pi 4, Apple Silicon, NAS modernes)
|
||||||
- `linux/arm/v7` (Raspberry Pi 3)
|
- `linux/arm/v7` (Raspberry Pi 3, anciens NAS)
|
||||||
- `linux/386` (Intel Atom i686)
|
- `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
|
- **Backend** : Python 3.11 + FastAPI + Uvicorn
|
||||||
- **Frontend** : Vanilla JS + HTML + CSS (zéro framework, zéro build)
|
- **Frontend** : Vanilla JS + HTML + CSS (zéro framework, zéro build)
|
||||||
- **Rendu Markdown** : mistune 3.x
|
- **Rendu Markdown** : mistune 3.x
|
||||||
- **Image Docker** : python:3.11-alpine (~150MB)
|
- **Image Docker** : python:3.11-alpine (~200MB)
|
||||||
- **Pas de base de données** : index en mémoire uniquement
|
- **Base de données** : Aucune (index en mémoire uniquement)
|
||||||
|
- **Architecture** : SPA + API REST
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## API
|
## 📝 Développement
|
||||||
|
|
||||||
| Endpoint | Description |
|
### Structure du projet
|
||||||
|----------|-------------|
|
```
|
||||||
| `GET /api/vaults` | Liste des vaults configurées |
|
ObsiGate/
|
||||||
| `GET /api/browse/{vault}?path=` | Navigation dans les dossiers |
|
├── backend/ # API FastAPI
|
||||||
| `GET /api/file/{vault}?path=` | Contenu rendu d'un fichier .md |
|
│ ├── main.py # Point d'entrée
|
||||||
| `GET /api/search?q=&vault=&tag=` | Recherche fulltext |
|
│ ├── indexer.py # Indexation des vaults
|
||||||
| `GET /api/tags?vault=` | Tags uniques avec compteurs |
|
│ ├── search.py # Moteur de recherche
|
||||||
| `GET /api/index/reload` | Force un re-scan des vaults |
|
│ └── 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
|
container_name: obsigate
|
||||||
restart: unless-stopped
|
restart: unless-stopped
|
||||||
ports:
|
ports:
|
||||||
- "8080:8080"
|
- "2020:8080"
|
||||||
volumes:
|
volumes:
|
||||||
- /NFS/OBSIDIAN_DOC/Obsidian-RECETTES:/vaults/Obsidian-RECETTES:ro
|
- /NFS/OBSIDIAN_DOC/Obsidian-RECETTES:/vaults/Obsidian-RECETTES:ro
|
||||||
- /NFS/OBSIDIAN_DOC/Obsidian_IT:/vaults/Obsidian_IT:ro
|
- /NFS/OBSIDIAN_DOC/Obsidian_IT:/vaults/Obsidian_IT:ro
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user