docs/deployment-bare-metal.mdx at main · pullbase/docs

title	Bare-Metal Deployment
description	Run the Pullbase server and agent directly on VMs or physical hosts.

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 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.

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

```bash 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:

[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:

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):

Install Go 1.22+ and Node.js 20+. ```bash 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.

```bash cd agent go build -o pullbase-agent ```

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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)

FilesExpand file tree

deployment-bare-metal.mdx

Latest commit

History

deployment-bare-metal.mdx

File metadata and controls

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)