​
1. Prerequisites

  • Docker & Docker Compose installed (v2+ recommended)
  • Terminal access to your Bilanc project directory
  • API keys for your chosen AI provider, email service, and GitHub

​
2. Initial Setup

  1. Clone the repository (if you haven’t already): 
    git clone https://github.com/bilanc/bilanc.git
cd bilanc
  2. Copy the example env file: 
    cp .env.example .env
  3. Edit .env and fill in the values as described below.

​
3. Environment Variables

​
A. AI Provider

VariableDescriptionExample
AI_PROVIDERChoose your AI backend: openai (default), anthropic, or google-ai.openai
OPENAI_API_KEYAPI key for OpenAI models (required if AI_PROVIDER=openai).sk-...
ANTHROPIC_API_KEYAPI key for Anthropic (Claude) (required if AI_PROVIDER=anthropic).env-...
GOOGLE_API_KEYAPI key for Google Gemini (required if AI_PROVIDER=google-ai).AIza...
Only set the API key corresponding to your chosen AI_PROVIDER.

​
B. Email Service

VariableDescriptionExample
DEFAULT_SENDER_EMAILFrom address for system-generated emailsno-reply@yourdomain.com
RESEND_API_KEYAPI key for Resend (email delivery service)re_1234567890abcdef

​
C. Frontend (Dashboard)

VariableDescriptionExample
FRONTEND_URLPublic URL of your Bilanc dashboard (used in email links)https://dashboard.yourdomain.com

​
D. Database (PostgreSQL)

Bilanc includes a Postgres container by default. To connect to an external DB, override these:
VariableDescriptionDefaultExample
POSTGRES_HOSTHostname or IP of the Postgresdbdb.example.com
POSTGRES_PORTPort number54325432
POSTGRES_DATABASEDatabase namebilancbilanc_prod
POSTGRES_USERNAMEDatabase userbilancbilanc_user
POSTGRES_PASSWORDDatabase password—secure_password

​
E. GitHub Integration

VariableDescriptionExample
GITHUB_ACCESS_TOKENGitHub Personal Access Token with repo and read:org scopesghp_abcdef1234567890
GITHUB_REPOSITORIESSpace‑separated list of repos to track (format: owner/name)bilanc/bilanc-frontend bilanc/bilanc-backend

​
4. Example .env Template

# ─── AI Configuration ─────────────────────────────────────────────────────
AI_PROVIDER=openai
OPENAI_API_KEY=sk-...

# ─── Email Configuration ──────────────────────────────────────────────────
DEFAULT_SENDER_EMAIL=no-reply@yourdomain.com
RESEND_API_KEY=re_123456...

# ─── Dashboard ───────────────────────────────────────────────────────────
FRONTEND_URL=https://dashboard.yourdomain.com

# ─── PostgreSQL ──────────────────────────────────────────────────────────
POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_DATABASE=bilanc
POSTGRES_USERNAME=bilanc
POSTGRES_PASSWORD=secure_password

# ─── GitHub Integration ─────────────────────────────────────────────────
GITHUB_ACCESS_TOKEN=ghp_abcdef1234567890
GITHUB_REPOSITORIES="bilanc/bilanc-frontend bilanc/bilanc-backend"

​
5. Running Bilanc

docker compose up
Once up, the services are available at:

​
6. Next Steps

  • Open your dashboard at FRONTEND_URL and authenticate via GitHub.
  • Configure or switch AI providers by updating AI_PROVIDER in .env.
  • For production deployments, point PostgreSQL to a managed database and lock down your env file.
You’re all set—enjoy full self‑hosted Bilanc!