Configuration

This guide covers all configuration options for your self-hosted Bilanc deployment, including environment variables, database setup, and tenant configuration.

Initial Setup

Create your environment file:
```
cp .env.example .env
```
Edit .env with your configuration values as described below.
Configure your tenant in tenant_config.yaml.

Environment Variables

Database Configuration

Bilanc requires a PostgreSQL database. Configure the connection details:

Variable	Description	Default	Example
`POSTGRES_HOST`	Hostname or IP of the PostgreSQL server	`db`	`db.example.com`
`POSTGRES_PORT`	Port number	`5432`	`5432`
`POSTGRES_DATABASE`	Database name	`bilanc`	`bilanc_prod`
`POSTGRES_USERNAME`	Database user	`bilanc`	`bilanc_user`
`POSTGRES_PASSWORD`	Database password	-	`secure_password`
`RAW_DATA_SCHEMA`	Schema for raw data storage	`bilanc`	`bilanc`

# Database Configuration
POSTGRES_HOST=your_postgres_host
POSTGRES_PORT=5432
POSTGRES_DATABASE=bilanc_db
POSTGRES_USERNAME=your_username
POSTGRES_PASSWORD=your_secure_password
RAW_DATA_SCHEMA=bilanc

AI Provider Configuration

Bilanc uses AI for generating insights. Choose one provider and configure its API key:

Variable	Description	Example
`AI_PROVIDER`	AI backend: `openai`, `anthropic`, or `google-ai`	`openai`
`AI_MODEL`	Specific model to use	`gpt-4o`
`OPENAI_API_KEY`	API key for OpenAI (if `AI_PROVIDER=openai`)	`sk-...`
`ANTHROPIC_API_KEY`	API key for Anthropic (if `AI_PROVIDER=anthropic`)	`sk-ant-...`
`GOOGLE_API_KEY`	API key for Google AI (if `AI_PROVIDER=google-ai`)	`AIza...`

Only set the API key corresponding to your chosen AI_PROVIDER.

# AI Configuration
AI_PROVIDER=openai
AI_MODEL=gpt-4o
OPENAI_API_KEY=sk-...

Integration Tokens

Configure tokens for the data sources you want to connect:

Variable	Description	Example
`GITHUB_ACCESS_TOKEN`	GitHub Personal Access Token with `repo` and `read:org` scopes	`ghp_...`
`GITHUB_REPOSITORY`	Space-separated list of repositories (`owner/name` format)	`org/repo-1 org/repo-2`
`LINEAR_ACCESS_TOKEN`	Linear API token	`lin_api_...`
`CURSOR_API_KEY`	Cursor API key	`cursor_...`

# Integration Tokens
GITHUB_ACCESS_TOKEN=ghp_abcdef1234567890
GITHUB_REPOSITORY=bilanc/frontend bilanc/backend bilanc/api
LINEAR_ACCESS_TOKEN=lin_api_xxxxx
CURSOR_API_KEY=cursor_xxxxx

See Integrations for detailed setup instructions for each integration.

Application Settings

Configure the frontend and application behavior:

Variable	Description	Example
`FRONTEND_URL`	Public URL of your Bilanc dashboard	`https://dashboard.yourdomain.com`
`NEXT_PUBLIC_API_URL`	API URL for the frontend	`http://host.docker.internal:8000`
`NEXT_PUBLIC_AUTH_URL`	Authentication provider URL	`https://auth.yourdomain.com`
`NEXT_PUBLIC_AUTH_API_KEY`	Authentication API key	`your_auth_api_key`
`ENVIRONMENT`	Environment name	`dev` or `production`

# Application Settings
FRONTEND_URL=https://dashboard.yourdomain.com
NEXT_PUBLIC_API_URL=http://host.docker.internal:8000
NEXT_PUBLIC_AUTH_URL=https://auth.yourdomain.com
NEXT_PUBLIC_AUTH_API_KEY=your_auth_api_key
ENVIRONMENT=production

Email Configuration

Bilanc uses Resend for sending emails:

Variable	Description	Example
`RESEND_API_KEY`	API key for Resend	`re_...`
`DEFAULT_SENDER_EMAIL`	From address for system emails	`notifications@yourdomain.com`

# Email Configuration
RESEND_API_KEY=re_1234567890abcdef
DEFAULT_SENDER_EMAIL=notifications@yourdomain.com

Internal Settings

These are typically left at their default values:

Variable	Description	Default
`DBT_PREFIX`	Prefix for dbt models	`marts`
`CELERY_BROKER_URL`	Redis URL for Celery	`redis://broker:6379/0`

# Internal Settings
DBT_PREFIX=marts
CELERY_BROKER_URL=redis://broker:6379/0

Complete `.env` Example

# ─── Database Configuration ───────────────────────────────────────────────
POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_DATABASE=bilanc
POSTGRES_USERNAME=bilanc
POSTGRES_PASSWORD=secure_password
RAW_DATA_SCHEMA=bilanc

# ─── AI Configuration ─────────────────────────────────────────────────────
AI_PROVIDER=openai
AI_MODEL=gpt-4o
OPENAI_API_KEY=sk-...

# ─── Integration Tokens ───────────────────────────────────────────────────
GITHUB_ACCESS_TOKEN=ghp_abcdef1234567890
GITHUB_REPOSITORY=bilanc/frontend bilanc/backend
LINEAR_ACCESS_TOKEN=lin_api_xxxxx
CURSOR_API_KEY=cursor_xxxxx

# ─── Application Settings ─────────────────────────────────────────────────
FRONTEND_URL=https://dashboard.yourdomain.com
NEXT_PUBLIC_API_URL=http://host.docker.internal:8000
NEXT_PUBLIC_AUTH_URL=https://auth.yourdomain.com
NEXT_PUBLIC_AUTH_API_KEY=your_auth_api_key
ENVIRONMENT=production

# ─── Email Configuration ──────────────────────────────────────────────────
RESEND_API_KEY=re_1234567890abcdef
DEFAULT_SENDER_EMAIL=notifications@yourdomain.com

# ─── Internal Settings ────────────────────────────────────────────────────
DBT_PREFIX=marts
CELERY_BROKER_URL=redis://broker:6379/0

Target Configuration

The target_config.yaml file configures database connections for data transformation:

postgres:
  postgres_db:
    username: !ENV ${POSTGRES_USERNAME}
    password: !ENV ${POSTGRES_PASSWORD}
    hostname: !ENV ${POSTGRES_HOST}
    db_name:  !ENV ${POSTGRES_DATABASE}
    schema:   !ENV ${RAW_DATA_SCHEMA}
    port:     !ENV ${POSTGRES_PORT}

This configuration uses environment variables from your .env file for consistency.

Tenant Configuration

The tenant_config.yaml file defines your organization and data source connections (called “taps”).

Basic Structure

tenants:
  - name: Your Organization Name
    domain: yourdomain.com
    is_auto_onboarding_enabled: true
    taps:
      # Data source configurations go here

Field	Description
`name`	Your organization’s display name
`domain`	Your organization’s email domain (used for auto-onboarding)
`is_auto_onboarding_enabled`	Automatically onboard users with matching email domain
`taps`	List of data source integrations

Tap Configuration

Each tap represents a data source integration:

taps:
  - name: github
    type: tap-github
    config:
      start_date: 2025-01-01
      repository: !ENV ${GITHUB_REPOSITORY}
  
  - name: linear
    type: tap-linear
    config:
      start_date: 2025-01-01
  
  - name: cursor
    type: tap-cursor
    config:
      start_date: 2025-01-01

Field	Description
`name`	Identifier for this tap instance
`type`	Tap type: `tap-github`, `tap-linear`, or `tap-cursor`
`config.start_date`	Date to start collecting data from (YYYY-MM-DD)
`config.repository`	(GitHub only) Repository list from environment variable

Complete Tenant Configuration Example

tenants:
  - name: Acme Corporation
    domain: acme.com
    is_auto_onboarding_enabled: true
    taps:
      - name: github
        type: tap-github
        config:
          start_date: 2025-01-01
          repository: !ENV ${GITHUB_REPOSITORY}
      - name: linear
        type: tap-linear
        config:
          start_date: 2025-01-01
      - name: cursor
        type: tap-cursor
        config:
          start_date: 2025-01-01

The start_date determines how far back Bilanc will fetch historical data. Setting an earlier date will result in more data but longer initial sync times.

Get Started

Guides

Initial Setup

Environment Variables

Database Configuration

AI Provider Configuration

Integration Tokens

Application Settings

Email Configuration

Internal Settings

Complete `.env` Example

Target Configuration

Tenant Configuration

Basic Structure

Tap Configuration

Complete Tenant Configuration Example

Next Steps

Integrations

Commands

Get Started

Guides

​Initial Setup

​Environment Variables

​Database Configuration

​AI Provider Configuration

​Integration Tokens

​Application Settings

​Email Configuration

​Internal Settings

​Complete .env Example

​Target Configuration

​Tenant Configuration

​Basic Structure

​Tap Configuration

​Complete Tenant Configuration Example

​Next Steps

Integrations

Commands

Initial Setup

Environment Variables

Database Configuration

AI Provider Configuration

Integration Tokens

Application Settings

Email Configuration

Internal Settings

Complete `.env` Example

Target Configuration

Tenant Configuration

Basic Structure

Tap Configuration

Complete Tenant Configuration Example

Next Steps