Init & Start¶

Project initialization and starting services via CLI.

Overview¶

This guide covers the essential commands for creating and starting Dango projects. Learn how to initialize new projects, configure settings, and start the platform.

What you'll learn:

Initialize new Dango projects
Understanding project structure
Configure platform settings
Start and stop services
Manage multiple projects
Troubleshoot startup issues

Initializing a New Project¶

Interactive Initialization¶

The recommended way to create a new project:

dango init my-analytics

Interactive wizard prompts:

Welcome to Dango!

Let's set up your data analytics project.

Project name: my-analytics
Organization (optional): Acme Corp
Created by: [email protected]

What's the purpose of this project?
> Track customer behavior and revenue metrics

Would you like to add a stakeholder? (Y/n): y
  Name: Bob Chen
  Role: CEO
  Email: [email protected]

Would you like to add another stakeholder? (y/N): n

Data SLA/Cadence (optional): Daily updates by 9am UTC

Known limitations (optional): Stripe data has 24h delay

Would you like to add a data source now? (Y/n): y

Select source type:
  1. CSV files
  2. Stripe
  3. Google Sheets
  ...

Creating project structure...
✓ Created .dango/project.yml
✓ Created .dango/sources.yml
✓ Created dbt/ directory
✓ Created data/ directory
✓ Created custom_sources/ directory
✓ Created docker-compose.yml
✓ Created .gitignore

Project initialized successfully!

Next steps:
  cd my-analytics
  dango start        # Start the platform
  dango sync         # Sync your first data source

Non-Interactive Initialization¶

Create a blank project without the wizard:

dango init my-analytics --skip-wizard

What it creates:

my-analytics/
├── .dango/
│   ├── project.yml          # Project metadata
│   └── sources.yml          # Data source configuration
├── .dlt/
│   ├── config.toml          # dlt configuration
│   └── secrets.toml         # Credentials (gitignored)
├── data/
│   └── .gitkeep             # Data files directory
├── dbt/
│   ├── dbt_project.yml      # dbt configuration
│   ├── profiles.yml         # DuckDB connection (auto-configured)
│   ├── models/
│   │   ├── staging/         # Auto-generated models
│   │   ├── intermediate/    # Your models
│   │   └── marts/           # Your models
│   ├── tests/               # Custom tests
│   ├── macros/              # Reusable SQL
│   └── packages.yml         # dbt packages
├── custom_sources/
│   └── __init__.py          # Custom dlt sources
├── docker-compose.yml       # Metabase + dbt-docs
├── .gitignore               # Git ignore rules
└── .env.example             # Environment variables template

Initialize in Current Directory¶

Initialize Dango in an existing directory:

cd existing-project
dango init .

Safety check:

Warning: Directory is not empty.
Files found:
  - data/sales.csv
  - README.md

Dango will create:
  - .dango/ directory
  - dbt/ directory
  - docker-compose.yml

Proceed? (y/N): y

Force Reinitialize¶

Reinitialize an existing project:

dango init my-analytics --force

Warning:

⚠ Project 'my-analytics' already exists!

This will OVERWRITE:
  - .dango/project.yml (backup created)
  - dbt/dbt_project.yml (backup created)

This will PRESERVE:
  - .dango/sources.yml
  - data/ directory
  - dbt/models/ (your custom models)

Backups saved to .dango/backups/2024-12-09-12-34-56/

Proceed? (y/N): y

Project Configuration¶

Project Metadata¶

Edit .dango/project.yml:

project:
  name: my-analytics
  organization: Acme Corp
  created_at: 2024-12-09
  created_by: [email protected]
  dango_version: 0.0.5

  purpose: |
    Track customer behavior and revenue metrics for
    executive dashboards and marketing analysis.

  stakeholders:
    - name: Bob Chen
      role: CEO
      email: [email protected]
      slack: "@bob"

    - name: Sarah Lee
      role: Senior Analyst
      email: [email protected]
      slack: "@sarah"

  sla:
    description: Daily updates by 9am UTC
    frequency: daily
    time: "09:00"
    timezone: UTC

  limitations:
    - Stripe data has 24h processing delay
    - Google Sheets updated manually
    - Facebook Ads API rate limited

platform:
  port: 8800
  metabase_port: 3000
  dbt_docs_port: 8081

  auto_sync: true
  debounce_seconds: 600  # 10 minutes

  file_watcher:
    enabled: true
    patterns:
      - "*.csv"
      - "*.json"
    ignored_dirs:
      - ".git"
      - "venv"
      - "node_modules"

database:
  path: data/warehouse.duckdb

  settings:
    memory_limit: "2GB"
    threads: 4

View Configuration¶

Display current configuration:

# Human-readable
dango info

# YAML format
dango config show

# Show current config
dango config show

Starting the Platform¶

Basic Start¶

Start all services:

dango start

Startup sequence:

Starting Dango platform...

[1/5] Starting FastAPI Web UI...
      ✓ Web UI started on http://localhost:8800

[2/5] Starting File Watcher...
      ✓ Watching data/ for changes
      ✓ Auto-sync enabled (600s debounce)

[3/5] Starting Docker services...
      Pulling metabase:latest (if needed)
      ✓ Metabase container started

[4/5] Waiting for Metabase to be ready...
      This may take 30-60 seconds on first run...
      ✓ Metabase ready on http://localhost:3000

[5/5] Starting dbt-docs server...
      ✓ dbt-docs started on http://localhost:8081

──────────────────────────────────────────────
✓ Platform running successfully!

Services:
  Web UI:    http://localhost:8800
  Metabase:  http://localhost:3000
  dbt-docs:  http://localhost:8081

Press Ctrl+C to stop, or run 'dango stop' in another terminal.
──────────────────────────────────────────────

Recommended: Access via the Web UI

Open http://localhost:8800 and click "Open Metabase" in the sidebar. The SSO bridge logs you in automatically — no need to look up Metabase credentials.

First-time setup takes longer:

Docker images downloaded (Metabase ~500 MB)
Metabase initializes database
dbt compiles project

Subsequent starts are faster (~10 seconds).

Skip Confirmation¶

Skip startup confirmation prompts:

dango start -y
dango start --yes

Custom Port¶

Change the default Web UI port in .dango/project.yml:

platform:
  port: 8888

Production Mode¶

For cloud deployments, use dango serve instead of dango start:

dango serve --host 0.0.0.0 --port 8800 --workers 2

Unlike dango start, serve binds to all interfaces, runs in the foreground (for systemd), and skips browser/file-watcher.

View logs using Docker:

# Tail all platform logs
docker compose logs -f

# View Metabase logs only
docker compose logs -f metabase

# Last 100 lines
docker compose logs --tail 100

For remote servers, use dango remote logs instead.

Checking Status¶

Platform Status¶

Check if platform is running:

dango status

Output when running:

Project: my-analytics (Port: 8800)
Status: ● Running

Services:
  FastAPI Web UI     ● Running (http://localhost:8800)
  File Watcher       ● Running (auto-sync enabled)
  Metabase          ● Running (http://localhost:3000)
  dbt-docs          ● Running (http://localhost:8081)

Database: data/warehouse.duckdb (42.3 MB)
Sources: 5 configured (4 enabled, 1 disabled)
Last activity: 2 minutes ago

Uptime: 3 hours 24 minutes

Output when stopped:

Project: my-analytics (Port: 8800)
Status: ○ Stopped

All services are stopped.
Run 'dango start' to start the platform.

Stopping the Platform¶

Normal Stop¶

Gracefully stop all services:

dango stop

Shutdown sequence:

Stopping Dango platform...

[1/4] Stopping File Watcher...
      ✓ File watcher stopped

[2/4] Stopping FastAPI Web UI...
      ✓ Web UI stopped

[3/4] Stopping Docker containers...
      ✓ Metabase container stopped
      ✓ dbt-docs container stopped

[4/4] Cleanup...
      ✓ PID files removed
      ✓ Temp files cleaned

Platform stopped successfully.

Stop All Projects¶

Stop all Dango projects on machine:

dango stop --all

Output:

Found 3 running Dango projects:

1. my-analytics (port 8800)
2. marketing-data (port 8801)
3. finance-etl (port 8802)

Stop all projects? (y/N): y

Stopping my-analytics...
✓ Stopped

Stopping marketing-data...
✓ Stopped

Stopping finance-etl...
✓ Stopped

All Dango projects stopped.

Restarting the Platform¶

No Restart Command

Dango does not have a dedicated restart command. To restart the platform, use:

dango stop && dango start

Use when:

Configuration changes
Upgrading Dango version
Resolving stuck processes

Example:

# Stop and start the platform
dango stop && dango start

Managing Multiple Projects¶

Project Routing¶

Dango maintains a routing registry for multiple projects:

Location: ~/.dango/routing.json

Contents:

{
  "projects": {
    "my-analytics": {
      "path": "/Users/alice/projects/my-analytics",
      "port": 8800,
      "created": "2024-12-09T12:00:00Z",
      "last_started": "2024-12-09T14:30:00Z"
    },
    "marketing-data": {
      "path": "/Users/alice/projects/marketing-data",
      "port": 8801,
      "created": "2024-11-15T09:00:00Z",
      "last_started": "2024-12-08T08:00:00Z"
    }
  }
}

Running Multiple Projects¶

Project 1:

cd ~/projects/my-analytics
dango start
# Web UI: http://localhost:8800
# Metabase: http://localhost:3000

Project 2 (different ports):

cd ~/projects/marketing-data
# Edit .dango/project.yml
#   port: 8801
#   metabase_port: 3001
#   dbt_docs_port: 8082
dango start
# Web UI: http://localhost:8801
# Metabase: http://localhost:3001

Access both simultaneously:

my-analytics: http://localhost:8800
marketing-data: http://localhost:8801

No Projects List Command

Dango does not have a projects list command. Each Dango project is an independent directory. Use standard file system commands to list projects:

# List your Dango projects
ls ~/projects/

# Check if a specific project is running
cd ~/projects/my-analytics
dango status

Switch Between Projects¶

# Stop current project
dango stop

# Navigate to another project
cd ~/projects/marketing-data

# Start new project
dango start

Troubleshooting Startup¶

Port Already in Use¶

Error:

✗ Failed to start Web UI
Error: Address already in use (port 8800)

Solution 1: Find and kill process:

# Find process using port 8800
lsof -i :8800
# Output: python 12345 alice ...

# Kill process
kill 12345

# Restart Dango
dango start

Solution 2: Change port in .dango/project.yml:

platform:
  port: 8888

Then restart:

dango stop && dango start

Docker Not Running¶

Error:

✗ Failed to start Metabase
Error: Cannot connect to Docker daemon

Solution:

# Start Docker Desktop (macOS/Windows)
open -a Docker

# Or start Docker daemon (Linux)
sudo systemctl start docker

# Wait for Docker to start, then
dango start

Or check that Docker is installed and running before starting Dango.

Database Locked¶

Error:

✗ Failed to connect to database
Error: database is locked

Cause: Another process has database open.

Solution:

# Find processes with database open
lsof data/warehouse.duckdb

# Kill processes
kill <PID>

# Restart
dango start

Metabase Won't Start¶

Error:

✗ Metabase failed to start
Container exited with code 1

Check logs:

docker logs dango-metabase-my-analytics

Common fixes:

Port conflict:

# Change Metabase port in docker-compose.yml
ports:
  - "3001:3000"  # Change 3000 to 3001

Corrupted Metabase data:

# Remove Metabase volume
docker volume rm dango-metabase-my-analytics

# Restart (will reinitialize)
dango start

Insufficient memory:

# Increase Docker memory limit
# Docker Desktop → Settings → Resources → Memory
# Set to at least 4 GB

File Watcher Not Working¶

Symptom: CSV files change but don't auto-sync.

Check file watcher status:

dango status
# Look for: File Watcher ● Running

If stopped:

# Check .dango/project.yml
platform:
  file_watcher:
    enabled: true  # Should be true

# Restart platform
dango stop && dango start

Check watched patterns:

platform:
  file_watcher:
    patterns:
      - "*.csv"      # Ensure your file type is listed
      - "*.json"

Best Practices¶

1. Use Version Control¶

Initialize git after creating project:

dango init my-analytics
cd my-analytics

git init
git add .
git commit -m "Initial Dango project setup"

What's automatically gitignored:

.dlt/secrets.toml (credentials)
.env (environment variables)
data/warehouse.duckdb (database file)
dbt/target/ (compiled dbt files)
dbt/logs/ (dbt logs)

2. Document Your Project¶

Fill in project.yml metadata:

Purpose: Why does this project exist?
Stakeholders: Who uses this data?
SLA: When is data expected?
Limitations: Known issues or delays

Benefits:

Onboard new team members faster
Set clear expectations
Track project evolution

3. Start Small¶

Don't configure everything upfront:

# Initialize with minimal config
dango init my-analytics --skip-wizard

# Add sources incrementally
dango source add  # First source
dango sync
dango generate
dango run

# Add more sources as needed
dango source add  # Second source

4. Use Manual Configuration for Consistency¶

No Template Commands

Dango does not have template export or init --template commands. For multiple similar projects:

Create and configure first project fully

Copy .dango/ directory to new projects manually:

# Create new project
cd ~/projects/project-b
dango init .

# Copy configuration from template project
cp -r ~/projects/project-a/.dango/* .dango/

# Update project-specific settings
vim .dango/project.yml  # Change project name

5. Monitor Resource Usage¶

Check database size regularly:

dango db status

Clean up if needed:

# Remove orphaned tables
dango db clean

# Full database cleanup (careful!)
duckdb data/warehouse.duckdb "VACUUM;"

Next Steps¶

Sync & Run

Learn how to sync data and run transformations.

Source & Sync Guide
Source Management

Add and configure data sources via CLI.

Source & Sync
Validation

Validate configuration and troubleshoot issues.

Other Commands
CLI Reference

Complete reference for all CLI commands.

CLI Reference