Héberger la documentation dbt au-delà de localhost

dbt docs est un site statique et peut être hébergé partout où des fichiers statiques peuvent aller. Le bon choix dépend des exigences d’authentification, de l’infrastructure existante et des préférences de l’équipe. dbt docs serve est un outil de prévisualisation, pas une stratégie de déploiement — la documentation officielle de dbt l’indique explicitement.

Comparaison rapide

GitHub Pages ou GitLab Pages

L’option la plus simple pour les équipes déjà sur ces plateformes. Générer la documentation avec le flag —static, pousser le fichier résultant vers une branche, et laisser Pages le servir.

La distinction critique : GitHub Pages est public par défaut. Les Pages privées nécessitent GitHub Enterprise Cloud. Si votre projet dbt est interne et que vos modèles contiennent de la logique métier sensible ou des noms propriétaires, cette limitation est importante. La documentation publique expose la structure de votre modèle de données à n’importe qui.

GitLab Pages restreint l’accès aux utilisateurs ayant accès au dépôt par défaut, ce qui convient souvent mieux aux projets internes sans configuration supplémentaire.

Un workflow GitHub Actions de base :

name: Deploy dbt docs
on:
  push:
    branches: [main]

jobs:
  deploy-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install dbt
        run: pip install dbt-bigquery  # ou votre adaptateur
      - name: Generate docs
        run: dbt docs generate --static
        env:
          DBT_PROFILES_DIR: .
      - name: Deploy to Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./target

Ce workflow se déclenche à chaque fusion vers main. La documentation se met à jour automatiquement. Voir Automatiser le déploiement de la documentation dbt pour des patterns CI/CD plus sophistiqués.

Netlify

Netlify offre un déploiement avec une seule commande CLI et un contrôle d’accès optionnel :

netlify deploy --prod --dir=target

La protection par mot de passe est disponible avec les plans payants. L’authentification au niveau de l’équipe coûte 9 $ par utilisateur et par mois. Pour les équipes qui souhaitent quelque chose de légèrement plus soigné que Pages sans gérer d’infrastructure, Netlify représente un bon compromis.

La commande de déploiement peut être ajoutée à n’importe quel pipeline CI. Netlify prend également en charge les déploiements automatiques depuis les branches Git, les déploiements de prévisualisation pour les pull requests (utile pour examiner les changements de documentation avant de fusionner), et les domaines personnalisés avec TLS automatique.

Google Cloud Storage avec Identity-Aware Proxy

Pour les équipes sur GCP, cette approche offre une authentification basée sur Google à un coût quasi nul. L’architecture :

1. Envoyer la documentation vers un bucket GCS configuré pour l’hébergement de sites statiques (gsutil web set)
2. Mettre App Engine devant comme couche de service
3. Activer Identity-Aware Proxy (IAP)

Toute personne disposant du bon compte Google (votre domaine Workspace) peut accéder à la documentation. Les autres sont repoussées. Le coût est proche de zéro puisque vous servez des fichiers statiques avec une authentification gérée au niveau de l’infrastructure.

Ce pattern fonctionne particulièrement bien pour les organisations qui gèrent déjà leur identité via Google Workspace. Pas de fournisseur d’identité supplémentaire nécessaire. Hiflylabs a documenté ce pattern qui s’intègre proprement aux équipes qui exécutent déjà leurs projets dbt sur BigQuery.

S3 + CloudFront (AWS)

L’équivalent AWS utilise :

• S3 pour le stockage
• CloudFront pour la distribution CDN
• Fonctions Lambda avec OIDC pour l’accès authentifié

Plus flexible que l’approche GCP mais plus de composants à configurer. Si votre équipe gère déjà l’infrastructure AWS et utilise IAM pour le contrôle d’accès, cela s’intègre naturellement dans vos patterns existants. La couche CDN aide également à la performance en servant les assets statiques depuis des edge locations plus proches de vos utilisateurs.

Docker et Nginx

L’option la plus portable. Un Dockerfile minimal copie votre documentation dans Nginx :

FROM nginx:alpine
COPY target/ /usr/share/nginx/html/

Ce conteneur peut se déployer sur :

• Cloud Run — sans serveur, se scale à zéro, facturation à la requête
• ECS / Fargate — service de conteneurs AWS
• Kubernetes — si vous avez déjà un cluster
• Tout serveur interne exécutant Docker

Cette approche fonctionne bien pour les organisations qui exécutent déjà des charges de travail en conteneurs et souhaitent que la documentation soit hébergée aux côtés d’autres outils internes. L’authentification dépend de ce qui se trouve devant le conteneur — un load balancer avec OAuth, un VPN, ou l’authentification native de la plateforme (IAM de Cloud Run, par exemple).

Heuristiques de décision

• Petite équipe sur GitHub Enterprise : GitHub Pages avec le flag --static — faible effort de configuration, la documentation se met à jour à chaque fusion.
• GCP avec Google Workspace : Cloud Storage + IAP — maintenance minimale, utilise la gestion d’identité existante.
• Le projet a dépassé quelques centaines de modèles et l’interface par défaut est lente : voir Performance de dbt Docs à grande échelle et Alternatives à dbt Docs par défaut.
• L’équipe exécute déjà des conteneurs : Docker + Nginx sur la plateforme existante.

Le choix d’hébergement n’est pas permanent. Des options plus simples peuvent être adoptées en premier et remplacées si les exigences changent.