Installation

Detailed installation guide for pb-ext with system requirements, multiple installation methods, and troubleshooting

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)

Quick Start Installation

The fastest way to get started with pb-ext:

1. Install Go

   Download and install Go from golang.org/dl

   Verify installation:

   go version
   # Expected: go version go1.25.7 or higher
   
2. Create Project

   mkdir my-pb-project
   cd my-pb-project
   go mod init my-pb-project
   
3. Install pb-ext

   Add pb-ext as a dependency:

   go get github.com/magooney-loon/pb-ext/core
   go mod tidy
   
4. Install pb-cli Toolchain

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

   Verify installation:

   pb-cli --help
   
5. 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)
       }
   }
   
6. Run Application

   pb-cli --run-only
   

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

From Examples

Using Example Project

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

1. Clone Repository

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

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

   pb-cli --run-only
   
4. 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

Docker Installation

Run pb-ext in a containerized environment:

1. 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"]
   
2. Build Image

   docker build -t my-pb-app .
   
3. 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

Manual Build from Source

Build pb-ext without using pb-cli:

1. Clone and Setup

   git clone https://github.com/magooney-loon/pb-ext.git
   cd pb-ext
   go mod download
   
2. 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
   
3. Run Server

   ./pb-server serve
   

Verifying Installation

After installation, verify everything works correctly:

1. Check Go Version

   go version
   

   Should output go version go1.25.7 or higher.

2. Check pb-cli

   pb-cli --help
   

   Should display the pb-cli usage information.

3. 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
   
4. Access Admin Panel

   Open http://127.0.0.1:8090/_ in your browser.

   You should see the PocketBase admin setup page.

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

1. First visit /_/ to create an admin account
2. Log in to the admin panel
3. 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