Skip to content

Installation & Setup

Get Dataface installed and configured in your environment.

Prerequisites

Before installing Dataface, ensure you have:

  • Python 3.9+ installed
  • dbt-core installed (version 1.5+ recommended)
  • dbt Semantic Layer configured (MetricFlow)
  • A dbt project with Semantic Layer metrics and dimensions defined

Installation

Install Dataface

pip install dataface

Verify Installation

face --version

You should see the Dataface version number.

Configuration

dbt Project Setup

Dataface works with your existing dbt project. Ensure you have:

  1. dbt project initialized: 

    dbt init my_project

  2. Semantic Layer configured in dbt_project.yml: 

    semantic-models:
  - name: orders
    # ... semantic model definition

metrics:
  - name: total_revenue
    # ... metric definition

  3. dbt profiles configured in ~/.dbt/profiles.yml: 

    my_project:
  outputs:
    dev:
      type: snowflake  # or your database adapter
      # ... connection details
  target: dev

Create Dashboards Directory

Create a directory for your dashboards:

mkdir dashboards

Place your dashboard YAML files in this directory.

Project Configuration (Optional)

Dataface supports project-wide configuration via a dataface.yml file in your project root. This allows you to set default values for dashboard rendering.

Create dataface.yml in your project root (same level as dbt_project.yml):

# Default board rendering settings
board:
  width: 1200.0      # Board width in pixels
  padding: 20.0      # Padding around boards
  row_gap: 20.0      # Gap between rows

Configuration Discovery: - Dataface automatically searches for dataface.yml starting from the current working directory - It walks up the directory tree until it finds the config file or reaches the filesystem root - If no config file is found, sensible defaults are used (1200px width, 20px padding) - If you're working in a dbt project, Dataface will also detect dbt_project.yml as a project root indicator

Settings: - board.width: Default board width in pixels (default: 1200.0) - board.padding: Default padding around boards in pixels (default: 20.0) - board.row_gap: Default gap between rows in pixels (default: 20.0) - board.col_gap: Default gap between columns in pixels (default: 20.0)

These settings apply to all dashboards in your project unless overridden in individual dashboard YAML files.

Verification

Test Installation

  1. Create a simple dashboard file dashboards/test.yml: 

    dashboard:
  name: test

  queries:
    test:
      metrics: [total_revenue]
      dimensions: [month]

  sections:
    - title: "Test"
      layout: row
      charts:
        test_chart:
          query: queries.test
          type: bar
          x: month
          y: total_revenue

  2. Validate the dashboard: 

    face validate dashboards/test.yml

  3. Preview the dashboard: 

    face serve dashboards/test.yml

  4. Open your browser to http://localhost:8080

If you see the dashboard, installation is successful!

Troubleshooting Common Issues

dbt Not Found

Error: dbt: command not found

Solution: Install dbt-core: 

pip install dbt-core

MetricFlow Not Available

Error: MetricFlow not found or semantic layer errors

Solution: Ensure MetricFlow is installed: 

pip install "dbt-core[metricflow]"

Or install separately: 

pip install metricflow

Database Connection Issues

Error: Cannot connect to database

Solution: - Check your profiles.yml configuration - Verify database credentials - Test dbt connection: dbt debug

YAML Syntax Errors

Error: YAML parsing errors

Solution: - Check YAML indentation (use spaces, not tabs) - Validate YAML syntax with a YAML validator - Use face validate to check for errors

Next Steps

Getting Help

If you encounter issues:

  1. Check the Troubleshooting Guide
  2. Validate your dashboard: face validate
  3. Check dbt configuration: dbt debug
  4. Review the Field Reference