dbt docs serve - Step-by-Step Execution

Concept Flow - dbt docs serve

Run 'dbt docs generate'

↓

Generate docs site files

↓

Run 'dbt docs serve'

↓

Start local web server

↓

Open browser at http://localhost:8080

↓

View interactive dbt documentation

↓

Stop server when done

This flow shows how dbt docs serve starts a local web server to display your project's documentation after generating it.

Execution Sample

dbt

dbt docs generate
 dbt docs serve

Generates documentation files and then starts a local server to view them in a browser.

Execution Table

Step	Command Run	Action	Result	Output
1	dbt docs generate	Generate docs files	Docs JSON and site files created	Files saved in target/catalog.json and target/index.html
2	dbt docs serve	Start local server	Server running on localhost:8080	Server logs showing URL
3	Open browser	Access docs site	Docs site loads	Interactive docs UI visible
4	Stop server	Terminate server process	Server stops	No server running
5	-	End	No further action	Process complete

💡 Server stops when user interrupts (Ctrl+C) or closes terminal

Variable Tracker

Variable	Before docs generate	After docs generate	After docs serve start	After server stop
docs_files_exist	False	True	True	True
server_running	False	False	True	False
browser_opened	False	False	True	False

Key Moments - 2 Insights

Why do I need to run 'dbt docs generate' before 'dbt docs serve'?

Because 'dbt docs serve' needs the generated documentation files to serve. See execution_table step 1 and 2 where files are created first, then the server starts.

What happens if I close the terminal while 'dbt docs serve' is running?

The server stops running because it runs in the terminal session. See execution_table step 4 where stopping the server ends the process.

Visual Quiz - 3 Questions

Look at the execution_table, what is the output after running 'dbt docs generate'?

A Server running on localhost:8080

B Interactive docs UI visible

C Files saved in target/catalog.json and target/index.html

D No server running

💡 Hint

Check execution_table row 1, Output column

At which step does the local server start running?

A Step 1

B Step 2

C Step 3

D Step 4

💡 Hint

Look at execution_table Step and Action columns

If you stop the server, what happens to the 'server_running' variable in variable_tracker?

A It changes from True to False

B It changes from False to True

C It stays True

D It becomes undefined

💡 Hint

See variable_tracker row for 'server_running' from 'After docs serve start' to 'After server stop'

Concept Snapshot

dbt docs serve
- Run 'dbt docs generate' first to create docs files
- Then run 'dbt docs serve' to start a local web server
- Open http://localhost:8080 in browser to view docs
- Stop server with Ctrl+C when done
- Shows interactive dbt project documentation

Full Transcript

The 'dbt docs serve' command starts a local web server to display your dbt project's documentation. First, you run 'dbt docs generate' to create the documentation files. Then, 'dbt docs serve' launches a server on your computer, usually at http://localhost:8080. You open this address in your web browser to see an interactive documentation site showing your models, sources, and tests. When you finish, you stop the server by closing the terminal or pressing Ctrl+C. This process helps you explore your dbt project documentation easily on your local machine.