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

# Advanced Configuration

> Advanced configuration options for self-hosted Bilanc.

This guide covers advanced configuration scenarios for self-hosted Bilanc, including disabling integrations and customizing data transformations.

## Disabling Linear Integration

If your organization doesn't use Linear, you can disable the integration to avoid unnecessary pipeline runs and errors.

### Step 1: Update Tenant Configuration

Remove the Linear configuration section from `tenant_config.yaml`:

```yaml theme={null}
tenants:
  - name: Your Organization Name
    domain: yourdomain.com
    is_auto_onboarding_enabled: true
    taps:
      - name: github
        type: tap-github
        config:
          start_date: 2025-01-01
          repository: !ENV ${GITHUB_REPOSITORY}
      # Remove or comment out the linear tap:
      # - name: linear
      #   type: tap-linear
      #   config:
      #     start_date: 2025-01-01
      - name: cursor
        type: tap-cursor
        config:
          start_date: 2025-01-01
```

### Step 2: Mount Custom dbt Scripts

To fully disable Linear, you need to mount custom dbt scripts that exclude Linear models.

Add these volume mounts to **both** Dagster containers in your `docker-compose.yml`:

```yaml theme={null}
services:
  dagster_daemon:
    # ... existing config ...
    volumes:
      - ./dbt_project/dbt_run_exclude_linear.sh:/app/dbt_project/dbt_run.sh
      - ./dbt_project/models/marts/raw_users.sql:/app/dbt_project/models/marts/raw_users.sql

  dagster_webserver:
    # ... existing config ...
    volumes:
      - ./dbt_project/dbt_run_exclude_linear.sh:/app/dbt_project/dbt_run.sh
      - ./dbt_project/models/marts/raw_users.sql:/app/dbt_project/models/marts/raw_users.sql
```

### Step 3: Restart Containers

Apply the changes:

```bash theme={null}
make recompose
```

<Warning>
  Ensure the custom files exist in your repository's `dbt_project/` directory before mounting.
</Warning>

***

## Release Alternative Configuration

Bilanc supports an alternative release implementation for organizations with non-standard release workflows.

### When to Use

Use the alternative release configuration if:

* Your release process doesn't follow conventional patterns
* You need custom release detection logic
* Standard release metrics aren't capturing your workflow

### Step 1: Mount Alternative dbt Scripts

Add these volume mounts to **both** Dagster containers in your `docker-compose.yml`:

```yaml theme={null}
services:
  dagster_daemon:
    # ... existing config ...
    volumes:
      - ./dbt_project/dbt_run_releases_alt.sh:/app/dbt_project/dbt_run.sh
      - ./dbt_project/models/marts/release_details_alternative.sql:/app/dbt_project/models/marts/release_details.sql

  dagster_webserver:
    # ... existing config ...
    volumes:
      - ./dbt_project/dbt_run_releases_alt.sh:/app/dbt_project/dbt_run.sh
      - ./dbt_project/models/marts/release_details_alternative.sql:/app/dbt_project/models/marts/release_details.sql
```

### Step 2: Restart Containers

Apply the changes:

```bash theme={null}
make recompose
```

***

## Custom dbt Model Mounting

For advanced customization, you can mount custom dbt models to modify how data is transformed.

### Understanding the dbt Structure

Bilanc uses dbt for data transformation with this structure:

```
dbt_project/
├── dbt_run.sh              # Main transformation script
├── models/
│   └── marts/
│       ├── raw_users.sql    # User data model
│       ├── release_details.sql
│       └── ... other models
```

### Mounting Custom Models

1. Create your custom SQL model in your local `dbt_project/models/marts/` directory
2. Add volume mounts in `docker-compose.yml`:

```yaml theme={null}
services:
  dagster_daemon:
    volumes:
      - ./dbt_project/models/marts/your_custom_model.sql:/app/dbt_project/models/marts/your_custom_model.sql

  dagster_webserver:
    volumes:
      - ./dbt_project/models/marts/your_custom_model.sql:/app/dbt_project/models/marts/your_custom_model.sql
```

<Note>
  Custom models must be compatible with Bilanc's schema. Contact support for guidance on model development.
</Note>

***

## Multiple Tenants

Bilanc supports multiple tenants in a single deployment, useful for:

* Managed service providers
* Large organizations with separate business units
* Development/staging/production environments

### Configuration

Add multiple tenant entries to `tenant_config.yaml`:

```yaml theme={null}
tenants:
  - name: Team Alpha
    domain: alpha.company.com
    is_auto_onboarding_enabled: true
    taps:
      - name: github
        type: tap-github
        config:
          start_date: 2025-01-01
          repository: company/alpha-repo-1 company/alpha-repo-2

  - name: Team Beta
    domain: beta.company.com
    is_auto_onboarding_enabled: true
    taps:
      - name: github
        type: tap-github
        config:
          start_date: 2025-01-01
          repository: company/beta-repo-1 company/beta-repo-2
```

<Warning>
  Each tenant requires separate API tokens for their integrations.
</Warning>

***

## External PostgreSQL

For production deployments, we recommend using an external managed PostgreSQL instance.

### Recommended Providers

| Provider | Service                       |
| -------- | ----------------------------- |
| AWS      | RDS PostgreSQL                |
| GCP      | Cloud SQL                     |
| Azure    | Azure Database for PostgreSQL |
| Other    | Any PostgreSQL 14+            |

### Configuration

Update your `.env` file with the external database details:

```bash theme={null}
POSTGRES_HOST=your-rds-instance.region.rds.amazonaws.com
POSTGRES_PORT=5432
POSTGRES_DATABASE=bilanc
POSTGRES_USERNAME=bilanc_user
POSTGRES_PASSWORD=secure_password
```

### Recommended Specifications

| Metric  | Minimum | Recommended |
| ------- | ------- | ----------- |
| vCPUs   | 2       | 4           |
| RAM     | 8GB     | 16GB        |
| Storage | 100GB   | 250GB       |
| IOPS    | 3000    | 6000        |

***

## SSL/TLS Configuration

For production deployments, configure SSL/TLS for secure connections.

### Reverse Proxy Setup

Use a reverse proxy (nginx, Traefik, Caddy) in front of Bilanc services:

```nginx theme={null}
server {
    listen 443 ssl;
    server_name dashboard.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### Update Environment Variables

Update `FRONTEND_URL` to use HTTPS:

```bash theme={null}
FRONTEND_URL=https://dashboard.yourdomain.com
```

***

## Backup and Recovery

### Database Backups

For external PostgreSQL, use your provider's backup features.

For local PostgreSQL:

```bash theme={null}
# Create a backup
docker compose exec db pg_dump -U bilanc bilanc > backup.sql

# Restore from backup
docker compose exec -T db psql -U bilanc bilanc < backup.sql
```

### Configuration Backups

Keep these files in version control:

* `.env` (with secrets in a secure vault)
* `tenant_config.yaml`
* `target_config.yaml`
* `docker-compose.yml` (if customized)

***

## Important Notes

When modifying Dagster containers:

<Check>All file mounts must be applied to **both** Dagster containers (daemon and webserver)</Check>
<Check>Ensure proper file permissions are maintained during mounting</Check>
<Check>Restart containers after applying configuration changes</Check>
<Check>Verify mounted files are accessible at their target paths before proceeding</Check>

***

## Getting Help

For advanced configuration assistance, contact Bilanc support at [support@bilanc.co](mailto:support@bilanc.co).