Hosting dbt Docs Beyond Localhost

dbt docs is a static site and can be hosted anywhere static files can go. The right choice depends on authentication requirements, existing infrastructure, and team preference. dbt docs serve is a preview tool, not a deployment strategy — dbt’s own documentation states this explicitly.

Quick comparison

GitHub Pages or GitLab Pages

The simplest option for teams already on these platforms. Generate docs with the —static flag, push the resulting file to a branch, and let Pages serve it.

The critical distinction: GitHub Pages are public by default. Private Pages require GitHub Enterprise Cloud. If your dbt project is internal and your models contain sensitive business logic or proprietary naming, this limitation matters. Public docs expose your data model structure to anyone.

GitLab Pages restrict access to users with repository access by default, which is often a better fit for internal projects without additional configuration.

A basic GitHub Actions workflow:

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  # or your adapter
      - 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

This workflow triggers on every merge to main. The docs update automatically. See Automating dbt Docs Deployment for more sophisticated CI/CD patterns.

Netlify

Netlify gives you deployment with a single CLI command and optional access control:

netlify deploy --prod --dir=target

Password protection comes with paid plans. Team-level authentication runs $9 per user per month. For teams that want something slightly more polished than Pages without managing infrastructure, Netlify hits a reasonable middle ground.

The deploy command can be added to any CI pipeline. Netlify also supports automatic deploys from Git branches, preview deploys for pull requests (useful for reviewing docs changes before merging), and custom domains with automatic TLS.

Google Cloud Storage with Identity-Aware Proxy

For teams on GCP, this approach provides Google-based authentication at near-zero cost. The architecture:

1. Upload docs to a GCS bucket configured for static website hosting (gsutil web set)
2. Put App Engine in front of it as the serving layer
3. Enable Identity-Aware Proxy (IAP)

Anyone with the right Google account (your Workspace domain) can access the docs. Everyone else gets turned away. The cost is close to zero since you are serving static files with authentication handled at the infrastructure layer.

This pattern works especially well for organizations that already manage identity through Google Workspace. No additional identity provider needed. Hiflylabs documented this pattern and it integrates cleanly with teams already running their dbt projects on BigQuery.

S3 + CloudFront (AWS)

The AWS equivalent uses:

• S3 for storage
• CloudFront for CDN distribution
• Lambda functions with OIDC for authenticated access

More flexible than the GCP approach but more pieces to configure. If your team already manages AWS infrastructure and uses IAM for access control, this fits naturally into your existing patterns. The CDN layer also helps with performance by serving the static assets from edge locations closer to your users.

Docker and Nginx

The most portable option. A minimal Dockerfile copies your docs into Nginx:

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

This container can deploy to:

• Cloud Run — serverless, scales to zero, pay per request
• ECS / Fargate — AWS container service
• Kubernetes — if you already run a cluster
• Any internal server running Docker

This approach works well for organizations that already run container workloads and want docs hosted alongside other internal tools. Authentication depends on what sits in front of the container — a load balancer with OAuth, a VPN, or the platform’s native auth (Cloud Run’s IAM, for example).

Decision heuristics

• Small team on GitHub Enterprise: GitHub Pages with the --static flag — low setup effort, docs update on every merge.
• GCP with Google Workspace: Cloud Storage + IAP — minimal ongoing maintenance, uses existing identity management.
• Project has grown past a few hundred models and the default UI lags: see dbt Docs Performance at Scale and Alternatives to Default dbt Docs.
• Team already runs containers: Docker + Nginx on existing platform.

The hosting choice is not permanent. Simpler options can be adopted first and replaced if requirements change.