Bare-Metal Deployment

Deploy Pullbase without containers by running the server and agent binaries directly with systemd. This is the recommended approach for production Linux servers.

Prerequisites

Ubuntu 22.04+, Debian 12, Rocky Linux 9, or a similar systemd-based distribution
curl and openssl
(Production) Reverse proxy for TLS termination or certificates for native TLS

Database: Pullbase uses SQLite by default — no external database required. For high-availability deployments, PostgreSQL 15+ is recommended.

Configure the server

Create a directory for configuration:

sudo mkdir -p /etc/pullbase
sudo mkdir -p /var/lib/pullbase/git-repos

Install the server

Download the server binary

Download the latest release with the web UI embedded:

curl -fsSL -o pullbase-server "https://github.com/pullbase/pullbase/releases/latest/download/pullbase-server-linux-amd64"
sudo install -m 0755 pullbase-server /usr/local/bin/pullbase-server

For ARM64 systems, use pullbase-server-linux-arm64.

Download pullbasectl

The CLI tool is used for bootstrapping, managing servers, and automation:

curl -fsSL -o pullbasectl "https://github.com/pullbase/pullbase/releases/latest/download/pullbasectl-linux-amd64"
sudo install -m 0755 pullbasectl /usr/local/bin/pullbasectl

For ARM64 systems, use pullbasectl-linux-arm64.Verify the installation:

pullbasectl --help

Download migrations

curl -fsSL "https://github.com/pullbase/pullbase/releases/latest/download/migrations.tar.gz" | sudo tar -xzf - -C /var/lib/pullbase/

Create an environment file with secrets and connection details:

cat <<EOF | sudo tee /etc/pullbase/pullbase.env
# Database configuration (SQLite is default — no setup required)
PULLBASE_DB_TYPE=sqlite
PULLBASE_DB_PATH=/var/lib/pullbase/pullbase.db

# Server configuration
PULLBASE_SERVER_PORT=8080
PULLBASE_SERVER_HOST=0.0.0.0

# Authentication
PULLBASE_JWT_SECRET=$(openssl rand -hex 32)
PULLBASE_JWT_EXPIRY_HOURS=24

# Webhooks
PULLBASE_WEBHOOK_SECRET_KEY=$(openssl rand -hex 32)

# Git integration (set to true when configuring GitHub App)
PULLBASE_GIT_ENABLED=false
PULLBASE_GIT_CLONE_PATH=/var/lib/pullbase/git-repos
PULLBASE_GIT_POLL_INTERVAL=60

# GitHub App (when using private repos)
# PULLBASE_GITHUB_APP_ID=your-app-id
# PULLBASE_GITHUB_APP_PRIVATE_KEY_PATH=/etc/pullbase/github-app.pem

# Migrations
PULLBASE_MIGRATIONS_PATH=file:///var/lib/pullbase/migrations
EOF
sudo chmod 600 /etc/pullbase/pullbase.env

Store long-lived secrets in a vault or parameter store and template this environment file during provisioning.

Using PostgreSQL instead

For high-availability or large-scale deployments, use PostgreSQL:

# First, create the PostgreSQL database
sudo -u postgres psql <<'SQL'
CREATE ROLE pullbaseuser WITH LOGIN PASSWORD 'change-me';
CREATE DATABASE pullbasedb OWNER pullbaseuser;
GRANT ALL PRIVILEGES ON DATABASE pullbasedb TO pullbaseuser;
SQL

Then update /etc/pullbase/pullbase.env:

# Database configuration (PostgreSQL)
PULLBASE_DB_TYPE=postgres
PULLBASE_DB_HOST=localhost
PULLBASE_DB_PORT=5432
PULLBASE_DB_USER=pullbaseuser
PULLBASE_DB_PASSWORD=change-me
PULLBASE_DB_NAME=pullbasedb
PULLBASE_DB_SSLMODE=disable

Create a systemd service

Create the service user:

sudo useradd --system --home /var/lib/pullbase --shell /usr/sbin/nologin pullbase
sudo chown -R pullbase:pullbase /var/lib/pullbase

Create the systemd unit:

/etc/systemd/system/pullbase.service

[Unit]
Description=Pullbase Server
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
EnvironmentFile=/etc/pullbase/pullbase.env
ExecStart=/usr/local/bin/pullbase-server
Restart=on-failure
RestartSec=5
User=pullbase
Group=pullbase
WorkingDirectory=/var/lib/pullbase

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now pullbase.service
sudo systemctl status pullbase.service

Verify the health endpoint: curl http://localhost:8080/api/v1/healthz

Bootstrap the admin

On first start, Pullbase generates a one-time bootstrap secret. Use it to create your admin account:

# Read the bootstrap secret
sudo cat /var/lib/pullbase/config/bootstrap-admin-secret.txt

# Create the admin user
pullbasectl auth bootstrap-admin \
  --server-url http://localhost:8080 \
  --bootstrap-secret "YOUR_SECRET" \
  --username admin \
  --password 'YourSecurePassword123!'

The bootstrap secret file is automatically deleted after successful admin creation.

Alternatively, use the secret file directly:

pullbasectl auth bootstrap-admin \
  --server-url http://localhost:8080 \
  --bootstrap-secret-file /var/lib/pullbase/config/bootstrap-admin-secret.txt \
  --username admin \
  --password 'YourSecurePassword123!'

TLS configuration

Pullbase supports two approaches for TLS:

Option 1: Native TLS (simpler)

Enable native TLS by adding these variables to /etc/pullbase/pullbase.env:

PULLBASE_TLS_ENABLED=true
PULLBASE_TLS_CERT_PATH=/etc/pullbase/certs/server.crt
PULLBASE_TLS_KEY_PATH=/etc/pullbase/certs/server.key

For development, generate self-signed certificates:

pullbase-server --generate-dev-certs

Use CA-signed certificates in production.

Option 2: Reverse proxy (for existing infrastructure)

Place Pullbase behind a reverse proxy that terminates TLS:

/etc/nginx/sites-available/pullbase

server {
    listen 443 ssl http2;
    server_name pullbase.example.com;
    
    ssl_certificate /etc/ssl/certs/pullbase.crt;
    ssl_certificate_key /etc/ssl/private/pullbase.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Install agents on managed servers

Once the central server is running, install agents on each server you want to manage.

Recommended: Install script

After creating a server and token in the Pullbase UI, run the install script on each managed server:

curl -fsSL "https://pullbase.example.com/api/v1/servers/web-01/install-script?token=pbt_xxx" | sudo bash

The script downloads the agent, creates a systemd service, and starts it automatically.

Get the complete install command from the UI: Servers > [your server] > Install

Manual installation

For more control, see Agent Operations for step-by-step manual installation.

Next steps

Bootstrap your first admin using the generated secret
Integrate a GitHub App if you pull from private repositories
Review Security & Hardening to lock down secrets, TLS, and network access

Building from source (optional)

If you need to build Pullbase yourself (for development or custom builds):

Prerequisites

Install Go 1.22+ and Node.js 20+.

Clone and build

git clone https://github.com/pullbase/pullbase.git
cd pullbase
./scripts/build-with-ui.sh

The server binary (with embedded UI) is written to bin/pullbase-server.

Build the agent

cd agent
go build -o pullbase-agent

Foundations

Setup

Operations

Examples

Prerequisites

Configure the server

Install the server

Using PostgreSQL instead

Create a systemd service

Bootstrap the admin

TLS configuration

Option 1: Native TLS (simpler)

Option 2: Reverse proxy (for existing infrastructure)

Install agents on managed servers

Recommended: Install script

Manual installation

Next steps

Building from source (optional)

​Prerequisites

​Configure the server

​Install the server

​Using PostgreSQL instead

​Create a systemd service

​Bootstrap the admin

​TLS configuration

​Option 1: Native TLS (simpler)

​Option 2: Reverse proxy (for existing infrastructure)

​Install agents on managed servers

​Recommended: Install script

​Manual installation

​Next steps

​Building from source (optional)

Prerequisites

Configure the server

Install the server

Using PostgreSQL instead

Create a systemd service

Bootstrap the admin

TLS configuration

Option 1: Native TLS (simpler)

Option 2: Reverse proxy (for existing infrastructure)

Install agents on managed servers

Recommended: Install script

Manual installation

Next steps

Building from source (optional)