Skip to content

Latest commit

 

History

History
228 lines (174 loc) · 6.28 KB

quickstart.mdx

File metadata and controls

228 lines (174 loc) · 6.28 KB
title description
Quickstart
Get Pullbase running and see your first servers come online in under 5 minutes.

This guide gets you from zero to a working Pullbase setup with agents reporting status. By the end, you'll have:

  • A running Pullbase server with database
  • An admin account
  • Two demo agents reporting their status

Time estimate: 5 minutes

Prerequisites

  • Docker 24.0+ with the Compose plugin (docker compose)
  • Git to clone the repository
  • A terminal (macOS, Linux, or WSL)
**This quickstart is for evaluation only.** It uses Docker to run demo agents for testing purposes.

For production:

  • Deploy the central server using Docker or bare-metal
  • Install agents natively on your Linux servers using the install script — never run production agents in containers

Step 1: Clone and start Pullbase

git clone https://github.com/pullbase/pullbase.git
cd pullbase
docker compose up -d

This starts:

  • PostgreSQL database
  • Pullbase server (API + dashboard)
  • Two demo agents (test-server-1, test-server-2)
Wait for the stack to be healthy (about 60 seconds): 
docker compose ps

You should see all services with status healthy or running.

Step 2: Verify the server is running

curl http://localhost:8080/api/v1/healthz

Expected output:

{"status":"healthy","service":"pullbase-server"}

Step 3: Bootstrap your admin account

Pullbase generates a one-time bootstrap secret on first start. Retrieve it and create your admin:

# Get the bootstrap secret
docker compose exec central-server cat /app/secrets/bootstrap.secret

# Create admin (replace YOUR_SECRET with the value above)
docker compose exec central-server pullbasectl auth bootstrap-admin \
  --server-url http://localhost:8080 \
  --bootstrap-secret "YOUR_SECRET" \
  --username admin \
  --password 'SecurePassword123!'
You should see: ``` Admin bootstrap completed successfully. Username: admin Access token (store securely): eyJhbGciOiJIUzI1NiIs... ``` Save the access token! You'll need it for CLI commands. The bootstrap secret is invalidated after use.

Step 4: Open the dashboard

Visit http://localhost:8080 in your browser and sign in with:

  • Username: admin
  • Password: SecurePassword123! (or whatever you chose)
You should see the Pullbase dashboard with: - A sidebar showing "Environments" and "Servers" - The demo environment and servers from the seeded data

Step 5: Watch agents come online

Navigate to Servers in the sidebar. Within 60 seconds, you should see:

Server Status Last Seen
test-server-1 Applied Just now
test-server-2 Applied Just now

The agents are pulling configuration from the demo environment and reporting their status.

Congratulations! You have a working Pullbase installation.

Next: Add your own server

Now that you've seen Pullbase working, here's how to add a real server.

Option A: Using the UI

  1. Go to Servers → Create Server
  2. Enter a server ID (e.g., web-01) and name
  3. Select an environment
  4. Click Create
  5. Go to the server's Tokens tab and create a token
  6. Copy the install command and run it on your target server

Option B: Using the CLI

# Set your server URL and token
export PULLBASE_URL=http://localhost:8080
export PULLBASE_TOKEN=<your-access-token-from-step-3>

# Create a server
docker compose exec central-server pullbasectl servers create \
  --server-url $PULLBASE_URL \
  --admin-token $PULLBASE_TOKEN \
  --id web-01 \
  --name "Web Server 01" \
  --environment-id 1

# Create an agent token
docker compose exec central-server pullbasectl tokens create \
  --server-url $PULLBASE_URL \
  --admin-token $PULLBASE_TOKEN \
  --server-id web-01 \
  --description "initial token"

The token output includes an install command you can run on your target server.

Install the agent on your server

On your target Linux server (VM, bare-metal, or cloud instance):

curl -fsSL "http://YOUR_PULLBASE_HOST:8080/api/v1/servers/web-01/install-script?token=YOUR_TOKEN" | sudo bash
For production, always use HTTPS. See [Security Hardening](/security-hardening) for TLS setup.

What's next?

Group servers and link them to Git repositories Define packages, services, and files to manage Deploy Pullbase on real infrastructure with TLS Master the CLI for automation and workflows

Troubleshooting

- Ensure Docker is running: `docker info` - Check if port 8080 is available: `lsof -i :8080` - Check if port 5432 is available: `lsof -i :5432` - View logs: `docker compose logs -f` The secret file is created on first boot. Wait 30 seconds after `docker compose up` and try again: ```bash docker compose exec central-server cat /app/secrets/bootstrap.secret ``` - Check agent logs: `docker compose logs test-server-1` - Agents report every 60 seconds — wait and refresh - Verify the central-server is healthy: `curl http://localhost:8080/api/v1/healthz` - Ensure the central-server is running: `docker compose ps` - Check for errors: `docker compose logs central-server` - Try the healthcheck: `docker compose exec central-server wget -qO- http://localhost:8080/api/v1/healthz`

Clean up

To stop and remove all containers and data:

docker compose down -v

This removes:

  • All containers
  • The PostgreSQL data volume
  • Generated certificates