Lightdash is an MIT-licensed BI tool that reads directly from your dbt project’s YAML files and turns them into an interactive analytics layer. No separate modeling language, no parallel metric definitions — the dbt project is the semantic layer. These garden notes decompose the self-hosting guide into reusable concepts.
How Lightdash Reads Your dbt Project
How Lightdash Connects to Your dbt Project — The three mechanisms for connecting Lightdash to a dbt repository: direct Git integration, lightdash deploy from the CLI, and CI/CD automation. Includes a working GitHub Actions workflow and an explanation of what Lightdash reads from compiled dbt output to generate the Explore UI.
Deployment
Self-Hosting Lightdash with Docker Compose — Running Lightdash with Docker Compose. The three required services (application, PostgreSQL, headless browser), critical environment variables, known gotchas (port 3000 vs 8080, the uuid-ossp extension requirement), and what to expect from small-team production deployments.
Lightdash in Production: Kubernetes Deployment — Moving to Kubernetes with the community Helm chart. Production checklist: external PostgreSQL, S3-compatible object storage, HTTPS, SMTP. Authentication tier limitations and a safe upgrade strategy for the aggressive release cadence.
The Metric Layer
The YAML metric configuration syntax lives in the existing hub at Lightdash + dbt YAML: Metrics Reference Hub, which breaks into:
- Lightdash Dimension Configuration in dbt YAML — Dimension types, hidden columns, time intervals, format strings, and additional_dimensions
- Lightdash Metric Types and Definition Syntax — Aggregate, non-aggregate, and post-calculation metric categories; column-level vs model-level placement; filters and display properties
- Lightdash Joins and Fanout Protection — Defining joins between models and why the
relationshipproperty prevents inflated metrics - Organizing Lightdash Metrics at Scale — Groups, the Metrics Catalog, Spotlight categories, and parameters for multi-environment deployments
Comparing Semantic Layer Approaches
Lightdash's Semantic Layer vs MetricFlow — Lightdash’s native metric layer vs MetricFlow. Simpler YAML syntax vs richer entity-based modeling. Lightdash-only vs cross-platform API. When adoption friction matters more than tool flexibility, and when it doesn’t.
Positioning and Licensing
BI Tool Self-Hosting and Licensing — MIT vs AGPL vs proprietary licensing, and what the open-source tier actually includes. Feature comparison between Lightdash self-hosted (free), Cloud Pro ($2,400/month), and Enterprise.
BI Tool Selection Framework — When Lightdash fits and when it doesn’t. The four deciding questions: dbt investment, governance requirements, budget, and user sophistication. Head-to-head comparison with Looker and Metabase.
Context
Lightdash is one expression of a broader architectural shift — dbt becoming the foundation layer that BI tools read from rather than a parallel concern. dbt as the Center of Gravity for BI covers that shift and the market context. Semantic Layer Architecture compares Lightdash’s approach to MetricFlow, Snowflake Semantic Views, and Databricks Metric Views.