Developer Onboarding

This guide walks you through setting up your local development environment from scratch. By the end, you will have a working dbt build running against a local DuckDB database -- no Fabric connection required.

Prerequisites Checklist

Before you begin, ensure you have the following installed:

Access requirements:

• Git access to the Azure DevOps repo (org: geris-devops, project: insights-requests)
• An Azure account with Fabric workspace access (for remote targets)

Onboarding Sequence

The following diagram shows the complete onboarding flow. Steps 1-6 get you to a working local build; step 7 onward connects you to Fabric.

graph TD
    A["1. Install prerequisites<br/><small>Python 3.11, Node.js 20+,<br/>az CLI, ODBC 18, Terraform</small>"]
    B["2. az login<br/><small>Authenticate with Azure</small>"]
    C["3. Clone the repo<br/><small>git clone from Azure DevOps</small>"]
    D["4. Install Python packages<br/><small>pip install dbt-fabric dbt-duckdb<br/>fabric-cicd pyodbc azure-identity</small>"]
    E["5. Install dbt packages<br/><small>cd dbt && dbt deps --profiles-dir .</small>"]
    F["6. First local build<br/><small>dbt build --target local --profiles-dir .</small>"]
    G["7. Verify local build<br/><small>All models pass, DuckDB file created</small>"]
    H["8. Optional: Build against Fabric<br/><small>Set env vars, dbt build --target dev</small>"]

    A --> B --> C --> D --> E --> F --> G --> H

    style F fill:#2d6a4f,color:#fff
    style G fill:#2d6a4f,color:#fff

Step-by-Step Walkthrough

1. Install Prerequisites

Install the tools listed in the prerequisites table above. For Python, we strongly recommend 3.11 -- it is the version used in CI and has been thoroughly tested with all dependencies.

Verify your installations:

python --version        # Should show 3.10.x, 3.11.x, or 3.12.x
node --version          # Should show v20.x or higher
az --version            # Should show azure-cli 2.x
terraform --version     # Should show v1.8+
git --version           # Any recent version

2. Authenticate with Azure

az login

This opens a browser window for Microsoft login. After authentication, your session is cached and reused by dbt, Terraform, and all scripts. You do not need SPN credentials for local development -- CLI auth is the standard for this project.

3. Clone the Repository

git clone https://geris-devops@dev.azure.com/geris-devops/insights-requests/_git/insights-requests
cd insights-requests

Then configure the pre-commit hooks for secret scanning:

git config core.hooksPath .githooks

This enables the drift-check post-commit hook that runs automatically on every commit.

4. Install Python Packages

pip install dbt-fabric dbt-duckdb fabric-cicd pyodbc azure-identity azure-keyvault-secrets
pip install uv  # Provides uvx for Python-based MCP servers

Important: Do NOT add dbt-fabric or dbt-duckdb to packages.yml -- they are pip packages, not dbt Hub packages. Adding them there breaks dbt deps.

5. Install dbt Packages

cd dbt
dbt deps --profiles-dir .

This installs dbt_utils from the dbt Hub. The --profiles-dir . flag is required because profiles.yml lives in the dbt/ directory, not the default ~/.dbt/ location. You will need this flag on every dbt command.

6. First Local Build

dbt build --target local --profiles-dir .

This runs the full dbt pipeline against a local DuckDB database. It:

• Bootstraps DuckDB from Parquet seed files in dev-data/ (via the load_parquet_sources() macro)
• Creates all staging views, intermediate views, and mart tables
• Runs all dbt tests
• Completes in seconds (vs minutes against Fabric)

Expected output: All 176 models pass. A DuckDB file is created at dbt/fabric_datalake.duckdb.

7. Verify the Build

After a successful build, you can query the local DuckDB database to verify the data:

# Using the DuckDB MCP server (if configured), or directly:
python -c "
import duckdb
con = duckdb.connect('fabric_datalake.duckdb', read_only=True)
print(con.sql('SELECT count(*) as model_count FROM information_schema.tables').fetchone())
con.close()
"

You should see a count matching the number of materialized models in your build.

8. Optional: Build Against Fabric

Once your local build works, you can connect to the DEV Fabric Warehouse:

# Set environment variables (values from deployment/dev.yml)
export FABRIC_SERVER="<warehouse-server>.datawarehouse.fabric.microsoft.com"
export FABRIC_DATABASE="Gold_Warehouse"

# Build against DEV
dbt build --target dev --profiles-dir .

This uses your az login session for authentication -- no SPN credentials needed. The build runs against the real Fabric Warehouse and takes significantly longer than the local DuckDB build.

Common Issues

MCP Server Setup (Optional)

The project includes 9 MCP servers configured in .mcp.json at the repo root. These are automatically picked up by Claude Code and other MCP-compatible AI tools. No per-user configuration is needed -- just ensure the prerequisites (Node.js, uv, Docker, az CLI) are installed.

MCP servers that require authentication will prompt for browser login on first use. Servers that need az login use your existing session.

For the full list of MCP servers and their capabilities, see Technology Stack.

What's Next?

Now that your environment is set up, explore these topics:

• System Architecture -- understand how the 4 layers connect and why
• Data Flow Pipeline -- trace data from source systems to reports
• Workspace Layout -- the 4-workspace model and feature branches
• Technology Stack -- deep dive into tools, versions, and decisions
• FAQ -- answers to common developer questions