Watchflare docs
English Français
Sur cette page

Référence de configuration du Hub

Référence complète de toutes les variables d'environnement du Hub Watchflare : secrets obligatoires, base de données, ports, mode TLS, sécurité des cookies et fenêtre d'horodatage gRPC.

Le Hub se configure entièrement par variables d’environnement. Lors d’un déploiement avec Docker Compose, elles sont lues depuis le fichier .env dans le même répertoire que docker-compose.yml. Lorsque vous exécutez le binaire directement, placez un fichier .env à côté du binaire ou exportez les variables dans le shell.

Secrets obligatoires

VariableLongueur min.ObligatoireDescription
POSTGRES_PASSWORDAucuneOuiMot de passe de l’instance TimescaleDB. Aucune longueur minimale n’est imposée, mais utilisez une valeur aléatoire solide.
JWT_SECRET32 caractèresOuiSigne les cookies de session utilisateur et chiffre les secrets TOTP pour le 2FA. Le Hub s’arrête au démarrage s’il manque ou s’il est trop court.
NOTIFICATION_ENCRYPTION_KEY32 caractèresPour les notificationsChiffre les identifiants SMTP et les URL des canaux de notification (Discord, Slack, etc.) stockés en base. Le Hub démarre sans, mais le stockage des notifications sera indisponible. Le Hub s’arrête si elle est définie mais trop courte.

Générez les trois avec :

bash 
POSTGRES_PASSWORD=$(openssl rand -base64 32)
JWT_SECRET=$(openssl rand -base64 32)
NOTIFICATION_ENCRYPTION_KEY=$(openssl rand -base64 32)

Danger

Gardez ces valeurs secrètes. Sauvegardez-les hors des volumes Docker. Changer JWT_SECRET invalide toutes les sessions utilisateur actives et désactive le 2FA pour les utilisateurs qui l’avaient activé (leurs secrets TOTP ne peuvent plus être déchiffrés, ils doivent donc s’enrôler à nouveau). Changer NOTIFICATION_ENCRYPTION_KEY rend illisibles les identifiants e-mail enregistrés, et vous devrez les resaisir.

Base de données

VariableDéfautDescription
POSTGRES_HOSTlocalhostNom d’hôte de l’instance PostgreSQL. Docker Compose le remplace par postgres (le nom du service).
POSTGRES_PORT5432Port PostgreSQL
POSTGRES_USERwatchflareUtilisateur de la base
POSTGRES_PASSWORDwatchflare_devMot de passe de la base. Le binaire retombe sur watchflare_dev si la variable n’est pas définie : surchargez-la toujours en production. Docker Compose l’impose comme obligatoire via :?.
POSTGRES_DBwatchflareNom de la base
POSTGRES_SSLMODEdisableMode SSL PostgreSQL. disable est sûr lorsque les deux conteneurs partagent un réseau Docker.

Remarque

Lorsque vous utilisez le fichier Docker Compose de Déployer avec Docker, POSTGRES_HOST est déjà défini à postgres dans le fichier Compose et n’a pas besoin de figurer dans votre .env.

Ports

VariableDéfautDescription
HUB_PORT8080Docker uniquement. Port externe exposé sur l’hôte pour le serveur HTTP et le tableau de bord. Le port interne du conteneur est toujours 8080.
GRPC_PORT50051Port des connexions gRPC des agents. Doit être joignable depuis tous les hôtes surveillés.

Le port HTTP est fixé à 8080 à l’intérieur du conteneur. HUB_PORT ne fait que mapper le port externe. Par exemple, définissez HUB_PORT=80 pour servir le tableau de bord sur le port 80.

TLS

Le Hub utilise TLS pour toutes les communications gRPC avec les agents. Deux modes sont disponibles.

VariableDéfautDescription
TLS_MODEautoauto : le Hub génère sa propre CA et son certificat serveur au premier démarrage. custom : fournissez vos propres fichiers de certificats (voir ci-dessous).
TLS_PKI_DIR/var/lib/watchflare/pkiRépertoire où sont stockés les certificats générés automatiquement. Persisté via le volume Docker pki_data.

Certificats personnalisés (TLS_MODE=custom)

VariableDéfautDescription
TLS_CERT_FILEAucunChemin du certificat serveur (PEM)
TLS_KEY_FILEAucunChemin de la clé privée serveur (PEM)
TLS_CA_FILEAucunChemin du certificat CA (PEM) distribué aux agents à l’enrôlement

Attention

Lorsque vous utilisez TLS_MODE=custom, le certificat CA de TLS_CA_FILE est envoyé aux agents à l’enrôlement et épinglé sur chaque agent. Si vous effectuez une rotation de la CA, tous les agents enrôlés doivent être réenrôlés.

Voir certificats TLS pour un guide complet du mode custom.

Sécurité des cookies

Le Hub pose automatiquement le flag Secure sur le cookie de session JWT, d’après le contexte de la requête. Vous n’avez besoin de ces variables que si la détection automatique ne fonctionne pas pour votre configuration.

VariableDéfautDescription
COOKIE_SECURE(auto)Force le flag Secure à on ou off. Accepte true ou false. Omettez-la pour utiliser la détection automatique (recommandé).
COOKIE_DOMAIN(vide)Définissez-la à votre domaine lorsque vous servez le tableau de bord via un reverse proxy avec un nom d’hôte personnalisé (par ex. watchflare.example.com).
TRUSTED_PROXIES127.0.0.1,::1Liste d’adresses IP séparées par des virgules, autorisées à poser X-Forwarded-Proto. Ajoutez l’IP de votre reverse proxy s’il s’exécute sur un hôte distinct.

Règles de détection automatique (appliquées lorsque COOKIE_SECURE n’est pas défini) :

  1. Connexion HTTPS directe → Secure: true
  2. X-Forwarded-Proto: https depuis une IP de proxy de confiance → Secure: true
  3. HTTP simple, sans proxy de confiance → Secure: false

Attention

Si vous exposez le tableau de bord en HTTPS via un reverse proxy, assurez-vous que TRUSTED_PROXIES inclut l’IP du proxy. Sinon Secure vaudra false, et les navigateurs rejetteront le cookie en HTTPS.

Sécurité gRPC

VariableDéfautDescription
GRPC_TIMESTAMP_WINDOW300Décalage d’horloge acceptable en secondes pour les timestamps HMAC des agents (±fenêtre). Les requêtes hors de cette fenêtre sont rejetées. La valeur par défaut est ±5 minutes.

Augmentez cette valeur si les agents échouent fréquemment avec des avertissements de désynchronisation d’horloge et que vous ne pouvez pas synchroniser les horloges avec NTP. La baisser resserre la fenêtre d’attaque par rejeu.

Environnement

VariableDéfautDescription
ENVdevelopmentDéfinissez-la à production sur les instances déployées. Passe Gin en mode release (supprime la sortie de débogage). Le fichier Docker Compose la définit automatiquement.
CORS_ORIGINShttp://localhost:5173Origines CORS autorisées, séparées par des virgules. Nécessaire uniquement lorsque le binaire Hub s’exécute séparément du frontend pendant le développement. Non requis pour Docker ou les installations binaires où le frontend est embarqué.

Référence .env complète

.env bash 
# ── Required secrets ────────────────────────────────────────────
POSTGRES_PASSWORD=                  # required, generate with openssl rand -base64 32
JWT_SECRET=                         # required, min 32 characters
NOTIFICATION_ENCRYPTION_KEY=                # optional, min 32 characters if set

# ── Database ─────────────────────────────────────────────────────
# POSTGRES_HOST=localhost           # default: localhost (Compose sets it to 'postgres')
# POSTGRES_PORT=5432                # default: 5432
# POSTGRES_USER=watchflare          # default: watchflare
# POSTGRES_DB=watchflare            # default: watchflare
# POSTGRES_SSLMODE=disable          # default: disable

# ── Ports ────────────────────────────────────────────────────────
# HUB_PORT=8080                     # default: 8080 (Docker only)
# GRPC_PORT=50051                   # default: 50051

# ── TLS ──────────────────────────────────────────────────────────
# TLS_MODE=auto                     # default: auto
# TLS_PKI_DIR=/var/lib/watchflare/pki

# Custom certs (TLS_MODE=custom only):
# TLS_CERT_FILE=/etc/watchflare/tls/cert.pem
# TLS_KEY_FILE=/etc/watchflare/tls/key.pem
# TLS_CA_FILE=/etc/watchflare/tls/ca.pem

# ── Cookie security ──────────────────────────────────────────────
# COOKIE_DOMAIN=watchflare.example.com
# TRUSTED_PROXIES=127.0.0.1,::1
# COOKIE_SECURE=                    # omit for auto-detection

# ── gRPC security ────────────────────────────────────────────────
# GRPC_TIMESTAMP_WINDOW=300         # default: 300s (±5 minutes)

# ── Environment ──────────────────────────────────────────────────
# ENV=production

Étapes suivantes

Modifier cette page sur GitHub Dernière mise à jour : 27/08/2026