Skip to main content
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:
ServiceURL
Dashboardhttp://localhost:3000
API Serverhttp://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