Quickstart

This guide will walk you through creating a minimal pb-ext application from scratch. By the end, you’ll have a running server with monitoring, logging, and API documentation.

Prerequisites

Install Go

pb-ext requires Go 1.25.7 or higher.

# Check your Go version
go version

If you need to install or upgrade Go, visit golang.org/dl.

Verify Installation

Ensure Go is properly installed and in your PATH:

# This should display the Go version
go version
# Expected output: go version go1.25.7 linux/amd64

Create Your First pb-ext Project

Create Project Directory

mkdir my-pb-project
cd my-pb-project

Initialize Go Module

go mod init my-pb-project

This creates a go.mod file that tracks your dependencies.

Create Main Application File

Create the directory structure and main file:

mkdir -p cmd/server

Create cmd/server/main.go with the following content:

cmd/server/main.go

package main

import (
    "flag"
    "log"

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

func main() {
    devMode := flag.Bool("dev", false, "Run in developer mode")
    flag.Parse()

    initApp(*devMode)
}

func initApp(devMode bool) {
    var opts []app.Option

    if devMode {
        opts = append(opts, app.InDeveloperMode())
    } else {
        opts = append(opts, app.InNormalMode())
    }

    srv := app.New(opts...)

    app.SetupLogging(srv)

    registerCollections(srv.App())
    registerRoutes(srv.App())
    registerJobs(srv.App())

    srv.App().OnServe().BindFunc(func(e *core.ServeEvent) error {
        app.SetupRecovery(srv.App(), e)
        return e.Next()
    })

    if err := srv.Start(); err != nil {
        srv.App().Logger().Error("Fatal application error",
            "error", err,
            "uptime", srv.Stats().StartTime,
            "total_requests", srv.Stats().TotalRequests.Load(),
        )
        log.Fatal(err)
    }
}

func registerCollections(app core.App) {
    // We'll add collections later
}

func registerRoutes(app core.App) {
    // We'll add routes later
}

func registerJobs(app core.App) {
    // We'll add jobs later
}

This is the exact structure from cmd/server/main.go in the pb-ext repository. The file location matters: pb-cli expects your entry point at cmd/server/main.go.

Download Dependencies

go mod tidy

This downloads pb-ext and all its dependencies (PocketBase, gopsutil, etc.).

Install pb-cli Toolchain

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

The pb-cli toolchain automates building, running, and deploying pb-ext applications.

Make sure your $GOPATH/bin or $HOME/go/bin is in your PATH. If pb-cli is not found, add this to your shell profile:

export PATH="$PATH:$(go env GOPATH)/bin"

Run Your Server

pb-cli --run-only

You should see output similar to:

> Server:     http://127.0.0.1:8090
├─ REST API: http://127.0.0.1:8090/api/
└─ Admin UI: http://127.0.0.1:8090/_
└─ pb-ext Dashboard:  http://127.0.0.1:8090/_/_

The --run-only flag skips frontend building (useful when you don’t have a frontend yet).

Access Your Application

PocketBase Admin Panel

Open http://127.0.0.1:8090/_Create your first admin account to access the PocketBase admin UI.

pb-ext Dashboard

Open http://127.0.0.1:8090//View system metrics, analytics, and cron job logs (requires admin auth).

Add Your First API Endpoint

Let’s add a simple API endpoint to see how pb-ext auto-generates documentation.

Create Routes File

Create cmd/server/routes.go:

cmd/server/routes.go

package main

// API_SOURCE

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

func registerRoutes(app core.App) {
    versionManager := initVersionedSystem()
    
    app.OnServe().BindFunc(func(e *core.ServeEvent) error {
        if err := versionManager.RegisterAllVersionRoutes(e); err != nil {
            return err
        }
        return e.Next()
    })
    
    versionManager.RegisterWithServer(app)
}

func initVersionedSystem() *api.APIVersionManager {
    v1Config := &api.APIDocsConfig{
        Title:       "My API",
        Description: "My first pb-ext API",
        Version:     "1.0.0",
        Status:      "stable",
        BaseURL:     "http://127.0.0.1:8090/",
        Enabled:     true,
        PublicSwagger: true,
    }
    
    return api.InitializeVersionedSystemWithRoutes(map[string]*api.VersionSetup{
        "v1": {
            Config: v1Config,
            Routes: registerV1Routes,
        },
    }, "v1")
}

// API_DESC Returns the current server time
// API_TAGS utilities
func timeHandler(e *core.RequestEvent) error {
    return e.JSON(200, map[string]string{
        "time": time.Now().Format(time.RFC3339),
    })
}

func registerV1Routes(router *api.VersionedAPIRouter) {
    router.GET("/api/v1/time", timeHandler)
}

The // API_SOURCE comment at the top tells pb-ext to parse this file for OpenAPI metadata. The API_DESC and API_TAGS directives add documentation to your endpoint.

Restart the Server

Stop the server (Ctrl+C) and restart it:

pb-cli --run-only

Test Your Endpoint

curl http://127.0.0.1:8090/api/v1/time

Expected response:

{
  "time": "2026-03-04T10:30:45Z"
}

View Auto-Generated Docs

Open http://127.0.0.1:8090/api/docs/v1/swaggerYou’ll see a Swagger UI with your /api/v1/time endpoint fully documented, including the response schema automatically inferred from your code.

Add a Cron Job

Let’s schedule a background task that runs every minute.

Create Jobs File

Create cmd/server/jobs.go:

cmd/server/jobs.go

package main

import (
    "fmt"
    "time"
    
    "github.com/magooney-loon/pb-ext/core/jobs"
    "github.com/pocketbase/pocketbase/core"
)

func registerJobs(app core.App) {
    app.OnServe().BindFunc(func(e *core.ServeEvent) error {
        if err := helloJob(app); err != nil {
            app.Logger().Error("Failed to register hello job", "error", err)
            return err
        }
        
        app.Logger().Info("Cron jobs registered successfully")
        return e.Next()
    })
}

func helloJob(app core.App) error {
    jm := jobs.GetManager()
    if jm == nil {
        return fmt.Errorf("job manager not initialized")
    }
    
    return jm.RegisterJob(
        "helloWorld",
        "Hello World Job",
        "A demonstration job that runs every minute",
        "*/1 * * * *", // Every minute
        func(el *jobs.ExecutionLogger) {
            el.Start("Hello World Job")
            el.Info("Current time: %s", time.Now().Format("2006-01-02 15:04:05"))
            el.Progress("Processing task...")
            
            // Simulate work
            time.Sleep(100 * time.Millisecond)
            
            el.Success("Task completed successfully")
            el.Complete("Job finished")
        },
    )
}

Restart and View Job Logs

Restart the server:

pb-cli --run-only

After waiting 1 minute, check the dashboard at http://127.0.0.1:8090// to see your job execution logs.

Add a Database Collection

Let’s create a simple “todos” collection.

Create Collections File

Create cmd/server/collections.go:

cmd/server/collections.go

package main

import (
    "github.com/pocketbase/pocketbase/core"
)

func registerCollections(app core.App) {
    app.OnServe().BindFunc(func(e *core.ServeEvent) error {
        if err := todoCollection(e.App); err != nil {
            app.Logger().Error("Failed to create todo collection", "error", err)
        }
        return e.Next()
    })
}

func todoCollection(app core.App) error {
    existingCollection, _ := app.FindCollectionByNameOrId("todos")
    if existingCollection != nil {
        return nil // Already exists
    }
    
    collection := core.NewBaseCollection("todos")
    
    collection.Fields.Add(&core.TextField{
        Name:     "title",
        Required: true,
        Max:      200,
    })
    
    collection.Fields.Add(&core.BoolField{
        Name: "completed",
    })
    
    collection.Fields.Add(&core.AutodateField{
        Name:     "created",
        OnCreate: true,
    })
    
    // Public access for demo
    collection.ViewRule = nil
    collection.CreateRule = nil
    collection.UpdateRule = nil
    collection.DeleteRule = nil
    
    if err := app.Save(collection); err != nil {
        return err
    }
    
    app.Logger().Info("Created todos collection")
    return nil
}

Restart Server

pb-cli --run-only

The “todos” collection will be automatically created on startup.

Test CRUD Operations

Create a todo:

curl -X POST http://127.0.0.1:8090/api/collections/todos/records \
  -H "Content-Type: application/json" \
  -d '{"title": "Learn pb-ext", "completed": false}'

List todos:

curl http://127.0.0.1:8090/api/collections/todos/records

Project Structure

Your project should now look like this:

my-pb-project/
├── cmd/
│   └── server/
│       ├── main.go          # Entry point
│       ├── routes.go        # API routes
│       ├── collections.go   # Database schemas
│       └── jobs.go          # Cron jobs
├── pb_data/                 # Created automatically (database)
├── pb_public/               # Static files (optional)
├── go.mod                   # Go dependencies
└── go.sum                   # Dependency checksums

You can restructure your project however you like, but cmd/server/main.go is the conventional entry point expected by pb-cli.

Next Steps

Learn API Documentation

Master the AST-based OpenAPI system with versioning and parameter inference

Explore Cron Jobs

Deep dive into job scheduling, logging, and the management API

Setup Frontend

Build a SvelteKit frontend with the pb-cli toolchain

Deploy to Production

Use pb-deployer for automated VPS deployment

Troubleshooting

pb-cli: command not found

Make sure $GOPATH/bin is in your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Add this to your .bashrc or .zshrc to make it permanent.

Port 8090 already in use

Change the port by passing flags to the server:

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

Or set it programmatically in main.go:

os.Args = []string{"app", "serve", "--http=127.0.0.1:9090"}

Module not found errors

Run go mod tidy to ensure all dependencies are downloaded:

go mod tidy

Dashboard shows no data

The dashboard requires admin authentication. Make sure you:

Created an admin account at /_/
Logged in before accessing /_/_

Example Project

Want to see a complete working example? The pb-ext repository includes a full example server in cmd/server/ with:

Multiple API versions (v1, v2)
CRUD routes with OpenAPI docs
Cron jobs with logging
Collection definitions
Request middleware

Clone the repository to explore:

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

Getting Started

Core Concepts

API Documentation

Features

Advanced

CLI Tools

Deployment

Prerequisites

Create Your First pb-ext Project

Access Your Application

PocketBase Admin Panel

pb-ext Dashboard

Add Your First API Endpoint

Add a Cron Job

Add a Database Collection

Project Structure

Next Steps

Learn API Documentation

Explore Cron Jobs

Setup Frontend

Deploy to Production

Troubleshooting

Example Project

​Prerequisites

​Create Your First pb-ext Project

​Access Your Application

PocketBase Admin Panel

pb-ext Dashboard

​Add Your First API Endpoint

​Add a Cron Job

​Add a Database Collection

​Project Structure

​Next Steps

Learn API Documentation

Explore Cron Jobs

Setup Frontend

Deploy to Production

​Troubleshooting

​Example Project

Prerequisites

Create Your First pb-ext Project

Access Your Application

Add Your First API Endpoint

Add a Cron Job

Add a Database Collection

Project Structure

Next Steps

Troubleshooting

Example Project