BlossomBot • Quickstart

Launch BlossomBot locally or in Docker in under 15 minutes.

This guide is tailored for the BlossomBot repo. It covers .env setup, Docker Compose, and local dev so you can start analyzing repos fast.

Docker GitHub App OpenRouter Postgres + Redis

What you need

Create a GitHub App and download the private key.

Create an OpenRouter API key.

Docker Desktop or local Node.js + PostgreSQL + Redis.

Step 1 — Create .env

Copy the template and fill in secrets:

cp .env.example .env

Required entries:

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
GITHUB_WEBHOOK_SECRET=your-webhook-secret
OPENROUTER_API_KEY=sk-or-v1-...

Private key tip: keep it in a single line with \n for newlines and wrap it in quotes.

Step 2 — Docker Compose

Start the full stack (API + worker + Postgres + Redis):

docker-compose up -d

Run migrations once:

docker-compose run --rm migrate

Check logs:

docker-compose logs -f api worker

Step 3 — Local Dev (optional)

If you prefer running without Docker:

npm install
npm run db:generate
cp .env.example .env
npm run db:migrate
npm run dev

In another terminal:

npm run worker:dev

Where to get your credentials

GitHub App: GitHub → Settings → Developer settings → GitHub Apps.

Generate a private key on the app page and download the .pem file.

Webhook secret: set in the app’s webhook settings.

OpenRouter key: create at the OpenRouter dashboard.

Docker .env defaults

These are optional because docker-compose sets defaults:

DB_PASSWORD=blossombot
OPENROUTER_MODEL=z-ai/glm-4.5-air:free
LOG_LEVEL=info
WORKER_CONCURRENCY=5
WORKER_REPLICAS=2

Common gotchas

Ensure the private key is a single line with \n escapes.

If Docker can’t start, verify Docker Desktop is running.

For webhook testing, use a reachable URL or a tunnel.