Documentation 12 min read

PB Manager Documentation

Published: May 22, 2025 Last Updated: June 2, 2025

1. Introduction

pb-manager is a command-line interface (CLI) tool designed to simplify the management of multiple PocketBase instances on a single Linux server. It automates setup, configuration, and ongoing maintenance tasks, including process management with PM2, reverse proxying with Nginx, SSL certificate handling with Certbot, and provides an interactive dashboard for instance monitoring.

It supports Debian-based (like Ubuntu), RHEL-based (like Fedora, CentOS, Oracle Linux), and Arch-based Linux distributions by adapting Nginx configuration paths accordingly.

1.1. Why pb-manager?

Running multiple web applications, like PocketBase instances, on one server can become complex. Each instance needs:

  • Its own isolated data directory.
  • To run on a unique internal port.
  • A way to be accessed via a public domain/subdomain.
  • Process management to ensure it stays running.
  • Optionally, HTTPS for secure connections.
  • Secure and modern Nginx configuration.
  • Easy monitoring and management.

pb-manager streamlines these processes by providing a single tool to:

  • Download and manage the PocketBase executable.
  • Create, configure, and clone PocketBase instances with isolated data.
  • Automatically generate secure, modern Nginx reverse proxy configurations.
  • Integrate with PM2 for process management.
  • Automate SSL certificate acquisition and renewal using Certbot.
  • Update the core PocketBase executable and restart instances.
  • Guide or automate the creation/reset of admin accounts.
  • Offer an interactive dashboard for instance monitoring.
  • Maintain an audit log of administrative actions.
  • Perform DNS validation and provide PocketBase version notifications.
  • Update itself from GitHub.

2. How It Works

pb-manager orchestrates several components:

  1. PocketBase Executable: Downloads a PocketBase executable (latest version by default, or a specified version) and stores it in ~/.pb-manager/bin/pocketbase. All managed instances use this single binary.
  2. Instance Configuration: Details about each managed PocketBase instance (name, domain, port, data directory, HTTPS settings, etc.) are stored in ~/.pb-manager/instances.json.
  3. CLI Configuration: Global settings for pb-manager itself (default Certbot email, default PocketBase version, logging verbosity) are stored in ~/.pb-manager/cli-config.json.
  4. Version Cache: The latest fetched PocketBase version from GitHub is cached for 24 hours in ~/.pb-manager/version-cache.json.
  5. Data Isolation: Each instance gets its own data directory under ~/.pb-manager/instances_data/<instance-name>/.
  6. PM2: For each instance, pb-manager generates an entry in a PM2 ecosystem file (~/.pb-manager/ecosystem.config.js). PM2 manages the lifecycle of these PocketBase processes.
  7. Nginx: pb-manager generates a secure Nginx server block configuration file.
    • For Debian/Arch: in /etc/nginx/sites-available/ with a symlink in /etc/nginx/sites-enabled/.
    • For RHEL-based systems: in /etc/nginx/conf.d/.
  8. Certbot: If HTTPS is enabled, pb-manager can run Certbot to obtain/install Let's Encrypt SSL certificates and configure Nginx for HTTPS. It also ensures dhparam.pem exists.
  9. Superuser Management: Offers CLI-based creation of initial admin accounts and password resets.
  10. Interactive Dashboard: Uses blessed and blessed-contrib for a terminal UI.
  11. Audit Log: Records commands in ~/.pb-manager/audit.log.
  12. DNS Validation: Checks domain resolution before Certbot runs.
  13. Distro Detection: Adapts Nginx paths and Certbot commands based on the detected Linux distribution.

3. Prerequisites

Before using pb-manager, ensure the following are installed and configured:

  1. Supported Linux Distribution: Debian-based (e.g., Ubuntu), RHEL-based (e.g., Fedora, CentOS, Oracle Linux), or Arch-based.
  2. Node.js and npm: Node.js v18.x or newer is recommended.
  3. PM2: The process manager (npm install -g pm2 and sudo pm2 startup).
  4. Nginx: The web server/reverse proxy.
  5. Certbot (with Nginx plugin):
    • Debian/Ubuntu: certbot, python3-certbot-nginx
    • RHEL/Fedora: certbot, python3-certbot-nginx (often via EPEL repository)
    • Arch: certbot, certbot-nginx
  6. Essential Tools: curl, git, openssl.
  7. sudo access: All pb-manager commands require root privileges.
  8. Firewall: Ports 80 (HTTP) and 443 (HTTPS) must be open. The automated installer attempts to configure ufw or firewalld.
  9. DNS Records: For each domain/subdomain, an A (and/or AAAA) record must point to your server's public IP.

4. Installation

4.1. Automated Installation (Recommended)

The provided shell script installs pb-manager.js, its core dependencies, and configures necessary services.

  1. Ensure curl and git are installed (the script will try to install them):

    For Debian/Ubuntu

    sudo apt update && sudo apt upgrade -y && sudo apt install -y curl git sudo

    For RHEL/Fedora

    sudo dnf install -y curl git sudo

    For Arch

    sudo pacman -Syu --noconfirm curl git sudo

  2. Run the installer:

    sudo curl -fsSL https://raw.githubusercontent.com/devAlphaSystem/Alpha-System-PBManager/main/install-pb-manager.sh -o /tmp/install-pb-manager.sh && sudo bash /tmp/install-pb-manager.sh && sudo rm /tmp/install-pb-manager.sh

The installer will:

  • Check for a supported distribution.
  • Update package lists.
  • Install/verify Node.js (v18.x), npm, PM2, Nginx, Certbot, and other tools.
  • Configure PM2 to start on boot.
  • Handle WSL2 systemd configuration if needed.
  • Download pb-manager.js to /opt/pb-manager/.
  • Install Node.js dependencies for pb-manager.js in /opt/pb-manager/.
  • Create a symlink pb-manager at /usr/local/bin/pb-manager.
  • Attempt to configure ufw or firewalld.
  • Optionally run pb-manager setup.

4.2. Manual Installation

  1. Ensure all prerequisites are installed manually.
  2. Create directory and download script:
    sudo mkdir -p /opt/pb-manager
cd /opt/pb-manager
sudo curl -fsSL https://raw.githubusercontent.com/devAlphaSystem/Alpha-System-PBManager/main/pb-manager.js -o pb-manager.js
  3. Initialize npm and install dependencies for pb-manager.js:
    sudo npm init -y
sudo npm install commander inquirer@8.2.4 fs-extra axios chalk@4.1.2 unzipper shelljs blessed blessed-contrib cli-table3 pretty-bytes@5.6.0
  4. Make script executable:
    sudo chmod +x pb-manager.js
  5. Create symlink for pb-manager CLI:
    sudo ln -sfn /opt/pb-manager/pb-manager.js /usr/local/bin/pb-manager
  6. Run initial setup for pb-manager:
    sudo pb-manager setup

5. Configuration

pb-manager stores its files in ~/.pb-manager/ (typically /root/.pb-manager when using sudo).

5.1. Configuration Directory Structure

  • ~/.pb-manager/: Main configuration directory.
    • cli-config.json: Global CLI settings.
    • instances.json: Configuration for each managed instance.
    • ecosystem.config.js: PM2 ecosystem file.
    • version-cache.json: Caches latest PocketBase version info.
    • audit.log: Log of all pb-manager commands.
    • bin/:
      • pocketbase: The downloaded PocketBase executable.
    • instances_data/:
      • <instance-name>/: Data directory for each instance (contains pb_data, pb_migrations, etc.).

5.2. CLI Configuration (cli-config.json)

Managed via sudo pb-manager configure. Stores:

  • defaultCertbotEmail: Default email for Let's Encrypt.
  • defaultPocketBaseVersion: Default PocketBase version for setup.
  • completeLogging: Boolean, for verbose CLI output.

5.3. Instance Configuration (instances.json)

Stores an object where each key is an instance name. Each instance object contains:

  • name: Instance name.
  • domain: Public domain/subdomain.
  • port: Internal port number.
  • dataDir: Path to the instance's data directory.
  • useHttps: Boolean, whether HTTPS is configured.
  • emailForCertbot: Email used for this instance's certificate.
  • useHttp2: Boolean, whether HTTP/2 is enabled in Nginx.
  • maxBody20Mb: Boolean, whether client_max_body_size 20M is set in Nginx.

5.4. PM2 Ecosystem File (ecosystem.config.js)

Generated by pb-manager for PM2. Defines how each PocketBase instance is run. Example app entry:

{
  name: "pb-my-app",
  script: "/root/.pb-manager/bin/pocketbase",
  args: "serve --http \"127.0.0.1:8091\" --dir \"/root/.pb-manager/instances_data/my-app\" --migrationsDir \"/root/.pb-manager/instances_data/my-app/pb_migrations\"",
  cwd: "/root/.pb-manager/instances_data/my-app",
  autorestart: true,
  watch: false,
  max_memory_restart: "200M",
  env: { NODE_ENV: "production" }
}

5.5. Version Cache (version-cache.json)

Caches the latest PocketBase version fetched from GitHub to reduce API calls. Example: {"timestamp":1678886400000,"latestVersion":"0.28.1"}

5.6. Audit Log (audit.log)

Plain text file logging command executions. Example entry: 2025-05-22T05:30:00.000Z - Command: add; Args: my-app

6. CLI Commands

6.1. Command Overview

  PocketBase Manager (pb-manager)
  A CLI tool to manage multiple PocketBase instances with Nginx, PM2, and Certbot.

  Usage:
    sudo pb-manager <command> [options]

  Main Commands:
    dashboard                          Show interactive dashboard for all PocketBase instances
    add | create                       Register a new PocketBase instance
    clone <sourceName> <newName>       Clone an existing instance's data and config to a new one
    list [--json]                      List all managed PocketBase instances
    remove <name>                      Remove a PocketBase instance (prompts for data deletion)
    reset <name>                       Reset a PocketBase instance (delete all data, re-confirm needed)
    reset-admin <name>                 Reset the admin password for a PocketBase instance

  Instance Management:
    start <name | all>                 Start a specific PocketBase instance via PM2
    stop <name | all>                  Stop a specific PocketBase instance via PM2
    restart <name | all>               Restart a specific PocketBase instance via PM2
    logs <name>                        Show logs for a specific PocketBase instance from PM2

  Setup & Configuration:
    setup [--version]                  Initial setup: creates directories and downloads PocketBase
    configure                          Set or view CLI configurations (default Certbot email, PB version, logging)

  Updates & Maintenance:
    renew-certificates <name | all>   Renew SSL certificates using Certbot (use --force to force renewal)
    update-pocketbase                  Update the PocketBase executable and restart all instances
    update-ecosystem                   Regenerate the PM2 ecosystem file and reload PM2
    update-pb-manager                  Update the pb-manager CLI from GitHub

  Other:
    audit                              Show the history of commands executed by this CLI (includes errors)
    help [command]                     Show help for a specific command

  Run all commands as root or with sudo.

6.2. Main Commands

dashboard

  • Purpose: Shows an interactive terminal-based dashboard.
  • Usage: sudo pb-manager dashboard
  • Features: Real-time view of instances (Name, Domain, Port, PM2 Status, HTTP Health, SSL, CPU/Mem, Uptime, Data Size).
  • Hotkeys: q (Quit), r (Refresh), l (Logs for selected), s (Start/Stop selected), d (Delete selected - redirects to remove command flow).

add (alias: create)

  • Purpose: Adds and configures a new PocketBase instance.
  • Usage: sudo pb-manager add
  • Details: Interactive prompts for instance name, domain, port, Nginx options (HTTP/2, max body size), HTTPS (Certbot), and initial admin creation. Performs DNS validation if HTTPS is chosen.

clone <sourceName> <newName>

  • Purpose: Clones an existing PocketBase instance's data and configuration.
  • Usage: sudo pb-manager clone <source-instance-name> <new-instance-name>
  • Details: Copies data from source, then prompts for new configuration (domain, port, etc.) similar to add.

list [--json]

  • Purpose: Lists all managed PocketBase instances.
  • Usage: sudo pb-manager list
  • Options: --json (Output in JSON format).
  • Output: Name, Domain, Protocol, Public URL, Internal Port, Data Directory, PM2 Status, Local Admin URL, SSL Expiry.

remove <name>

  • Purpose: Removes a managed PocketBase instance.
  • Usage: sudo pb-manager remove <instance-name>
  • Details: Confirms action. Stops/deletes PM2 process, removes Nginx config. Prompts for optional deletion of the data directory. Requires typing instance name to confirm.

reset <name>

  • Purpose: Resets an instance to a clean state. DESTRUCTIVE: DELETES ALL INSTANCE DATA.
  • Usage: sudo pb-manager reset <instance-name>
  • Details: Requires typing instance name to confirm. Deletes data directory, recreates it empty, updates PM2, and optionally creates a new admin.

reset-admin <name>

  • Purpose: Resets the password for a superuser (admin) account.
  • Usage: sudo pb-manager reset-admin <instance-name>
  • Details: Prompts for admin email and new password.

6.3. Instance Management

start <name | all>

  • Purpose: Starts a specific instance or all instances via PM2.
  • Usage: sudo pb-manager start my-app or sudo pb-manager start all

stop <name | all>

  • Purpose: Stops a specific instance or all instances via PM2.
  • Usage: sudo pb-manager stop my-app or sudo pb-manager stop all

restart <name | all>

  • Purpose: Restarts a specific instance or all instances via PM2.
  • Usage: sudo pb-manager restart my-app or sudo pb-manager restart all

logs <name>

  • Purpose: Shows logs for a specific instance from PM2 (tails logs).
  • Usage: sudo pb-manager logs my-app (Ctrl+C to exit)

6.4. Setup & Configuration Commands

setup [--version]

  • Purpose: Initial setup. Creates directories and downloads PocketBase executable.
  • Usage: sudo pb-manager setup
  • Options: -v, --version <version> (e.g., 0.28.1). Defaults to latest or version in cli-config.json.

configure

  • Purpose: Set or view global CLI configurations.
  • Usage: sudo pb-manager configure
  • Details: Interactive menu for Default Certbot Email, Default PocketBase Version, and Complete Logging.

6.5. Updates & Maintenance Commands

update-pocketbase

  • Purpose: Updates the core PocketBase executable and restarts all instances.
  • Usage: sudo pb-manager update-pocketbase
  • Details: Runs PocketBase's built-in update command, then restarts all managed instances.

renew-certificates [instanceName|all]

  • Purpose: Renews SSL certificates using Certbot.
  • Usage: sudo pb-manager renew-certificates or sudo pb-manager renew-certificates my-app or sudo pb-manager renew-certificates all
  • Options: --force (Force renewal even if not due).
  • Details: Reloads Nginx after renewal attempts.

update-ecosystem

  • Purpose: Regenerates the PM2 ecosystem file and reloads PM2.
  • Usage: sudo pb-manager update-ecosystem

update-pb-manager

  • Purpose: Updates pb-manager CLI itself from GitHub.
  • Usage: sudo pb-manager update-pb-manager
  • Details: Downloads latest pb-manager.js, overwrites current script, and prompts to reinstall Node.js dependencies.

6.6. Other Commands

audit

  • Purpose: Displays the audit log (~/.pb-manager/audit.log).
  • Usage: sudo pb-manager audit

help [command]

  • Purpose: Shows help for pb-manager or a specific command.
  • Usage: sudo pb-manager help or sudo pb-manager help add

7. Core Features & Concepts

7.1. Superuser (Admin) Account Creation

When adding, cloning, or resetting an instance, pb-manager offers to create the superuser (admin) account via CLI using: pocketbase superuser create "<email>" "<password>" --dir "<instance_data_dir>" --migrationsDir "<instance_data_dir>/pb_migrations" If skipped, create it via the web UI at https://your-domain.com/_/ or http://127.0.0.1:<instance_port>/_/.

7.2. Nginx Configuration

  • Distro Aware: Uses correct paths for Debian/Arch (sites-available, sites-enabled) and RHEL (conf.d).
  • HTTP/2: Optionally enabled per instance.
  • Security Headers: Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options, X-XSS-Protection.
  • Upload Limit: Optionally client_max_body_size 20M.
  • HTTPS: Full Certbot integration, HTTP to HTTPS redirect.
  • DH Parameters: Ensures ssl-dhparam.pem exists, generating if needed.

7.3. Logging (CLI & Instance)

  • CLI Verbosity: Toggle detailed command output via sudo pb-manager configure (Enable complete logging).
  • Instance Logs: View with sudo pb-manager logs <name> or directly with pm2 logs pb-<name>.

7.4. PocketBase Version Notification

Before most commands, pb-manager checks (using a 24h cache) if a newer PocketBase version is available on GitHub and notifies you.

7.5. DNS Validation

When adding an instance with HTTPS, pb-manager attempts to verify that the domain's A/AAAA records point to your server's public IP before running Certbot.

7.6. Distribution Support

The installation script and pb-manager CLI adapt behavior (primarily Nginx paths and package manager commands) for:

  • Debian-based systems (e.g., Ubuntu) using apt.
  • RHEL-based systems (e.g., Fedora, CentOS, Oracle Linux) using dnf.
  • Arch-based systems using pacman.

7.7. WSL2 Support

The install-pb-manager.sh script detects if running under WSL2. If systemd is not enabled (which is common by default and needed for services like Nginx and PM2 to auto-start correctly within WSL2), it will prompt the user and offer to add the necessary configuration (systemd=true under [boot]) to /etc/wsl.conf. This change requires a full WSL shutdown (wsl --shutdown from PowerShell/CMD) and restart.

8. Important Notes

8.1. Sudo Usage

All pb-manager CLI commands MUST be run as root or with sudo. This is required for managing system services, files in protected locations, and network configurations.

8.2. DNS Configuration

Correct DNS A (and/or AAAA) records pointing to your server's public IP are critical. Ensure propagation before setup.

8.3. Backups

pb-manager DOES NOT handle data backups. Implement your own strategy for backing up:

  • Instance data: ~/.pb-manager/instances_data/
  • Configuration files: ~/.pb-manager/cli-config.json, ~/.pb-manager/instances.json, ~/.pb-manager/ecosystem.config.js.

8.4. Security Considerations

  • Use strong, unique passwords for PocketBase admin accounts.
  • Keep your server OS and all software (Nginx, PM2, Node.js, PocketBase) updated.
  • Review Nginx configurations.
  • Regularly review the audit log (sudo pb-manager audit).

9. Potential Issues & Troubleshooting

  • Dependency Conflicts: Check versions of Node.js, PM2, Nginx, Certbot.
  • Nginx Errors: Test with sudo nginx -t. Check Nginx error logs (e.g., /var/log/nginx/error.log).
  • Certbot Failures: Check DNS, rate limits, firewalls, Nginx plugin. Logs in /var/log/letsencrypt/.
  • PM2 Problems: Check pm2 logs for specific instances or PM2's main log.
  • Permissions: sudo usually handles this. If manual changes were made, check ownership/permissions.
  • PocketBase Updates: Review PocketBase release notes for breaking changes.
  • Data Loss Risk:
    • remove prompts for data deletion.
    • reset is highly destructive.
    • ALWAYS BACK UP YOUR DATA INDEPENDENTLY.
  • Network Connectivity: Required for downloads.
  • Resource Limits: Monitor server CPU/memory if running many instances.

10. Disclaimer

This tool is provided as-is, without any warranty, express or implied. The user assumes all responsibility and risk for the use of this software. Always back up critical data before performing any operations, especially remove or reset.