Installation

This guide covers everything you need to install and configure pb-ext for development and production use.

System Requirements

Minimum Requirements

Component	Version	Notes
Go	1.25.7 or higher	Required for building and running pb-ext
Operating System	Linux, macOS, Windows	Cross-platform support
RAM	512 MB minimum	1 GB+ recommended for production
Disk Space	100 MB	For binaries, database, and dependencies

pb-ext requires Go 1.25.7 or higher. Earlier versions are not supported due to module dependencies.

Optional Dependencies

Tool	Purpose	Installation
Node.js	Frontend building with pb-cli	nodejs.org
Git	Version control and examples	git-scm.com
curl	Testing API endpoints	Usually pre-installed

Installation Methods

Quick Start (Recommended)
From Examples
Docker
Manual Build

Quick Start Installation

The fastest way to get started with pb-ext:

Install Go

Download and install Go from golang.org/dlVerify installation:

go version
# Expected: go version go1.25.7 or higher

Create Project

mkdir my-pb-project
cd my-pb-project
go mod init my-pb-project

Install pb-ext

Add pb-ext as a dependency:

go get github.com/magooney-loon/pb-ext/core
go mod tidy

Install pb-cli Toolchain

go install github.com/magooney-loon/pb-ext/cmd/pb-cli@latest

Verify installation:

pb-cli --help

Create Application

Create cmd/server/main.go:

package main

import (
    "log"
    app "github.com/magooney-loon/pb-ext/core"
    "github.com/pocketbase/pocketbase/core"
)

func main() {
    srv := app.New(app.InDeveloperMode())
    app.SetupLogging(srv)
    
    srv.App().OnServe().BindFunc(func(e *core.ServeEvent) error {
        app.SetupRecovery(srv.App(), e)
        return e.Next()
    })
    
    if err := srv.Start(); err != nil {
        log.Fatal(err)
    }
}

Run Application

pb-cli --run-only

Open http://127.0.0.1:8090/_ to access the admin panel.

Using Example Project

Clone the pb-ext repository to get a complete working example:

Clone Repository

git clone https://github.com/magooney-loon/pb-ext.git
cd pb-ext

Install Dependencies

go mod tidy
go install github.com/magooney-loon/pb-ext/cmd/pb-cli@latest

Run Example Server

pb-cli --run-only

Explore Examples

The cmd/server/ directory contains complete examples:

main.go - Server initialization with flags
routes.go - API versioning and handlers
collections.go - Database schema definitions
jobs.go - Cron job examples
handlers.go - Request handlers with OpenAPI annotations

This method is ideal for learning pb-ext features through working code examples.

Docker Installation

Run pb-ext in a containerized environment:

Create Dockerfile

Dockerfile

FROM golang:1.25.7-alpine AS builder

WORKDIR /app

# Install dependencies
RUN apk add --no-cache git

# Copy go mod files
COPY go.mod go.sum ./
RUN go mod download

# Copy source code
COPY . .

# Build application
RUN go build -ldflags="-s -w" -o server cmd/server/main.go

# Runtime image
FROM alpine:latest

WORKDIR /app

# Copy binary and static files
COPY --from=builder /app/server .
COPY --from=builder /app/pb_public ./pb_public

EXPOSE 8090

CMD ["./server", "serve", "--http=0.0.0.0:8090"]

Build Image

docker build -t my-pb-app .

Run Container

docker run -p 8090:8090 \
  -v $(pwd)/pb_data:/app/pb_data \
  my-pb-app

The volume mount (-v) persists your database across container restarts.

Manual Build from Source

Build pb-ext without using pb-cli:

Clone and Setup

git clone https://github.com/magooney-loon/pb-ext.git
cd pb-ext
go mod download

Build Binary

go build -o pb-server cmd/server/main.go

For production with optimizations:

go build -ldflags="-s -w" -o pb-server cmd/server/main.go

Run Server

./pb-server serve

Verifying Installation

After installation, verify everything works correctly:

Check Go Version

go version

Should output go version go1.25.7 or higher.

Check pb-cli

pb-cli --help

Should display the pb-cli usage information.

Run Test Server

Create a minimal test:

mkdir test-pb
cd test-pb
go mod init test-pb
go get github.com/magooney-loon/pb-ext/core

Create main.go:

package main
import (
    "log"
    app "github.com/magooney-loon/pb-ext/core"
)
func main() {
    srv := app.New(app.InDeveloperMode())
    app.SetupLogging(srv)
    if err := srv.Start(); err != nil {
        log.Fatal(err)
    }
}

Run it:

go run main.go serve

Access Admin Panel

Open http://127.0.0.1:8090/_ in your browser.You should see the PocketBase admin setup page.

Access Dashboard

After creating an admin account, visit http://127.0.0.1:8090//.You should see the pb-ext health dashboard with system metrics.

Configuration

Environment Variables

pb-ext respects standard PocketBase environment variables:

Variable	Default	Description
`PB_DATA_DIR`	`./pb_data`	Database and storage directory
`PB_ENCRYPTION_KEY`	Generated	Database encryption key
`PB_LOG_LEVEL`	`info`	Logging level (debug, info, warn, error)

Set environment variables before starting:

export PB_DATA_DIR=/var/lib/pb-data
export PB_LOG_LEVEL=debug
pb-cli --run-only

Configuration Options

Configure pb-ext via functional options in your main.go:

import (
    app "github.com/magooney-loon/pb-ext/core"
    "github.com/pocketbase/pocketbase"
)

func main() {
    // Option 1: Custom PocketBase config
    srv := app.New(
        app.WithConfig(&pocketbase.Config{
            DefaultDev:     true,
            DefaultDataDir: "./custom_pb_data",
        }),
    )
    
    // Option 2: Existing PocketBase instance
    pb := pocketbase.New()
    srv := app.New(app.WithPocketbase(pb))
    
    // Option 3: Developer mode toggle
    srv := app.New(app.InDeveloperMode())
    
    // Start server
    app.SetupLogging(srv)
    srv.Start()
}

WithConfig and WithPocketbase are mutually exclusive. Use one or the other, not both.

Custom Port Configuration

Change the default port (8090) programmatically:

import "os"

func main() {
    // Set port before creating server
    os.Args = []string{"app", "serve", "--http=127.0.0.1:9090"}
    
    srv := app.New(app.InDeveloperMode())
    app.SetupLogging(srv)
    srv.Start()
}

Or via command line:

pb-cli --run-only -- serve --http=127.0.0.1:9090

Troubleshooting

pb-cli: command not found

Problem: The pb-cli command is not found after installation.Solution: Ensure $GOPATH/bin is in your PATH:

# Check GOPATH
go env GOPATH

# Add to PATH (Linux/macOS)
export PATH="$PATH:$(go env GOPATH)/bin"

# Add to PATH (Windows PowerShell)
$env:Path += ";$(go env GOPATH)\bin"

Make it permanent by adding to your shell profile (~/.bashrc, ~/.zshrc, etc.):

echo 'export PATH="$PATH:$(go env GOPATH)/bin"' >> ~/.bashrc
source ~/.bashrc

Go version too old

Problem: Error messages about Go version requirements.Solution: Upgrade to Go 1.25.7 or higher:

# Download from golang.org/dl
# Or use version manager like gvm:

# Install gvm
bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)

# Install Go 1.25.7
gvm install go1.25.7
gvm use go1.25.7 --default

Port already in use

Problem: bind: address already in use error.Solution: Find and kill the process using port 8090:

# Find process
lsof -i :8090
# Or
netstat -tuln | grep 8090

# Kill process
kill -9 <PID>

# Or use a different port
pb-cli --run-only -- serve --http=127.0.0.1:9090

Module download failures

Problem: go mod tidy fails to download dependencies.Solution: Check your Go module proxy settings:

# Use default proxy
go env -w GOPROXY=https://proxy.golang.org,direct

# Or use mirror (China)
go env -w GOPROXY=https://goproxy.cn,direct

# Retry
go clean -modcache
go mod tidy

Permission denied on Linux

Problem: Cannot write to pb_data directory.Solution: Check directory permissions:

# Create directory with proper permissions
mkdir -p pb_data
chmod 755 pb_data

# Or run with specific user
sudo chown -R $USER:$USER pb_data

Dashboard shows 401 Unauthorized

Problem: Cannot access /_/_ dashboard.Solution: The dashboard requires superuser authentication:

First visit /_/ to create an admin account
Log in to the admin panel
Then access /_/_ - you should be automatically authenticated

If issues persist, clear cookies and try again.

OpenAPI docs not generating

Problem: Swagger UI shows no endpoints.Solution: Ensure your route files have the // API_SOURCE directive:

package main

// API_SOURCE  ← This is required!

import (
    "github.com/magooney-loon/pb-ext/core/server/api"
    "github.com/pocketbase/pocketbase/core"
)

func registerRoutes(app core.App) {
    // Your routes...
}

Check debug endpoint for AST parsing errors: http://127.0.0.1:8090/api/docs/debug/ast

Platform-Specific Notes

Linux

pb-ext works out of the box on most Linux distributions. For production deployments:

# Install as systemd service
sudo nano /etc/systemd/system/pb-ext.service

[Unit]
Description=pb-ext Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/pb-ext
ExecStart=/var/www/pb-ext/server serve
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl enable pb-ext
sudo systemctl start pb-ext

macOS

On macOS, you may need to allow the binary through Gatekeeper:

# If you get "unidentified developer" warning
xattr -d com.apple.quarantine ./pb-server

# Or build from source instead
go build -o pb-server cmd/server/main.go

Windows

On Windows, use PowerShell or CMD:

# Install pb-cli
go install github.com/magooney-loon/pb-ext/cmd/pb-cli@latest

# Add to PATH permanently
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:GOPATH\bin", "User")

# Run server
pb-cli --run-only

Windows Defender may flag the compiled binary. Add an exclusion for your project directory if needed.

Next Steps

Quickstart Guide

Follow the quickstart to build your first pb-ext application

Configuration

Learn about advanced server configuration options

API Documentation

Set up auto-generated OpenAPI documentation

Deployment

Deploy to production with pb-deployer

Additional Resources

Source Repository: github.com/magooney-loon/pb-ext
PocketBase Docs: pocketbase.io/docs
Go Documentation: pkg.go.dev/github.com/magooney-loon/pb-ext
Example Projects: github.com/magooney-loon/pb-ext/tree/main/cmd/server

Getting Started

Core Concepts

API Documentation

Features

Advanced

CLI Tools

Deployment

System Requirements

Minimum Requirements

Optional Dependencies

Installation Methods

Quick Start Installation

Using Example Project

Docker Installation

Manual Build from Source

Verifying Installation

Configuration

Environment Variables

Configuration Options

Custom Port Configuration

Troubleshooting

Platform-Specific Notes

Linux

macOS

Windows

Next Steps

Quickstart Guide

Configuration

API Documentation

Deployment

Additional Resources

​System Requirements

​Minimum Requirements

​Optional Dependencies

​Installation Methods

​Quick Start Installation

​Using Example Project

​Docker Installation

​Manual Build from Source

​Verifying Installation

​Configuration

​Environment Variables

​Configuration Options

​Custom Port Configuration

​Troubleshooting

​Platform-Specific Notes

​Linux

​macOS

​Windows

​Next Steps

Quickstart Guide

Configuration

API Documentation

Deployment

​Additional Resources

System Requirements

Minimum Requirements

Optional Dependencies

Installation Methods

Quick Start Installation

Using Example Project

Docker Installation

Manual Build from Source

Verifying Installation

Configuration

Environment Variables

Configuration Options

Custom Port Configuration

Troubleshooting

Platform-Specific Notes

Linux

macOS

Windows

Next Steps

Additional Resources