Installation

BuildButler can be deployed via Docker, npm, or built from source.

System requirements

Component	Minimum	Recommended
CPU	2 cores	4 cores
Memory	2 GB	4 GB
Disk	10 GB	50 GB (depends on retention)
Node.js	18.x	20.x LTS
PostgreSQL	15	16

Docker (recommended)

# Pull the latest image
docker pull ghcr.io/buildbutler/buildbutler:latest
 
# Run with environment variables
docker run -d \
  --name buildbutler \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://user:pass@host:5432/buildbutler" \
  -e JENKINS_URL="https://jenkins.example.com" \
  -e JENKINS_TOKEN="your-api-token" \
  ghcr.io/buildbutler/buildbutler:latest

Docker Compose

For production deployments we recommend Docker Compose with the bundled PostgreSQL instance:

# docker-compose.yml
version: '3.8'
services:
  app:
    image: ghcr.io/buildbutler/buildbutler:latest
    ports:
      - '3000:3000'
    environment:
      DATABASE_URL: postgresql://bb:bb@db:5432/buildbutler
    depends_on:
      - db
 
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: bb
      POSTGRES_PASSWORD: bb
      POSTGRES_DB: buildbutler
    volumes:
      - pgdata:/var/lib/postgresql/data
 
volumes:
  pgdata:

npm

npm install -g @buildbutler/cli
 
# Initialise a new project
buildbutler init
 
# Start the server
buildbutler start

Build from source

git clone https://github.com/buildbutler/buildbutler.git
cd buildbutler
npm ci
npm run build
npm start

Upgrading

# Docker
docker pull ghcr.io/buildbutler/buildbutler:latest
docker compose up -d
 
# npm
npm update -g @buildbutler/cli

Migrations run automatically on startup. Check the changelog before upgrading major versions.