Project Deployment

Deploy compiled Lightdash projects to production or create new projects.

Capabilities

Deploy

Compiles and deploys a Lightdash project to the active project or creates a new project.

lightdash deploy [options]

Inherits all compilation options (see dbt Compilation), plus:

Project Creation:

• --create [project_name] - Create new project (optional name; prompts if not provided in interactive mode)

Deployment Options:

• --ignore-errors - Deploy even with compilation errors (default: false)
• --start-of-week <number> - First day of week for date functions: 0 (Monday) to 6 (Sunday)
• --skip-dbt-compile - Skip dbt compile and deploy from existing ./target/manifest.json (default: false)
• --skip-warehouse-catalog - Skip fetch warehouse catalog and use types in yml (default: false)
• --use-dbt-list [true|false] - Use dbt list instead of dbt compile to generate manifest (default: true)
• --disable-timestamp-conversion [true|false] - Disable timestamp conversion to UTC for Snowflake warehouses (default: false)
• --no-warehouse-credentials - Create project without warehouse credentials (skips dbt compile and warehouse catalog)
• --organization-credentials <name> - Use organization warehouse credentials with specified name (Enterprise Edition feature)

Usage Examples:

# Deploy to active project
lightdash deploy

# Deploy with model selection
lightdash deploy --select tag:production

# Create new project (interactive name prompt)
lightdash deploy --create

# Create new project with name
lightdash deploy --create "Production Analytics"

# Deploy with errors (force deployment)
lightdash deploy --ignore-errors

# Deploy with start of week setting
lightdash deploy --start-of-week 0  # Monday

# Deploy using dbt list (faster)
lightdash deploy --use-dbt-list true

# Deploy without warehouse credentials
lightdash deploy --no-warehouse-credentials

# Deploy with organization credentials
lightdash deploy --organization-credentials "prod-warehouse"

# Deploy with custom dbt directories
lightdash deploy --project-dir ./dbt --profiles-dir ./profiles

# CI/CD: Deploy with environment variables
export CI=true
export LIGHTDASH_API_KEY="token"
export LIGHTDASH_PROJECT="project-uuid"
lightdash deploy

Deployment Process

Standard Deployment (Existing Project)

1. Validate Authentication - Check logged in with valid credentials
2. Validate Project - Ensure active project is set
3. Compile Project - Run compilation (see dbt Compilation)
4. Upload Explores - Send compiled explores to Lightdash API
5. Trigger Refresh - Lightdash processes explores
6. Report Success - Display deployment summary

Create New Project

With --create flag:

1. Prompt for Name - If name not provided (interactive mode only)
2. Compile Project - Run compilation
3. Create Project - Call Lightdash API to create project
4. Upload Explores - Send compiled explores
5. Set as Active - Save new project as active project
6. Report Success - Display project URL and UUID

Deployment Modes

Deploy to Active Project

Default behavior without --create:

# Requires: login and set-project completed
lightdash deploy

Prerequisites:

• Authenticated (lightdash login)
• Active project selected (lightdash config set-project)

Result:

• Updates existing project with new explores
• Preserves charts, dashboards, and content

Create New Project

With --create flag:

# Interactive mode: prompts for name
lightdash deploy --create

# Non-interactive: provide name
lightdash deploy --create "My New Project"

# CI mode: uses default name if not provided
export CI=true
lightdash deploy --create

Result:

• Creates new Lightdash project
• Uploads explores to new project
• Sets as active project for future commands

Note: Requires permission to create projects in organization.

Compilation Options

Deploy inherits all compilation options. Common patterns:

Model Selection

# Deploy only production models
lightdash deploy --select tag:production

# Deploy specific models
lightdash deploy --select customers orders

# Deploy excluding test models
lightdash deploy --exclude test_*

Fast Deployment

# Skip warehouse catalog (faster)
lightdash deploy --skip-warehouse-catalog

# Use existing manifest
lightdash deploy --skip-dbt-compile

# Skip both (fastest, for CI/CD)
lightdash deploy --no-warehouse-credentials

Warehouse Configuration

# Custom dbt directories
lightdash deploy --project-dir ./dbt --profiles-dir ./profiles

# Custom target
lightdash deploy --target production

# dbt variables
lightdash deploy --vars '{"env": "prod"}'

Error Handling

Ignore Compilation Errors

By default, deployment fails if compilation has errors:

# Default: fail on errors
lightdash deploy
# Error: Compilation failed - deployment aborted

Use --ignore-errors to deploy anyway:

# Force deployment despite errors
lightdash deploy --ignore-errors
# Warning: Compilation had errors but deployment proceeding

When to use --ignore-errors:

• Some models have known issues but others are valid
• Want to deploy partial project
• Testing in development environment

Risks:

• Invalid explores may cause issues in Lightdash
• Charts using broken models will fail
• Users may see incomplete or incorrect data

Best practice: Fix errors rather than ignoring them.

Start of Week Configuration

Controls first day of week for week-related date functions:

--start-of-week <number>

Values:

• 0 - Monday
• 1 - Tuesday
• 2 - Wednesday
• 3 - Thursday
• 4 - Friday
• 5 - Saturday
• 6 - Sunday

Usage:

# Set Monday as first day of week
lightdash deploy --start-of-week 0

# Set Sunday as first day of week
lightdash deploy --start-of-week 6

Affects:

• Week truncation functions
• Week-based metrics and dimensions
• Calendar displays in Lightdash UI

Default: If not specified, uses warehouse default or organization setting.

dbt List vs dbt Compile

dbt list (Default)

# Uses dbt list (faster)
lightdash deploy --use-dbt-list true

Behavior:

• Runs dbt list to identify models
• Skips full SQL compilation
• Faster than full compile

Advantages:

• Faster for large projects
• Reduced dbt execution time
• Sufficient for most deployments

dbt compile

# Uses dbt compile (thorough)
lightdash deploy --use-dbt-list false

Behavior:

• Runs full dbt compile
• Compiles all SQL
• Validates SQL correctness

When to use:

• Need full SQL validation
• Debugging SQL issues
• First deployment of project

Organization Credentials

Enterprise Edition feature for using shared warehouse credentials:

--organization-credentials <name>

Usage:

# Use org credentials named "production-warehouse"
lightdash deploy --organization-credentials "production-warehouse"

Benefits:

• Centralized credential management
• No need for individual warehouse access
• Audit trail for warehouse usage
• Easier credential rotation

Requirements:

• Lightdash Enterprise Edition
• Organization admin must configure credentials
• User must have permission to use credentials

CI/CD Integration

Environment Setup

# Set authentication
export LIGHTDASH_API_KEY="your-service-account-token"
export LIGHTDASH_URL="https://app.lightdash.cloud"
export LIGHTDASH_PROJECT="project-uuid"

# Enable non-interactive mode
export CI=true

# Optional: dbt configuration
export DBT_PROJECT_DIR="./dbt"
export DBT_PROFILES_DIR="./profiles"

Deployment Script

#!/bin/bash
set -e

# Authenticate (token from environment)
echo "Deploying to Lightdash..."

# Deploy without warehouse credentials (CI/CD)
lightdash deploy \
  --no-warehouse-credentials \
  --ignore-errors \
  --start-of-week 0

echo "Deployment complete!"

GitHub Actions Example

name: Deploy to Lightdash

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install Lightdash CLI
        run: npm install -g @lightdash/cli

      - name: Deploy
        env:
          LIGHTDASH_API_KEY: ${{ secrets.LIGHTDASH_API_KEY }}
          LIGHTDASH_PROJECT: ${{ secrets.LIGHTDASH_PROJECT }}
          CI: true
        run: lightdash deploy --no-warehouse-credentials

Deployment Validation

Pre-Deployment Checks

# 1. Validate compilation locally
lightdash compile --verbose

# 2. Check for errors
echo $?  # Should be 0

# 3. Deploy
lightdash deploy

Post-Deployment Validation

# Validate deployed project
lightdash validate --project project-uuid

# Check specific elements
lightdash validate --only tables charts

Permission Requirements

Deploy to Existing Project

Required permissions:

• Developer or Admin role on project
• Access to project

Create New Project

Required permissions:

• Organization Member with project creation permission
• Or Organization Admin role

Error if insufficient permissions:

ForbiddenError: You don't have permission to create projects

Solution: Contact organization admin for permission.

Return Values

Exit Code 0: Deployment succeeded Exit Code 1: Deployment failed

Success Output:

✓ Compiled N models
✓ Deployed N explores
✓ Project URL: https://app.lightdash.cloud/projects/abc-123

Error Output:

✗ Deployment failed: [error message]

Troubleshooting

Authentication Errors

Error: "AuthorizationError"

• Not logged in or token expired
• Solution: lightdash login

Project Not Found

Error: "No active project set"

• Solution: lightdash config set-project

Compilation Errors

Error: "Compilation failed"

• Check dbt model SQL
• Use --verbose for details
• Or use --ignore-errors to deploy anyway

Permission Errors

Error: "ForbiddenError"

• Insufficient permissions
• Solution: Contact organization admin

Warehouse Connection Errors

Error: "Could not connect to warehouse"

• Check profiles.yml credentials
• Or use --no-warehouse-credentials for CI/CD

Best Practices

1. Use Version Control

Commit dbt models and YAML before deploying:

git add models/ dbt_project.yml
git commit -m "Update models"
git push
lightdash deploy

2. Test in Preview First

Test changes in preview before deploying to production:

# Create preview
lightdash preview --name test-feature

# Validate preview
lightdash validate --preview

# If good, deploy to production
lightdash deploy

3. Use Tags for Selective Deployment

Tag production-ready models:

# dbt_project.yml
models:
  my_project:
    marts:
      +tags: ["production"]

Deploy only production models:

lightdash deploy --select tag:production

4. Automate in CI/CD

Deploy automatically on merge to main:

# .github/workflows/deploy.yml
on:
  push:
    branches: [main]

jobs:
  deploy:
    steps:
      - run: lightdash deploy --no-warehouse-credentials

5. Monitor Deployments

Track deployment success:

# Deploy with verbose output
lightdash deploy --verbose 2>&1 | tee deploy.log

# Check exit code
if [ $? -eq 0 ]; then
  echo "Deployment successful"
else
  echo "Deployment failed"
  exit 1
fi