Multi-PB: Multi-Instance PocketBase Manager

WARNING: THIS PROJECT IS STILL IN DEVELOPMENT, AND IS NOT PRODUCTION READY

Quick Start: Run ./install.sh to get started in minutes! See DEPLOYMENT.md for full hosting guide.

A single-container solution for running multiple isolated PocketBase instances with path-based routing. No DNS setup required.

Features

• Single Container - One Docker container, one port, hundreds of instances
• Path-Based Routing - Access instances via http://host:port/{instance}/_/
• Web Dashboard - UI to manage instances, view logs, and monitor status
• CLI Management - Add/remove/start/stop instances with shell commands
• Auto-Routing - Caddy reverse proxy auto-configured from manifest

Quick Start

# Clone and install
git clone https://github.com/n3-rd/multi-pb.git
cd multi-pb
./install.sh

# Or use docker compose directly
docker compose up -d

# Create your first instance
docker exec multipb add-instance.sh myapp

# Access at: http://localhost:25983/myapp/_/
# Dashboard: http://localhost:25983/dashboard

Installation Options

Installer Script (Recommended)

./install.sh                    # Full installation
./install.sh --cli-only         # Skip dashboard build
./install.sh --port 8080         # Custom port
./install.sh --non-interactive   # No prompts

Docker Compose

docker compose up -d

Direct Docker

docker build -t multipb .
docker run -d --name multipb -p 25983:25983 -v multipb-data:/var/multipb/data multipb

CLI Commands

All commands run via docker exec multipb <command>:

add-instance.sh

Create and start a new PocketBase instance.

docker exec multipb add-instance.sh myapp
docker exec multipb add-instance.sh myapp --email admin@example.com --password secret123

list-instances.sh

List all configured instances with status.

docker exec multipb list-instances.sh

start-instance.sh / stop-instance.sh

Control instance lifecycle.

docker exec multipb stop-instance.sh myapp
docker exec multipb start-instance.sh myapp

remove-instance.sh

Stop and remove a PocketBase instance.

docker exec multipb remove-instance.sh myapp

reload-proxy.sh

Regenerate Caddy configuration from manifest.

docker exec multipb reload-proxy.sh

Architecture

┌─────────────────────────────────────────────┐
│           Docker Container                  │
│  ┌───────────────────────────────────────┐  │
│  │  Caddy (:25983)                       │  │
│  │  - /_health  → Health check           │  │
│  │  - /_instances → List instances       │  │
│  │  - /{instance}/* → PB Instance        │  │
│  └──────────────┬────────────────────────┘  │
│                 │                           │
│    ┌────────────┴──────────────┐            │
│    │     Supervisord            │            │
│    │  (Process Manager)         │            │
│    └────────────┬──────────────┘            │
│                 │                           │
│  ┌──────┬───────┴───────┬──────┐            │
│  │      │               │      │            │
│  ▼      ▼               ▼      ▼            │
│ PB-1  PB-2   ...      PB-N                  │
│:30000 :30001          :30N                  │
└─────────────────────────────────────────────┘
         ▲
         │
    One Port: 25983

Configuration

Environment Variables

Variable	Default	Description
MULTIPB_PORT	25983	External port exposed from container
MULTIPB_DATA_DIR	/var/multipb/data	Data directory inside container

Port Range

Instances are assigned internal ports from 30000-39999 (up to 10,000 instances).

Data Structure

/var/multipb/data/
├── alpha/          # Instance "alpha" data
│   ├── pb_data/
│   └── pb_migrations/
├── beta/           # Instance "beta" data
└── instances.json  # Manifest mapping instances to ports

Production Deployment

Behind a Reverse Proxy

# nginx example
server {
    listen 80;
    server_name pb.yourdomain.com;
    location / {
        proxy_pass http://localhost:25983;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

# Traefik example
services:
  multipb:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.multipb.rule=Host(`pb.yourdomain.com`)"
      - "traefik.http.services.multipb.loadbalancer.server.port=25983"

Subdomain Routing

Set up wildcard DNS (*.pb.yourdomain.com) and route subdomains to paths:

server {
    server_name ~^(?<instance>.+)\.pb\.yourdomain\.com$;
    location / {
        proxy_pass http://localhost:25983/$instance/;
    }
}

Backup

# Backup all data
docker run --rm -v multipb-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/multipb-backup-$(date +%Y%m%d).tar.gz /data

# Restore
docker run --rm -v multipb-data:/data -v $(pwd):/backup \
  alpine tar xzf /backup/multipb-backup-20240113.tar.gz -C /

Healthchecks

# Container health
curl http://localhost:25983/_health

# List all instances
curl http://localhost:25983/_instances

Monitoring

# Check container health
docker ps

# View logs
docker logs multipb

# Check instance status
docker exec multipb list-instances.sh

# Check supervisord status
docker exec multipb supervisorctl status

Troubleshooting

Container won't start

docker logs multipb
docker volume inspect multipb-data
netstat -tuln | grep 25983

Instance won't start

# Check logs
docker exec multipb cat /var/log/multipb/<instance>.log
docker exec multipb cat /var/log/multipb/<instance>.err.log

# Check status
docker exec multipb supervisorctl status

# Restart instance
docker exec multipb stop-instance.sh <instance>
docker exec multipb start-instance.sh <instance>

Can't access instance

# Verify Caddy
docker exec multipb supervisorctl status caddy

# Check config
docker exec multipb cat /etc/caddy/Caddyfile

# Reload proxy
docker exec multipb reload-proxy.sh

# Test direct access
docker exec multipb curl http://localhost:30000/api/health

Development

git clone https://github.com/n3-rd/multi-pb.git
cd multi-pb
docker compose up -d --build
docker logs -f multipb

# Test commands
docker exec multipb add-instance.sh test1
docker exec multipb list-instances.sh
docker exec multipb remove-instance.sh test1

Contributing

Contributions welcome! This project prioritizes simplicity and reliability over features.

License

MIT