> ## Documentation Index
> Fetch the complete documentation index at: https://bilanc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**:
   ```bash theme={null}
   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`          |

```bash theme={null}
# 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...`    |

<Warning>
  Only set the API key corresponding to your chosen `AI_PROVIDER`.
</Warning>

```bash theme={null}
# 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_...`            |

```bash theme={null}
# 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
```

<Note>
  See [Integrations](/self-hosting/integrations) for detailed setup instructions for each integration.
</Note>

### 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`              |

```bash theme={null}
# 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](https://resend.com) 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` |

```bash theme={null}
# 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` |

```bash theme={null}
# Internal Settings
DBT_PREFIX=marts
CELERY_BROKER_URL=redis://broker:6379/0
```

***

## Complete `.env` Example

```bash theme={null}
# ─── 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:

```yaml theme={null}
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

```yaml theme={null}
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:

```yaml theme={null}
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

```yaml theme={null}
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
```

<Tip>
  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.
</Tip>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Integrations" icon="plug" href="/self-hosting/integrations">
    Detailed setup for each integration
  </Card>

  <Card title="Commands" icon="terminal" href="/self-hosting/commands">
    Run and manage your Bilanc instance
  </Card>
</CardGroup>