Local Docs Server & APIs
Relevant source files
The following files were used as context for generating this wiki page:
The dbt-docs-server is a Rust-based, read-only, and stateless server that provides the next generation of documentation for dbt projects. It replaces the dbt Core v1 dbt docs generate and serve commands, specifically optimized for the Rust/Fusion runtime. The server loads project artifacts directly from Parquet files produced by the Fusion engine into an in-memory database to answer documentation and API queries.
Sources: crates/dbt-docs-server/README.md, README.md
System Architecture
The documentation system is built around a single self-contained binary that embeds both a REST API and a React Single Page Application (SPA). At boot, the server loads Parquet artifacts from a specified target directory into an in-memory DuckDB analytical engine via ADBC.
The server is stateless; to refresh the documentation content, it must be pointed at a fresh set of artifacts and restarted.
Sources: crates/dbt-docs-server/README.md
Data Sources and Ingestion
Unlike previous versions that relied on manifest.json, the dbt-docs-server utilizes Parquet files located in <target>/index/. These files are generated by running dbt commands (run, build, compile) with the --write-index flag.
Ingestion Flow
- Metadata Ingestion: The system can ingest delta metadata before starting the server to ensure the index is up to date.
- DuckDB Backend: Uses
DuckDbViewsBackendto open the index directory. - ADBC Driver: The server requires an ADBC DuckDB driver, which is downloaded at first boot if not present in the cache.
API and UI Features
The server provides a comprehensive project catalog and interactive tools for analyzing dbt projects.
| Feature | Description |
|---|---|
| Full Project Catalog | Covers models, sources, seeds, snapshots, tests, macros, metrics, and semantic models. |
| Interactive Lineage | Node-to-node DAG lineage visualization. |
| Execution Info | Surfacing last-run status, completion times, and errors from run results. |
| Single Binary | API and SPA are baked into the binary using the rust-embed feature. |
| Read-Only REST API | JSON endpoints served under the /api/v1/* path. |
Sources: crates/dbt-docs-server/README.md, crates/dbt-docs-server/Cargo.toml
Configuration and Deployment
The docs server can be configured via command-line flags or environment variables.
Configuration Options
| Flag | Environment Variable | Default | Description |
|---|---|---|---|
--target-path | DBT_DOCS_TARGET_PATH | ./target | Path to directory containing index/*.parquet |
--host | DBT_DOCS_HOST | 127.0.0.1 | Bind address for the HTTP server |
--port | DBT_DOCS_PORT | 8580 | Listening port |
--no-open | N/A | Off | Disable auto-opening the browser |
Sources: crates/dbt-docs-server/README.md, crates/dbt-main/src/dbt_lib.rs:1080-1100
Docker Deployment
The project includes a Dockerfile and docker-compose.yml. Because the ADBC driver is downloaded at runtime, persistent volumes are recommended for the cache directory (/var/cache/dbt) to enable offline operation after the initial "warming" of the container.
Sources: crates/dbt-docs-server/README.md
Content Generation Defaults
The documentation server includes fallback content for project overviews. If a user project does not define its own {% docs __overview__ %} block, the server injects a default overview.
// crates/dbt-parser/src/constants.rs
pub const DEFAULT_OVERVIEW_CONTENTS: &str = "\
### Welcome!
Welcome to the auto-generated documentation for your dbt project!
### Navigation
...
";
This ensures the dbt Docs HTML does not crash when the doc.dbt.__overview__ entry is expected but missing from the project source.
Sources: crates/dbt-parser/src/constants.rs:5-42
Summary
The Local Docs Server in dbt Core v2.0 represents a shift toward high-performance, artifact-based documentation. By leveraging Rust, Axum, and an in-memory DuckDB instance querying Parquet files, it provides a scalable and responsive experience for even the largest dbt projects without requiring a live connection to a data warehouse.
Sources: README.md, crates/dbt-docs-server/README.md