Auto-héberger Lightdash avec Docker Compose

Docker Compose est la façon la plus rapide d’exécuter Lightdash localement ou sur une petite VM. Trois services sont requis : l’application Lightdash elle-même, une base de données PostgreSQL pour le stockage des métadonnées, et un navigateur headless pour générer les images de graphiques. Faire communiquer ces trois services entre eux est tout l’art de la configuration auto-hébergée.

Lightdash est sous licence MIT, ce qui signifie que vous pouvez l’exécuter sans frais, sans limite d’utilisateurs, et sans obligation d’ouvrir vos personnalisations. La version auto-hébergée est un produit réel — des équipes l’utilisent en production pour les petits déploiements. Elle est aussi délibérément incomplète : la planification, le smart caching, les fonctionnalités IA et les exports CSV sont réservés au tier Cloud Pro. Comprendre ces limites avant de déployer évite les mauvaises surprises. La description des licences couvre la répartition des fonctionnalités en détail.

Services requis

Application Lightdash

L’application principale s’exécute sur le port 8080 par défaut (important — la documentation et certaines configurations par défaut référencent le port 3000, ce qui est incorrect ; voir la section pièges ci-dessous).

PostgreSQL

Lightdash utilise PostgreSQL pour l’état de l’application : comptes utilisateurs, définitions de dashboards, graphiques sauvegardés et configurations de livraison planifiée. Deux exigences qui surprennent :

1. La base de données doit avoir l’extension uuid-ossp installée. Les images PostgreSQL standard l’ont disponible mais elle doit être activée.
2. Ne lancez pas PostgreSQL comme conteneur en production. Pour une équipe multi-personnes, utilisez un service de base de données managé (Cloud SQL, RDS, selon votre fournisseur cloud) et configurez des sauvegardes. Une base de données conteneur qui perd son volume perd toutes les définitions de vos dashboards.

Pour une évaluation locale ou une preuve de concept, un conteneur PostgreSQL convient.

Navigateur headless (Browserless)

Lightdash utilise un navigateur Chromium headless pour rendre des graphiques à deux fins : générer des images dans les messages Slack quand un rapport planifié se déclenche, et produire des captures d’écran de graphiques pour les livraisons par email. Sans ce service, l’application fonctionne normalement mais les livraisons planifiées n’incluront pas d’instantanés visuels de graphiques.

La configuration officielle utilise browserless (une image Docker qui exécute Chromium comme service). C’est le plus gourmand en mémoire des trois services.

Une configuration Docker Compose fonctionnelle

version: '3'
services:
  lightdash:
    image: lightdash/lightdash:latest
    ports:
      - "8080:8080"
    environment:
      - PGHOST=postgres
      - PGPORT=5432
      - PGUSER=${PGUSER}
      - PGPASSWORD=${PGPASSWORD}
      - PGDATABASE=${PGDATABASE}
      - LIGHTDASH_SECRET=${LIGHTDASH_SECRET}
      - SITE_URL=${SITE_URL}
      - SCHEDULER_ENABLED=true
      - SECURE_COOKIES=true
      - TRUST_PROXY=true
      - BROWSER_ENDPOINT=http://browserless:3000
    depends_on:
      - postgres
      - browserless

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_USER=${PGUSER}
      - POSTGRES_PASSWORD=${PGPASSWORD}
      - POSTGRES_DB=${PGDATABASE}
    volumes:
      - postgres_data:/var/lib/postgresql/data

  browserless:
    image: browserless/chrome:latest
    ports:
      - "3000:3000"

volumes:
  postgres_data:

Lancez avec :

docker compose -f docker-compose.yml --env-file .env up --detach --remove-orphans

Variables d’environnement

Toutes les valeurs sensibles vont dans .env. Ne committez jamais ce fichier.

Pour l’authentification, le tier open-source supporte uniquement Google OAuth :

AUTH_GOOGLE_CLIENT_ID=your_client_id
AUTH_GOOGLE_CLIENT_SECRET=your_client_secret

Okta (OIDC) nécessite Cloud Pro. Azure AD, OneLogin, OIDC générique, SAML et SCIM 2.0 sont réservés Enterprise. Si votre organisation impose le SSO via autre chose que Google, tenez compte des coûts de tier avant de vous engager dans l’auto-hébergement.

Un template .env :

# Generate with: openssl rand -hex 32
LIGHTDASH_SECRET=your_32_character_secret_here

# Your public URL (no trailing slash)
SITE_URL=https://lightdash.yourdomain.com

# PostgreSQL
PGHOST=postgres
PGPORT=5432
PGUSER=lightdash
PGPASSWORD=your_database_password
PGDATABASE=lightdash_db

# Google OAuth
AUTH_GOOGLE_CLIENT_ID=your_google_client_id
AUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret

Pièges connus

Port 3000 vs port 8080

L’application Lightdash s’exécute sur le port 8080. Le SITE_URL par défaut dans certaines documentations et configurations d’exemple référence le port 3000. Ce décalage provoque l’échec silencieux des redirections d’authentification — les callbacks OAuth vont sur le mauvais port et les utilisateurs obtiennent des pages d’erreur plutôt qu’une connexion fonctionnelle. Vérifiez toujours que votre SITE_URL correspond au port sur lequel le conteneur écoute réellement. Le problème GitHub #10893 suit ce problème.

Extension PostgreSQL uuid-ossp

Si vous voyez des erreurs au premier démarrage concernant des fonctions UUID manquantes, l’extension n’est pas activée. La correction la plus propre est de l’ajouter dans un script init monté dans le conteneur PostgreSQL :

-- init.sql
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

postgres:
  image: postgres:15
  volumes:
    - postgres_data:/var/lib/postgresql/data
    - ./init.sql:/docker-entrypoint-initdb.d/init.sql

Migrations de base de données lors des mises à jour

Lightdash sort plusieurs releases par semaine (le rythme a atteint v0.2258.1 en décembre 2025). Chaque release peut inclure des migrations de base de données. Lors d’une mise à jour, l’application exécute les migrations automatiquement au démarrage. Pour les petits déploiements c’est acceptable, mais sur une base de données partagée avec des utilisateurs actifs, surveillez les contentions de verrou pendant la fenêtre de migration. Effectuez les mises à jour pendant les périodes de faible trafic.

Le flag --remove-orphans

Incluez toujours --remove-orphans dans votre commande compose up. Quand Lightdash met à jour sa spécification Docker Compose (ajout d’un service, suppression d’un service, renommage d’un conteneur), les conteneurs orphelins de la configuration précédente resteront actifs sans ce flag. Ils ne provoquent pas d’erreurs évidentes mais consomment des ressources et peuvent produire des comportements déroutants.

Dimensionnement pour les petites équipes

Une instance GCP e2-medium (2 vCPU, 4 Go RAM) ou équivalent gère confortablement la charge pour une petite équipe en preuve de concept et en début de production. Le navigateur headless est le service le plus gourmand en mémoire — si vous rencontrez des pressions mémoire, c’est la première chose à contraindre ou à déplacer sur un hôte séparé.

Pour tout ce qui dépasse une petite équipe — plus de 10-15 utilisateurs actifs, rapports planifiés haute fréquence, ou plusieurs viewers de dashboards simultanés — passez au déploiement Kubernetes avec un scaling horizontal approprié.

Ce que l’auto-hébergement inclut et exclut

Le déploiement Docker Compose inclut : les requêtes Explore, la construction de dashboards, les jointures multi-modèles, les graphiques personnalisés Vega-Lite, la gestion des utilisateurs et la planification basique (nécessite SCHEDULER_ENABLED=true et le service browserless).

Non disponible en auto-hébergé : exports CSV, smart caching, fonctionnalités IA (requêtage en langage naturel, MCP Server), embedding via le SDK React, accès API, et SSO au-delà de Google OAuth. Le passage du gratuit auto-hébergé au Cloud Pro (2 400 $/mois) est important, sans tier intermédiaire.