Environment Configuration

Environment Overview

pb-ext inherits PocketBase’s configuration system and adds pb-ext-specific settings. Configuration can be set via environment variables, command-line flags, or programmatically in code.

Port Configuration

Default Port

pb-ext runs on port 8090 by default:

# Starts on http://127.0.0.1:8090
./pb-ext serve

Custom Port via Command Line

Use the --http flag to specify a custom port:

# Custom port
./pb-ext serve --http=127.0.0.1:9090

# Listen on all interfaces
./pb-ext serve --http=0.0.0.0:8090

# Custom host and port
./pb-ext serve --http=192.168.1.100:3000

--http

string

default:"127.0.0.1:8090"

HTTP server address and port (host:port)

Programmatic Port Configuration

Set the port in code using os.Args:

package main

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

func main() {
    // Set custom port before server initialization
    os.Args = []string{"app", "serve", "--http=127.0.0.1:9090"}
    
    srv := app.New()
    // ... rest of setup
}

Environment Variable

Set via environment variable:

export PB_HTTP="127.0.0.1:9090"
./pb-ext serve

Data Directory

Default Data Directory

By default, PocketBase stores all data in pb_data/:

pb_data/
├── data.db              # Main SQLite database
├── logs.db              # Request logs
├── backups/             # Automatic backups
└── storage/             # File uploads

Custom Data Directory via Flag

./pb-ext serve --dir=/var/lib/pb-ext/data

Programmatic Configuration

Configure the data directory in code:

package main

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

func main() {
    // Option 1: Custom PocketBase config
    pbConfig := &pocketbase.Config{
        DefaultDataDir: "./custom_pb_data",
    }
    srv := app.New(app.WithConfig(pbConfig))
    
    // ... rest of setup
}

Ensure the data directory has proper permissions (0755 for directory, 0600 for database file) and sufficient disk space.

Developer Mode vs Normal Mode

pb-ext can run in two modes that affect behavior and security settings.

Developer Mode

Enables development features and relaxed security:

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

Command line:

go run ./cmd/server --dev serve

Features:

Verbose logging
Runtime OpenAPI spec generation via AST parsing
Auto-migration of schema changes
CORS headers relaxed for localhost
Admin UI accessible without HTTPS

Never use developer mode in production. It disables important security features.

Normal Mode (Production)

Production-ready configuration:

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

Features:

Structured logging only
OpenAPI specs read from disk (specs/ directory)
CORS restrictions enforced
Requires HTTPS for admin UI (recommended)
Security headers enabled

Database Configuration

Database File Location

The main database file:

pb_data/data.db

Connection Pool Settings

PocketBase uses SQLite with WAL mode enabled by default for better concurrency:

// Custom database configuration (advanced)
pbConfig := &pocketbase.Config{
    DefaultDataDir: "./pb_data",
}
srv := app.New(app.WithConfig(pbConfig))

Database Backups

Automatic backups are stored in:

pb_data/backups/

Backups are created:

Before schema migrations
On demand via admin UI
Via cron job (if configured)

Logs and Persistent Storage

Application Logs

Structured logs are written to:

pb_data/logs.db

Access logs via SQL:

SELECT * FROM _logs 
ORDER BY created DESC 
LIMIT 100;

pb-ext System Logs

pb-ext creates these collections for operational data:

Collection	Purpose	Retention
`_analytics`	Page view analytics	90 days
`_analytics_sessions`	Recent 50 visits	Ring buffer
`_job_logs`	Cron job execution logs	72 hours

Log Rotation

For systemd deployments, use journald for log management:

[Service]
StandardOutput=journal
StandardError=journal

View logs:

sudo journalctl -u pb-ext -f

Environment Variables

Common environment variables for pb-ext:

PB_HTTP

string

default:"127.0.0.1:8090"

HTTP server address

PB_DATA_DIR

string

default:"./pb_data"

Data directory path

PB_DEV

boolean

default:false

Enable developer mode

PB_ENCRYPTION_KEY

string

32-character key for encrypting sensitive fields

PB_ADMIN_EMAIL

string

Default admin email (first-run setup)

PB_ADMIN_PASSWORD

string

Default admin password (first-run setup)

Example .env File

# Server configuration
PB_HTTP=127.0.0.1:8090
PB_DATA_DIR=/var/lib/pb-ext/data

# Security
PB_ENCRYPTION_KEY=your-32-character-encryption-key-here

# Admin setup (first run only)
PB_ADMIN_EMAIL=[email protected]
PB_ADMIN_PASSWORD=secure-password-here

# Optional: External services
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=smtp-password

Load environment variables using a package like godotenv or via systemd service configuration.

Docker Configuration

Dockerfile Example

FROM golang:1.21-alpine AS builder

WORKDIR /app

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

# Copy source
COPY . .

# Build binary
RUN go build -ldflags="-s -w" -o pb-ext ./cmd/server

FROM alpine:latest

RUN apk --no-cache add ca-certificates

WORKDIR /app

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

# Create data directory
RUN mkdir -p /app/pb_data

# Expose port
EXPOSE 8090

# Run as non-root
RUN adduser -D -u 1000 pbext
RUN chown -R pbext:pbext /app
USER pbext

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

Docker Compose

version: '3.8'

services:
  pb-ext:
    build: .
    ports:
      - "8090:8090"
    environment:
      - PB_HTTP=0.0.0.0:8090
      - PB_ENCRYPTION_KEY=${PB_ENCRYPTION_KEY}
    volumes:
      - pb_data:/app/pb_data
    restart: unless-stopped

volumes:
  pb_data:

Running with Docker

# Build image
docker build -t pb-ext .

# Run container
docker run -d \
  -p 8090:8090 \
  -v pb_data:/app/pb_data \
  -e PB_ENCRYPTION_KEY="your-key-here" \
  --name pb-ext \
  pb-ext

# View logs
docker logs -f pb-ext

Configuration Precedence

Settings are applied in this order (later overrides earlier):

Default values (hardcoded in PocketBase/pb-ext)
Environment variables (PB_*)
Command-line flags (--http, --dir, etc.)
Programmatic configuration (WithConfig, os.Args)

Security Considerations

File Permissions

Set restrictive permissions on sensitive files:

chmod 600 pb_data/data.db
chmod 700 pb_data/

Encryption Key

Generate a secure encryption key:

openssl rand -base64 32

Store securely (environment variable or secrets manager).

Network Binding

Development: 127.0.0.1:8090 (localhost only)
Production: Use reverse proxy (Nginx/Caddy)
Docker: 0.0.0.0:8090 inside container, map externally

Admin Access

Use strong admin passwords
Enable 2FA for admin accounts
Restrict admin panel to VPN or trusted IPs
Use HTTPS in production

Monitoring Configuration

Health Checks

Configure health check endpoints:

# Check server status
curl http://localhost:8090/_/

# pb-ext dashboard
curl http://localhost:8090/_/_

Metrics Collection

pb-ext automatically collects system metrics:

CPU usage
Memory usage
Disk space
Network I/O
Request statistics
Active connections

Access via the dashboard at http://localhost:8090/_/_

Troubleshooting

Port already in use

Error: bind: address already in useSolution:

# Find process using port 8090
lsof -i :8090

# Kill process or use different port
./pb-ext serve --http=127.0.0.1:9090

Permission denied on data directory

Error: failed to open database: unable to open database fileSolution:

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

# If running as service, ensure correct owner
sudo chown -R pbext:pbext /var/lib/pb-ext

Database locked errors

Cause: Multiple instances accessing same database or stale lock.Solution:

Ensure only one instance is running
Remove stale lock: rm pb_data/data.db-wal
Check file permissions

Next Steps

Production Deployment

Deploy to production with automated tools

Frontend Configuration

Set up SvelteKit and static file serving

Getting Started

Core Concepts

API Documentation

Features

Advanced

CLI Tools

Deployment

​Environment Overview

​Port Configuration

​Default Port

​Custom Port via Command Line

​Programmatic Port Configuration

​Environment Variable

​Data Directory

​Default Data Directory

​Custom Data Directory via Flag

​Programmatic Configuration

​Developer Mode vs Normal Mode

​Developer Mode

​Normal Mode (Production)

​Database Configuration

​Database File Location

​Connection Pool Settings

​Database Backups

​Logs and Persistent Storage

​Application Logs

​pb-ext System Logs

​Log Rotation

​Environment Variables

​Example .env File

​Docker Configuration

​Dockerfile Example

​Docker Compose

​Running with Docker

​Configuration Precedence

​Security Considerations

​Monitoring Configuration

​Health Checks

​Metrics Collection

​Troubleshooting

​Next Steps

Production Deployment

Frontend Configuration

Environment Overview

Port Configuration

Default Port

Custom Port via Command Line

Programmatic Port Configuration

Environment Variable

Data Directory

Default Data Directory

Custom Data Directory via Flag

Programmatic Configuration

Developer Mode vs Normal Mode

Developer Mode

Normal Mode (Production)

Database Configuration

Database File Location

Connection Pool Settings

Database Backups

Logs and Persistent Storage

Application Logs

pb-ext System Logs

Log Rotation

Environment Variables

Example .env File

Docker Configuration

Dockerfile Example

Docker Compose

Running with Docker

Configuration Precedence

Security Considerations

Monitoring Configuration

Health Checks

Metrics Collection

Troubleshooting

Next Steps