Quickstart

Get Bilanc self-hosted running in 5 minutes.

This guide will help you get a self-hosted Bilanc instance up and running quickly.

Prerequisites Checklist

Before you begin, ensure you have:

Docker and Docker Compose v2+ installed

Access to the Bilanc self-hosted Docker image

gcloud CLI installed and authenticated

A PostgreSQL database (or use the included container)

API keys for your AI provider (OpenAI, Anthropic, or Google AI)

GitHub Personal Access Token with repo and read:org scopes

Step 1: Authenticate with Docker Registry

gcloud auth configure-docker europe-west2-docker.pkg.dev

Step 2: Clone the Repository

Clone your Bilanc self-hosted configuration repository:

git clone <your-bilanc-config-repo>
cd bilanc-self-hosted

Contact your Bilanc representative if you don’t have access to the configuration repository.

Step 3: Configure Environment Variables

Create your environment file from the example:

cp .env.example .env

Edit the .env file with your configuration. At minimum, configure:

# Database
POSTGRES_HOST=your_postgres_host
POSTGRES_PORT=5432
POSTGRES_DATABASE=bilanc_db
POSTGRES_USERNAME=your_username
POSTGRES_PASSWORD=your_secure_password

# AI Provider (choose one)
AI_PROVIDER=openai
OPENAI_API_KEY=sk-...

# GitHub Integration
GITHUB_ACCESS_TOKEN=ghp_...
GITHUB_REPOSITORY=owner/repo-1 owner/repo-2

# Frontend URL
FRONTEND_URL=http://localhost:3000

See Configuration for the complete list of environment variables.

Step 4: Configure Your Tenant

Edit tenant_config.yaml with your organization details:

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}

See Configuration for more details on tenant setup.

Step 5: Start Bilanc

Build and start all containers:

make r

This command builds and starts all Docker containers in detached mode.

Use make up instead if you want to see logs in the foreground.

Step 6: Access the Application

Once the containers are running, access Bilanc at:

Service	URL
Dashboard	http://localhost:3000
API Server	http://localhost:8000
Dagster (Orchestrator)	http://localhost:4000

Verify the Installation

1. Open the Dashboard at http://localhost:3000
2. Authenticate with your configured auth provider
3. Check the Dagster UI at http://localhost:4000 to verify pipelines are running

Next Steps

Configuration

Complete environment variable reference

Integrations

Set up GitHub, Linear, and Cursor

Commands

Useful commands for managing Bilanc

Troubleshooting

Common issues and solutions