Quick Start¶

Get your first data pipeline running in under 10 minutes.

Prerequisites¶

Before starting, make sure you have:

• Installed Dango (Installation Guide)
• Python 3.10+ and Docker Desktop running
• Virtual environment activated (if using venv)

Step 1: Install and Initialize¶

Run the install script to set up your project:

curl -sSL https://getdango.dev/install.sh | bash

irm https://getdango.dev/install.ps1 | iex

The installer will:

• Create a project directory
• Set up an isolated virtual environment
• Install Dango from PyPI
• Run dango init to configure your project

During dango init, you set an admin password for the Web UI. This configures authentication automatically — no extra setup needed.

cd my-analytics
source venv/bin/activate

cd my-analytics
.\venv\Scripts\Activate.ps1

Step 2: Add a Data Source¶

Let's add your first data source. Dango supports 33 data sources including file imports, APIs, databases, and OAuth-based services.

Option A: File Import (Simplest)¶

dango source add

Follow the prompts:

1. Select File Import (CSV, JSON, Parquet) as the source type
2. Provide a path to your data file (CSV, JSON, or Parquet)
3. Give it a descriptive name (e.g., sales_data)

Example:

$ dango source add
? Select source type: File Import (CSV, JSON, Parquet)
? File path: /path/to/your/data.csv
? Source name: sales_data
✓ Source 'sales_data' added successfully

Your sources.yml will look like this:

# .dango/sources.yml
sources:
  - name: sales_data
    type: local_files
    local_files:
      file_path: /path/to/your/data.csv

Option B: Stripe (API Integration)¶

For a more advanced example, try Stripe:

dango source add

Follow the prompts:

1. Select Stripe as the source type
2. Enter your Stripe API key (get it from Stripe Dashboard)
3. Give it a descriptive name (e.g., stripe_payments)

Option C: Google Sheets (OAuth)¶

dango source add

Follow the prompts:

1. Select Google Sheets as the source type
2. Complete OAuth authentication in your browser
3. Provide the Google Sheet URL
4. Give it a descriptive name (e.g., marketing_data)

Step 3: Sync Your Data¶

Now let's pull data from your source into DuckDB:

dango sync

What happens during sync:

1. dlt connects to your data source
2. Data is loaded into the raw schema in DuckDB
3. dbt generates staging models automatically
4. Transformations run to create clean, deduplicated data

Example output:

$ dango sync
[18:30:45] Starting sync for all sources...
[18:30:46] → sales_data: Extracting data...
[18:30:47] → sales_data: Loading to DuckDB...
[18:30:48] → sales_data: 1,234 rows loaded
[18:30:49] Running dbt transformations...
[18:30:51] ✓ 3 models completed successfully
[18:30:51] ✓ Sync completed in 6.2s

Dry Run (Preview Without Executing)¶

To preview what will happen without executing:

dango sync --dry-run

Step 4: Start the Platform¶

Start the Web UI, Metabase, and dbt docs server:

dango start

What starts:

• Web UI — http://localhost:8800
• Metabase — Accessible through the Web UI (SSO bridge)
• dbt docs — Accessible through the Web UI

Example output:

$ dango start
[18:31:00] Starting Dango platform...
[18:31:02] ✓ Docker containers started
[18:31:05] ✓ Metabase ready
[18:31:06] ✓ Web UI ready at http://localhost:8800
[18:31:06] ✓ Platform started successfully
[18:31:06] Opening http://localhost:8800 in your browser...

Your browser should open automatically. If it doesn't, visit http://localhost:8800 manually. Log in with the admin password you set during dango init.

Open the Dashboard¶

open http://localhost:8800

Start-Process http://localhost:8800

Or simply visit http://localhost:8800 in your browser.

Step 5: Explore Your Data¶

Web UI (http://localhost:8800)¶

The Web UI provides:

• Pipeline Status — See all your data sources and their sync status
• Data Sources — Add, edit, and manage sources
• Transformations — View and manage dbt models
• Metabase — Access dashboards (SSO bridge, no separate login needed)
• dbt docs — Explore your data models
• Monitoring — Schema drift alerts, sync history, health checks

Metabase Dashboards¶

1. Click "Open Metabase" in the Web UI sidebar
2. Metabase is auto-configured with your DuckDB database
3. Start exploring your data with SQL or the visual query builder

Query Your Data with SQL¶

You can query DuckDB directly using Metabase's SQL editor (via the Web UI) or from the command line. Open an interactive DuckDB session:

duckdb data/warehouse.duckdb

D SELECT * FROM staging.stg_sales_data LIMIT 10;
D .exit

Recommended: Use Metabase's SQL editor (accessible via the Web UI at http://localhost:8800) for a better query experience with autocomplete and visualization.

Step 6: Add Transformations¶

Dango auto-generates staging models, but you can add your own transformations:

Create a New dbt Model¶

1. Navigate to your dbt models directory:

   cd dbt_project/models/
   

2. Create a new model file (e.g., marts/revenue_summary.sql):

   {{ config(materialized='table') }}
   
   SELECT
       DATE_TRUNC('month', order_date) AS month,
       SUM(amount) AS total_revenue,
       COUNT(DISTINCT customer_id) AS unique_customers
   FROM {{ ref('stg_sales_data') }}
   GROUP BY 1
   ORDER BY 1 DESC
   

3. Run dbt to materialize your model:

   dango sync
   

Your new model is now available in DuckDB and Metabase!

Step 7: Automate with Scheduling¶

Set up automatic syncing on a schedule:

1. Enable in configuration:

Edit .dango/project.yml:

platform:
  auto_sync: true
  debounce_seconds: 600  # Wait 10 minutes after last change

2. Add a schedule:

dango schedule add

The interactive wizard will prompt you for the source name and schedule (e.g., "every day at 8am", custom cron expressions).

3. Start the platform:

dango start

The scheduler runs automatically while the platform is running.

Learn more in Scheduled Syncs and Configuring Schedules.

Common Workflows¶

Daily Data Pipeline¶

# Morning routine
source venv/bin/activate
dango sync                    # Pull fresh data
dango start                   # Start dashboards

Development Workflow¶

# Make changes to dbt models
cd dbt_project/models/

# Test your changes
dango sync --dry-run          # Preview changes
dango sync                    # Apply changes

# View results in Metabase
open http://localhost:8800

Adding More Sources¶

# Add another source
dango source add

# Sync all sources
dango sync

# Sync specific source only
dango sync stripe_payments

Verify Everything Works¶

Let's make sure your setup is complete:

# Check Dango is installed
which dango

# Validate installation
dango validate

# Check sync status
dango status

# List all sources
dango source list

Next Steps¶

Now that you have a working pipeline:

1. Your First Dashboard — Build a Metabase dashboard step by step
2. Core Concepts — Understand Dango's architecture
3. Data Sources — Connect more data sources
4. Transformations — Write advanced dbt models
5. Dashboards — Advanced Metabase features
6. Scheduling & Monitoring — Automate your pipelines
7. Security — Authentication, OAuth, credentials
8. Deployment — Deploy to the cloud
9. CLI Reference — Explore all 50+ commands
10. Notebooks — Interactive data exploration

Troubleshooting¶

"dango: command not found"¶

Make sure your virtual environment is activated:

source venv/bin/activate

.\venv\Scripts\Activate.ps1

If you just installed Dango, clear the shell's command cache:

hash -r

"Docker not running"¶

Start Docker Desktop and verify:

docker --version

"Port 8800 already in use"¶

Stop any running Dango instances:

dango stop

Or kill the process using the port:

lsof -ti:8800 | xargs kill -9

More Issues?¶

Check the full Troubleshooting Guide or open an issue.

Summary¶

You've successfully:

• ✅ Initialized a Dango project (with authentication)
• ✅ Added a data source
• ✅ Synced data to DuckDB
• ✅ Started the Web UI and Metabase
• ✅ Explored your data

Keep learning:

• Explore the CLI Reference for all 50+ commands
• Learn about Data Sources
• Master dbt Transformations
• Set up Scheduled Syncs