Setup

Setup Your Environment

Get your Daana CLI environment up and running.

Want to learn with sample data? Use the Tutorial instead - it includes a complete example dataset.

Overview

You'll set up three things:

  1. Daana CLI - Download the binary for your platform
  2. Databases - PostgreSQL containers for Daana's internal state and your data warehouse
  3. Daana Framework - Install the transformation engine

Step 1: Download Daana CLI

For Beta Testers

The Daana team will provide you with a direct download link for the binary. Once you have the binary:

# macOS/Linux: Extract and move to PATH
tar -xzf daana-cli_*_<OS>_<ARCH>.tar.gz
sudo mv daana-cli /usr/local/bin/
 
# Verify installation
daana-cli --version

Note: If you don't have the download link yet, contact your Daana representative. The repository is private during beta.

✅ Checkpoint: You should see version information (e.g., v0.5.15 or later)

For Contributors

If you're building from source:

git clone --recurse-submodules https://github.com/daana-code/daana-cli.git
cd daana-cli
task setup
task build

Step 2: Create Your Project

# Create a new project
daana-cli init my-project
cd my-project

This creates a project with:

  • model.yaml - Data model template (you'll define your entities here)
  • workflow.yaml - Workflow configuration
  • connections.yaml - Database connection profiles
  • docker-compose.yml - Local PostgreSQL databases
  • mappings/ - Directory for entity mapping files

✅ Checkpoint: You should see a new my-project/ directory with the files above

Step 3: Start Databases

Daana CLI uses two PostgreSQL databases:

  • internaldb (port 5434): Daana's internal database - stores your models, mappings, and workflows
  • customerdb (port 5432): Your data warehouse - contains source data and transformed business entities
docker-compose up -d
 
# Wait ~30 seconds for databases to start
docker-compose ps
 
# You should see 2 containers running:
#   daana-customerdb (port 5432)
#   daana-internaldb (port 5434)

✅ Checkpoint: Run docker ps - you should see 2 containers running

Step 4: Install Daana Framework

Install the Daana transformation framework into both databases:

daana-cli install

This command:

  • ✅ Installs Daana framework tables in internaldb (port 5434)
  • ✅ Installs transformation infrastructure in customerdb (port 5432)

✅ Checkpoint: Installation completes without errors

Step 5: Configure Your Data Source

Edit connections.yaml to point to your data warehouse:

profiles:
  dev:
    type: postgres
    host: localhost
    port: 5432
    database: customerdb
    username: dev
    password: ${DB_PASSWORD}  # Use environment variables in production
    schema: stage             # Where your source data lives

Tip: Your source data should be in a schema (e.g., stage) that Daana can read from. Transformed data will be written to the daana_dw schema.

What You Have Now

🎉 Success! You now have:

  • ✅ Daana CLI installed and working
  • ✅ Two databases running:
    • internaldb (port 5434): Daana's internal database
    • customerdb (port 5432): Your data warehouse
  • ✅ Daana framework installed in both databases
  • ✅ Project structure ready for your model and mappings

Next Steps

  1. Define your model in model.yaml - see DMDL Model Guide
  2. Generate mappings with daana-cli generate mapping
  3. Deploy and execute with daana-cli deploy and daana-cli execute

Or, to learn with sample data first, check out the Tutorial →

Understanding the Architecture

Why Two Databases?

  • internaldb (Daana's brain): Stores your blueprints (models, mappings, workflows). When you run daana-cli materialize model, it goes here.

  • customerdb (Your warehouse): This is where the magic happens:

    • Source data lives in stage schema
    • Transformed data goes in the daana_dw schema
    • Your BI tools will query daana_dw tables

You configure both databases in connections.yaml and select which profile to use (e.g., dev, prod) when running commands.

Troubleshooting

"Cannot connect to Docker daemon"

Make sure Docker Desktop is running:

  • macOS: Check menu bar for Docker icon
  • Windows: Check system tray for Docker icon
  • Linux: Run sudo systemctl start docker

"Port already in use"

If ports 5432 or 5434 are already in use:

# Check what's using the ports
lsof -i :5432
lsof -i :5434
 
# Stop any existing PostgreSQL
# macOS: brew services stop postgresql
# Linux: sudo systemctl stop postgresql

Installation fails with "connection refused"

Wait a bit longer for databases to start:

# Check if databases are ready
docker logs daana-internaldb
docker logs daana-customerdb
 
# Look for: "database system is ready to accept connections"

Installation fails

If installation fails, restart the databases:

docker-compose down -v
docker-compose up -d
 
# Wait ~30 seconds, then try again
daana-cli install

Need Help?

PrerequisitesOverview