Skip to main content

​
Mage Pro (auto-generate and serve)

If you’re using Mage Pro, dbt docs can be automatically generated and served when the app starts.
  • Set the environment variable ENABLE_DBT_DOCS=true.
  • Mage will discover dbt projects under /dbt, generate docs (if missing), and serve them.
  • Open a project’s docs from the UI:
    • In File Browser, right-click the dbt project folder and click “Open dbt docs”.
    • The docs are available at /dbt_docs/[dbt_project_name].
    • The path /dbt_docs shows the status for all dbt projects (running port, errors, etc.).
To regenerate docs manually, add a generic dbt block in a pipeline and run dbt docs generate.

​
Generating docs

Before enabling dbt docs in production, we need to make sure the static files for the docs are generated.
  1. Configure the dbt super project.
    • Your dbt projects should be in the /path/to/<mage_project>/dbt directory.
      • The /dbt directory will serve as a “super-project” for all of your dbt projects in your Mage project.
    • Make sure the /.../<mage_project>/dbt directory has the files dbt_project.yml, profiles.yml, and packages.yml. These files are needed for dbt to create docs for all the projects within this directory.
      1. dbt_project.yml 
        name: 'base'
version: '1.0.0'
config-version: 2
profile: 'base'
target-path: "target"
clean-targets:
  - "target"
  - "dbt_packages"
      2. profiles.yml: The config in this file is not used, but it needs to still be a valid output target in order for the project to compile. 
        base:
  target: dev
  outputs:
    dev:
      <output_config>
      3. packages.yml: Add all projects that you want to be included in the documentation. 
        packages:
  - local: ./project1
  - local: ./project2
  2. Generate the dbt docs 
      dbt deps
  dbt docs generate

​
Terraform

​
GCP

In the mage-ai-terraform-templates repository, the terraform templates for GCP have commented out resources at the end of the following files for enabling the dbt docs service. Once you uncomment those resources, you should see an output docs_service_ip at the end of terraform apply with the IP to access the dbt docs in the cloud. 
Outputs:
docs_service_ip = "<dbt_docs_ip>"
service_ip = "<mage_ip>"

​
AWS

Coming soon…