Configuration

Complete guide to configuring your self-hosted Bilanc instance.

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

Initial Setup

1. Create your environment file:

   cp .env.example .env
   

2. Edit .env with your configuration values as described below.

3. 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	[e-mail]

# Email Configuration
RESEND_API_KEY=re_1234567890abcdef
DEFAULT_SENDER_EMAIL=[e-mail]

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=[e-mail]

# ─── 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.

---

Next Steps

Integrations

Detailed setup for each integration

Commands

Run and manage your Bilanc instance