222 lines
6.7 KiB
Markdown
222 lines
6.7 KiB
Markdown
# 🐳 Guide de déploiement Docker
|
|
|
|
Ce guide couvre l'installation, la configuration et l'exploitation d'ObsiGate
|
|
avec Docker / Docker Compose, y compris le reverse proxy HTTPS et les mises à jour.
|
|
|
|
> **Public :** administrateurs, ops
|
|
> **Voir aussi :** [Prise en main](./PRISE_EN_MAIN.md) ·
|
|
> [Authentification & sécurité](./AUTHENTIFICATION_SECURITE.md) ·
|
|
> [`DEVELOPMENT_AND_RELEASES.md`](../DEVELOPMENT_AND_RELEASES.md)
|
|
|
|
---
|
|
|
|
## 1. Prérequis
|
|
|
|
| Composant | Version minimale |
|
|
|---|---|
|
|
| Docker | ≥ 20.10 |
|
|
| docker-compose | ≥ 2.0 |
|
|
| Espace disque | ~200 Mo pour l'image |
|
|
|
|
Systèmes supportés : Linux (Ubuntu, Debian…), macOS (Intel & Apple Silicon),
|
|
Windows (Docker Desktop), NAS compatibles Docker (Synology, QNAP…).
|
|
|
|
---
|
|
|
|
## 2. Configuration de `docker-compose.yml`
|
|
|
|
```yaml
|
|
services:
|
|
obsigate:
|
|
build:
|
|
context: .
|
|
image: obsigate:latest
|
|
container_name: obsigate
|
|
restart: unless-stopped
|
|
ports:
|
|
- "2020:8080" # port local 2020 → conteneur 8080
|
|
volumes:
|
|
- /home/user/Documents/Obsidian-Recettes:/vaults/Recettes:ro
|
|
- /home/user/Documents/Obsidian-IT:/vaults/IT:ro
|
|
- ./data:/app/data # persistance auth/config/backups
|
|
environment:
|
|
- VAULT_1_NAME=Recettes
|
|
- VAULT_1_PATH=/vaults/Recettes
|
|
- VAULT_2_NAME=IT
|
|
- VAULT_2_PATH=/vaults/IT
|
|
- OBSIGATE_AUTH_ENABLED=true
|
|
- OBSIGATE_ADMIN_USER=admin
|
|
env_file:
|
|
- .env # secrets (mot de passe admin…)
|
|
```
|
|
|
|
> **Important :** les chemins de vaults doivent être **absolus** et montés en
|
|
> **lecture seule** (`:ro`) sauf si vous voulez autoriser l'édition depuis
|
|
> ObsiGate. Le dossier `./data` doit être **persistant**.
|
|
|
|
### Variables de vault
|
|
|
|
| Variable | Description | Exemple |
|
|
|---|---|---|
|
|
| `VAULT_N_NAME` | Nom affiché | `Recettes` |
|
|
| `VAULT_N_PATH` | Chemin dans le conteneur | `/vaults/Recettes` |
|
|
| `VAULT_N_ATTACHMENTS_PATH` | Dossier d'attachements (optionnel) | `Assets/Images` |
|
|
| `VAULT_N_SCAN_ATTACHMENTS` | Scanner les images au démarrage | `true` |
|
|
|
|
**Nommage :** lettres, chiffres et tirets uniquement ; le nom doit correspondre au
|
|
chemin interne.
|
|
|
|
---
|
|
|
|
## 3. Construire et lancer
|
|
|
|
### 3.1 Script `build.sh` (recommandé)
|
|
|
|
```bash
|
|
chmod +x build.sh # une seule fois
|
|
./build.sh
|
|
```
|
|
|
|
Le script :
|
|
|
|
1. vérifie Docker et Docker Compose (versions) ;
|
|
2. valide `docker-compose.yml` (présence + syntaxe) ;
|
|
3. contrôle chaque volume monté (avertit si la source n'existe pas) ;
|
|
4. construit l'image (multi-stage, ~180 Mo) ;
|
|
5. démarre le conteneur ;
|
|
6. affiche le statut puis les logs en temps réel.
|
|
|
|
| Option | Description |
|
|
|---|---|
|
|
| `--help`, `-h` | Aide complète |
|
|
| `--build-only` | Construire sans démarrer |
|
|
| `--no-cache` | Rebuild complet sans cache **(défaut)** |
|
|
| `--cache` | Utiliser le cache Docker (plus rapide) |
|
|
| `--progress=plain` / `--progress=tty` | Sortie verbeuse / interactive |
|
|
|
|
### 3.2 Alternative manuelle
|
|
|
|
```bash
|
|
docker compose build --no-cache
|
|
docker compose up -d
|
|
```
|
|
|
|
### 3.3 Exploitation
|
|
|
|
```bash
|
|
docker compose down # arrêter
|
|
docker compose up -d # redémarrer sans rebuild
|
|
docker compose logs -f # logs temps réel
|
|
docker compose logs --tail=100 obsigate
|
|
```
|
|
|
|
> **Compatibilité Docker :** l'image utilise une variante `uvicorn` minimale et
|
|
> `fastapi 0.110.3` pour éviter des dépendances natives optionnelles
|
|
> (`watchfiles`, `uvloop`, `httptools`, `fastapi-cli`…) qui échouent sur Alpine,
|
|
> ARM ou i386.
|
|
|
|
---
|
|
|
|
## 4. Reverse proxy & HTTPS
|
|
|
|
ObsiGate sert du HTTP en clair ; placez un reverse proxy devant pour TLS.
|
|
|
|
### 4.1 Nginx (exemple)
|
|
|
|
```nginx
|
|
server {
|
|
listen 443 ssl http2;
|
|
server_name obsigate.example.com;
|
|
|
|
ssl_certificate /etc/letsencrypt/live/obsigate.example.com/fullchain.pem;
|
|
ssl_certificate_key /etc/letsencrypt/live/obsigate.example.com/privkey.pem;
|
|
|
|
location / {
|
|
proxy_pass http://127.0.0.1:2020;
|
|
proxy_http_version 1.1;
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
proxy_set_header Upgrade $http_upgrade; # WebSocket collab
|
|
proxy_set_header Connection "upgrade";
|
|
proxy_read_timeout 3600s; # SSE / WebSocket
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4.2 Variables à activer derrière un proxy
|
|
|
|
```bash
|
|
OBSIGATE_SECURE_COOKIES=true # cookie Secure (HTTPS uniquement)
|
|
OBSIGATE_TRUST_PROXY=true # confiance à X-Forwarded-For / Host
|
|
```
|
|
|
|
> N'activez `OBSIGATE_TRUST_PROXY` **que** derrière un proxy de confiance, sinon
|
|
> l'adresse IP client peut être usurpée (rate limiting, audit).
|
|
|
|
Cloudflare Tunnel, Caddy et Traefik fonctionnent de la même façon (pensez au
|
|
support WebSocket et aux longs timeouts pour le SSE).
|
|
|
|
---
|
|
|
|
## 5. Healthcheck & supervision
|
|
|
|
L'image intègre un healthcheck sur `/api/health` (statut, version, stats). Vous
|
|
pouvez aussi l'interroger depuis l'hôte :
|
|
|
|
```bash
|
|
curl -s http://localhost:2020/api/health
|
|
curl -s http://localhost:2020/api/health/detailed # admin
|
|
```
|
|
|
|
`/api/admin/stream` fournit un flux d'administration (admin uniquement).
|
|
|
|
---
|
|
|
|
## 6. Mises à jour
|
|
|
|
```bash
|
|
git pull
|
|
./build.sh # reconstruit et redémarre
|
|
```
|
|
|
|
Vos données (`./data`) et vos vaults (volumes `:ro`) sont conservées. Pour un
|
|
rebuild propre sans cache : `./build.sh --no-cache`.
|
|
|
|
> **Version :** le fichier `VERSION` à la racine est la source unique de vérité ;
|
|
> l'image et l'UI affichent la même version. Voir
|
|
> [`DEVELOPMENT_AND_RELEASES.md`](../DEVELOPMENT_AND_RELEASES.md).
|
|
|
|
---
|
|
|
|
## 7. Sauvegardes
|
|
|
|
- **Données applicatives** : sauvegardez `./data` (utilisateurs, clés, partages,
|
|
webhooks, jetons).
|
|
- **Vos notes** : ObsiGate n'écrit dans les vaults que si elles sont montées en
|
|
écriture. Un backup automatique interne est créé dans `.obsigate-backup/` avant
|
|
chaque modification (rotation 10 Mo d'audit).
|
|
- **Backups desktop** : voir [Desktop](./DESKTOP.md).
|
|
|
|
---
|
|
|
|
## 8. Multi-plateforme
|
|
|
|
L'image est publiée pour `linux/amd64`, `linux/arm64`, `linux/arm/v7` et
|
|
`linux/386`. Sur un NAS ou un Raspberry Pi, choisissez la variante correspondante
|
|
(Buildx / `platform:` dans le compose).
|
|
|
|
---
|
|
|
|
## 9. Dépannage
|
|
|
|
| Symptôme | Piste |
|
|
|---|---|
|
|
| Port déjà utilisé | `sudo netstat -tulpn \| grep 2020` puis changer `ports: "2021:8080"` |
|
|
| Vault introuvable | Chemin absolu, permissions de lecture, redémarrer après modif |
|
|
| Build qui échoue | `docker system prune -f` puis `./build.sh --progress=plain` |
|
|
| Logs | `docker compose logs -f obsigate` |
|
|
| Widgets temps réel inopérants derrière un proxy | Autoriser les upgrades WebSocket et augmenter `proxy_read_timeout` |
|
|
| Login « insecure cookie » | Passer en HTTPS ou retirer `OBSIGATE_SECURE_COOKIES` |
|