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 · Authentification & sécurité · 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`

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é)

chmod +x build.sh   # une seule fois
./build.sh

Le script :

vérifie Docker et Docker Compose (versions) ;
valide docker-compose.yml (présence + syntaxe) ;
contrôle chaque volume monté (avertit si la source n'existe pas) ;
construit l'image (multi-stage, ~180 Mo) ;
démarre le conteneur ;
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

docker compose build --no-cache
docker compose up -d

3.3 Exploitation

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)

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

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 :

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

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.

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.

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`

6.7 KiB Raw Blame History

🐳 Guide de déploiement Docker