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:

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:

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:

make recompose

Ensure the custom files exist in your repository’s dbt_project/ directory before mounting.

---

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:

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:

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:

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

Custom models must be compatible with Bilanc’s schema. Contact support for guidance on model development.

---

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:

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

Each tenant requires separate API tokens for their integrations.

---

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:

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:

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:

FRONTEND_URL=https://dashboard.yourdomain.com

---

Backup and Recovery

Database Backups

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

For local PostgreSQL:

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

All file mounts must be applied to both Dagster containers (daemon and webserver)

Ensure proper file permissions are maintained during mounting

Restart containers after applying configuration changes

Verify mounted files are accessible at their target paths before proceeding

---

Getting Help

For advanced configuration assistance, contact Bilanc support at [e-mail].