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:
-
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}
.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
