Installation

Pullbase consists of two components:

Central Server — Coordinates environments, monitors Git, serves the dashboard.
Agents — Run on each managed Linux server.

This guide covers deploying the Central Server. For installing agents on your servers, see Agent Operations.

Prerequisites

Docker (v24.0+) with Docker Compose
Git repository for your configuration
Database: SQLite (default) or PostgreSQL (production)

Choose Your Database

Pullbase supports two database backends. Choose the one that fits your needs:

Feature	SQLite (Default)	PostgreSQL (Recommended)
Best for	Testing, POCs, Small deployments	Production, High Availability
Setup	Zero configuration	Requires Postgres container/RDS
Storage	Single file on disk	External volume/service
Performance	Good for < 100 agents	Scales to thousands

Quick Start (SQLite)

The easiest way to get started is using the default SQLite database. This requires zero external dependencies and is perfect for testing.

Create docker-compose.yml

Create a file named docker-compose.yml with the following content:

docker-compose.yml

services:
  central-server:
    image: pullbaseio/pullbase:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      # Database
      - PULLBASE_DB_TYPE=sqlite
      - PULLBASE_DB_PATH=/data/pullbase.db
      # Security
      # ⚠️ IMPORTANT: Generate secure random strings for production use
      - PULLBASE_JWT_SECRET=change-this-to-a-secure-random-string
      - PULLBASE_WEBHOOK_SECRET_KEY=change-this-to-a-secure-random-string
      - PULLBASE_BOOTSTRAP_SECRET_FILE=/app/secrets/bootstrap.secret
      # Logging (optional)
      - PULLBASE_LOG_FORMAT=json   # json or text (default: text)
      - PULLBASE_LOG_LEVEL=info    # debug, info, warn, error (default: info)
    volumes:
      - pullbase_data:/data
      - pullbase_secrets:/app/secrets

volumes:
  pullbase_data:
  pullbase_secrets:

Start the server

docker compose up -d

Verify installation

Check if the server is running:

curl http://localhost:8080/api/v1/healthz
# Output: {"status":"ok"}

Bootstrap the Admin

You need to create your first admin user to access the UI. Follow the CLI Guide to bootstrap your admin account using the secret file.

Production Setup (PostgreSQL)

For production environments, we recommend using PostgreSQL for better performance, reliability, and concurrency.

Create docker-compose.yml

Use this configuration to spin up Pullbase with a dedicated PostgreSQL container.

docker-compose.yml

services:
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${PULLBASE_DB_USER:-pullbaseuser}
      POSTGRES_PASSWORD: ${PULLBASE_DB_PASSWORD}
      POSTGRES_DB: ${PULLBASE_DB_NAME:-pullbasedb}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5

  central-server:
    image: pullbaseio/pullbase:latest
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8080:8080"
    environment:
      # Database Connection
      - PULLBASE_DB_TYPE=postgres
      - PULLBASE_DB_HOST=db
      - PULLBASE_DB_PORT=5432
      - PULLBASE_DB_USER=pullbaseuser
      - PULLBASE_DB_NAME=pullbasedb
      # Security
      - PULLBASE_JWT_SECRET=${PULLBASE_JWT_SECRET}
      - PULLBASE_WEBHOOK_SECRET_KEY=${PULLBASE_WEBHOOK_SECRET_KEY}
      - PULLBASE_BOOTSTRAP_SECRET_FILE=/app/secrets/bootstrap.secret
      # Logging (optional)
      - PULLBASE_LOG_FORMAT=json   # json recommended for production
      - PULLBASE_LOG_LEVEL=info
    volumes:
      - pullbase_secrets:/app/secrets

volumes:
  postgres_data:
  pullbase_secrets:

Configure Secrets

Create a .env file to store your sensitive secrets. Do not commit this file to Git.

.env

PULLBASE_JWT_SECRET=generate-a-long-random-string-here
PULLBASE_WEBHOOK_SECRET_KEY=generate-another-random-string
PULLBASE_DB_PASSWORD=generate-a-secure-database-password

Start the stack

docker compose up -d

Next Steps

Now that your server is running:

Bootstrap the Admin to create your first user.
Login to the Dashboard at http://localhost:8080.
Secure your installation with TLS before going to production.

Foundations

Setup

Operations

Examples

Prerequisites

Choose Your Database

Quick Start (SQLite)

Production Setup (PostgreSQL)

Next Steps

​Prerequisites

​Choose Your Database

​Quick Start (SQLite)

​Production Setup (PostgreSQL)

​Next Steps

Prerequisites

Choose Your Database

Quick Start (SQLite)

Production Setup (PostgreSQL)

Next Steps