dbt Fusion Dev Container Template

A development container template for dbt projects that use the new Fusion engine with the official dbt VS Code extension.

What's a dev container?

• A dev container is a Docker container specifically configured to serve as a fully featured, consistent, isolated, and portable development environment
• Defined in .devcontainer/devcontainer.json within a project
• Read more about them in GitHub Docs

Why should I use dbt-fusion within a container?

dbt-fusion is written in Rust, not Python, and isn't distributed through or installable from PyPI like dbt-core is. This means that Python-based virtual environment tools & package managers like venv, pip, or uv don't apply. Instead, the recommended installation method (either via the VS Code extension or directly from the command line) puts the dbt-fusion executable--a standalone binary CLI tool--in a directory available through your system’s PATH.

This makes it easy to run, but it can also lead to potential conflicts with other dbt installations, especially if you have both Python-based and Rust-based dbt CLIs on the same machine. If you want to avoid those conflicts or if you want to experiment with different dbt-fusion projects in an isolated environment without affecting existing setups, using a development container is a solid option!

General benefits of using containers include:

• Isolated environments for each project (preventing dependency and path conflicts)
• Reproducible builds and consistent environments across teams
• Faster setup and onboarding for new contributors
• Simplified experimentation without impacting your main system configuration or other projects

Read more here: Why You Should Sse Dev Containers with dbt Fusion - Brooklyn Data Co.

Requirements

• Docker Desktop
• VS Code with the Dev Containers (or Remote Explorer) extension
• A dbt project with a proper:
  • dbt_project.yml in the workspace/project folder root
  • Proper configs in your local ~/.dbt directory

Features

• A clean and isolated environment to run the official dbt VS Code Extension
  • The extension will download dbt-fusion on your behalf
  • Also compatible with Cursor
• Base Python development environment / tools
  • Python 3.12 and uv
  • Note: The dbt-fusion engine does NOT need Python to run. These are added to the base image to enable flexibility for being able to easily add other Python-based dev tools or to run arbitrary Python in the dev container.
• Git
• Pre-configured settings for SQL, YAML, and Python

Usage

For a detailed configuration (and comments about what each is for), check out the example configuration here.

1. Add the following to your project's .devcontainer/devcontainer.json:

   {
     "image": "ghcr.io/brooklyn-data/dbt-fusion-devcontainer/dbt-fusion:latest",
     "remoteUser": "vscode",
     "mounts": [
       "source=${localEnv:HOME}/.dbt,target=/home/vscode/.dbt,type=bind",
       "source=${localEnv:HOME}/.ssh,target=/home/vscode/.ssh,type=bind" // mount if git authentication uses SSH
     ],
     "workspaceMount": "source=${localWorkspaceFolder},target=/workspaces/${localWorkspaceFolderBasename},type=bind,consistency=cached",
     "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
     "customizations": {
       "vscode": {
         "settings": {
           "dbt.dbtPath": "/home/vscode/.local/bin/dbt",
           "files.associations": {
             "*.sql": "sql",
             "*.yml": "yaml"
           },
           "[sql]": {
             "editor.defaultFormatter": "dbtLabsInc.dbt",
             "editor.formatOnSave": true
           },
           "[yaml]": {
             "editor.defaultFormatter": "dbtLabsInc.dbt",
             "editor.formatOnSave": true
           },
           "[python]": {
             "editor.defaultFormatter": "charliermarsh.ruff",
             "editor.formatOnSave": true
           },
           "yaml.schemas": {
             "https://raw.githubusercontent.com/dbt-labs/dbt-jsonschema/main/schemas/latest/dbt_yml_files-latest.json": [
               "/**/*.yml",
               "!profiles.yml",
               "!dbt_project.yml",
               "!packages.yml",
               "!selectors.yml",
               "!profile_template.yml",
               "!package-lock.yml"
             ],
             "https://raw.githubusercontent.com/dbt-labs/dbt-jsonschema/main/schemas/latest/dbt_project-latest.json": [
               "dbt_project.yml"
             ],
             "https://raw.githubusercontent.com/dbt-labs/dbt-jsonschema/main/schemas/latest/selectors-latest.json": [
               "selectors.yml"
             ],
             "https://raw.githubusercontent.com/dbt-labs/dbt-jsonschema/main/schemas/latest/packages-latest.json": [
               "packages.yml"
             ]
          }
         },
         "extensions": [
           "ms-python.python",
           "charliermarsh.ruff",
           "ms-python.vscode-pylance",
           "tamasfe.even-better-toml",
           "EditorConfig.EditorConfig",
           "eamodio.gitlens",
           "visualstudioexptteam.vscodeintellicode",
           "dbtlabsinc.dbt",
           "redhat.vscode-yaml"
         ]
       }
     },
     "features": {
       "ghcr.io/devcontainers/features/common-utils:2": {
         "installZsh": true,
         "username": "vscode",
         "upgradePackages": true
       },
       "ghcr.io/devcontainers/features/python:1": {
         "version": "3.12",
         "installTools": true
       }
     }
   }

   Note: The extensions with this configuration are installed by VS Code when the container starts for ease of setup. To manage the extension installation yourself, remove the "features" key from the devcontainer.json file.

2. Open your project in VS Code and use the Dev Containers (or Remote Explorer) extension to build and run the container. (docs)

3. Allow some time for the extensions to install and follow dbt's prompt to install dbt-fusion

dbt Fusion Resources

• Meet the dbt Fusion Engine... - Jason Ganz
• Up & Running with dbt Fusion Engine and VS Code - Anders Swanson
• Docs: dbt Fusion
• GitHub: dbt-fusion
• dbt Fusion Slack Channel

About Brooklyn Data

Brooklyn Data offers full-service capabilities for implementing the modern data stack. Our data experts help you develop impactful data strategies, manage data effectively, and leverage AI to activate your data. Read more at brooklyndata.co.