Deploying PocketBase on a VPS for

Configuration

After installing PocketBase and Caddy, you need to configure them to work together. The main task is to set up Caddy as a reverse proxy for PocketBase and ensure a secure HTTPS connection.

1. Configuring the Caddyfile

Caddy uses a configuration file called Caddyfile. We will edit it to route traffic to PocketBase.

sudo nano /etc/caddy/Caddyfile
    

Replace the entire file content with the following, specifying your domain (e.g., api.example.com). If you don't have a domain, you can use an IP address, but HTTPS will only work with a domain.

your_domain.com {
    reverse_proxy localhost:8090
    handle_errors {
        respond "{err.status_code} {err.status_text}"
    }
}
    

Save the file (Ctrl+X, Y, Enter).

This config tells Caddy:

• Listen for requests for your_domain.com (or your IP if there's no domain).
• Automatically obtain and renew HTTPS certificates for this domain.
• Forward all incoming requests to localhost:8090, where PocketBase is running.
• Handle errors by returning a standard HTTP status.

2. Applying Caddy Configuration

After modifying the Caddyfile, you need to reload the Caddy service for the changes to take effect.

sudo systemctl reload caddy        # Reload Caddy configuration
sudo systemctl status caddy        # Check Caddy status
    

Ensure that Caddy is active and successfully reloaded.

3. Initial PocketBase Launch and Admin User Creation

PocketBase is now accessible via your domain. Open your browser and navigate to https://your_domain.com/_/. This is the path to the PocketBase admin panel. Upon first access, you will be prompted to create an administrator user. This is a critical step for managing your database and API.

Enter your desired email and password for the admin. After creation, you will be redirected to the PocketBase control panel.

4. Configuring Secrets via Environment Variables (Optional, but Recommended)

For more secure storage of sensitive data, such as API keys or other secrets, use environment variables. PocketBase supports them. You can edit the systemd service file:

sudo nano /etc/systemd/system/pocketbase.service
    

Add the line Environment="YOUR_SECRET_KEY=your_value" to the [Service] section.

[Service]
...
Environment="[email protected]"
Environment="POCKETBASE_APP_URL=https://your_domain.com"
# Add your variables:
Environment="MY_CUSTOM_API_KEY=supersecretkey123"
ExecStart=/opt/pocketbase/pocketbase serve --http "0.0.0.0:8090" --dir "/opt/pocketbase/pb_data"
...
    

After saving the file, remember to reload systemd and the PocketBase service:

sudo systemctl daemon-reload
sudo systemctl restart pocketbase
    

Inside PocketBase, you will be able to access these environment variables through code or, if supported, through plugin settings.

5. Verifying Functionality

You can verify the functionality of PocketBase and Caddy in several ways:

• Via browser: Open https://your_domain.com (for API) and https://your_domain.com/_/ (for the admin panel).
• Via curl:

curl -v https://your_domain.com/api/health # Check PocketBase API status
    

You should receive an HTTP 200 OK and a JSON response from PocketBase. If you see errors or cannot connect, check the Caddy logs (sudo journalctl -u caddy --since "1 hour ago") and PocketBase logs (sudo journalctl -u pocketbase --since "1 hour ago").

Backups and Maintenance

Backups are a critically important part of any production service. PocketBase stores all its data in a single SQLite file (data.db) and optionally in the files directory, which significantly simplifies the backup process.

1. What to Back Up

• Database: /opt/pocketbase/pb_data/data.db – this is the main SQLite file containing all your collections, records, users, and settings.
• Files: If you use PocketBase for file storage, they will be located in the /opt/pocketbase/pb_data/files/ directory. Backing up this directory is mandatory.
• PocketBase Configuration: Although PocketBase does not have a complex configuration file, any changes to the code (if you use custom hooks or plugins) or to the systemd service file (/etc/systemd/system/pocketbase.service) should also be saved.
• Caddy Configuration: /etc/caddy/Caddyfile – for quick reverse proxy recovery.

2. Simple Auto-Backup Script

We will create a simple script that will archive PocketBase data, save it to a temporary location, and then synchronize it with remote storage. For example, we will use tar and rclone (which will need to be installed and configured for S3 or another cloud storage).

# Install rclone if not already installed
# sudo apt install rclone -y
# rclone config # Configure S3-compatible storage or another provider

sudo nano /usr/local/bin/backup_pocketbase.sh
    

Paste the following script, replacing your_new_user and your_rclone_remote (the name of your configured rclone storage).

#!/bin/bash

# Paths
POCKETBASE_DIR="/opt/pocketbase"
PB_DATA_DIR="${POCKETBASE_DIR}/pb_data"
BACKUP_DIR="/tmp/pocketbase_backups"
RCLONE_REMOTE="your_rclone_remote:pocketbase-backups" # Example: s3_valebyte:pocketbase-backups
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_ARCHIVE="${BACKUP_DIR}/pocketbase_backup_${DATE}.tar.gz"
LOG_FILE="/var/log/pocketbase_backup.log"

# Create temporary backup directory if it doesn't exist
mkdir -p "${BACKUP_DIR}"

# Logging
echo "--- Backup started at $(date) ---" >> "${LOG_FILE}"

# Stop PocketBase to ensure DB integrity
echo "Stopping PocketBase service..." >> "${LOG_FILE}"
sudo systemctl stop pocketbase
sleep 5 # Give time to stop

# Create archive
echo "Creating backup archive: ${BACKUP_ARCHIVE}" >> "${LOG_FILE}"
sudo tar -czf "${BACKUP_ARCHIVE}" -C "${POCKETBASE_DIR}" pb_data >> "${LOG_FILE}" 2>&1

# Start PocketBase
echo "Starting PocketBase service..." >> "${LOG_FILE}"
sudo systemctl start pocketbase

# Copy archive to remote storage using rclone
echo "Uploading backup to remote: ${RCLONE_REMOTE}" >> "${LOG_FILE}"
rclone copy "${BACKUP_ARCHIVE}" "${RCLONE_REMOTE}" >> "${LOG_FILE}" 2>&1

# Delete old local backups (keep the last 7 days)
find "${BACKUP_DIR}" -type f -name ".tar.gz" -mtime +7 -delete >> "${LOG_FILE}" 2>&1
echo "Old local backups cleaned." >> "${LOG_FILE}"

echo "Backup finished at $(date)" >> "${LOG_FILE}"
echo "---" >> "${LOG_FILE}"
    

sudo chmod +x /usr/local/bin/backup_pocketbase.sh
    

sudo crontab -e
    

0 3    /usr/local/bin/backup_pocketbase.sh >> /var/log/cron.log 2>&1
    

Save and close the file. Now your data will be backed up regularly.

4. Where to Store (External S3 / Separate VPS)

It is crucial to store backups separately from the main server. This will protect you from data loss in case of a VPS failure or other disasters. Recommended options:

• S3-compatible storage: Amazon S3, DigitalOcean Spaces, Backblaze B2, MinIO. These are reliable and relatively inexpensive solutions.
• Separate VPS: You can set up a second, less powerful VPS exclusively for storing backups and use rsync or SCP to transfer files.
• NAS/Local Storage: For personal projects, you can use a home NAS or cloud storage synchronized with a local machine.

5. Updates: Rolling vs. Maintenance Window

• PocketBase Update: PocketBase does not have a built-in update mechanism via a package manager. To update, you need to download the new executable from GitHub, stop the service, replace the old file with the new one, and then start the service. This can be done during a "maintenance window" to minimize downtime.

  
  # Example commands for updating PocketBase
  sudo systemctl stop pocketbase
  # Download the new version, as in step 6.1, but to /tmp, then:
  # sudo cp /tmp/pocketbase_new_version /opt/pocketbase/pocketbase
  sudo systemctl start pocketbase
              

• Caddy and OS Updates: Caddy, like other system packages, is updated via the Ubuntu package manager. Regularly run sudo apt update && sudo apt upgrade -y to keep the system and Caddy up to date. These updates can usually be performed without stopping services, but sometimes a reboot is required to apply kernel updates.

Always test updates on a staging server, if possible, before applying them to production.

Troubleshooting + FAQ

PocketBase Does Not Start or Is Inaccessible

What to check: Make sure the PocketBase service is running (sudo systemctl status pocketbase). Check the service logs (sudo journalctl -u pocketbase --since "1 hour ago"). Ensure that port 8090 is not occupied by another process (sudo lsof -i :8090) and that UFW allows outgoing connections for PocketBase.

How to fix: If the service has crashed, the logs will show the reason. Common issues: incorrect path to the executable, incorrect permissions for the pb_data directory, port conflict. Ensure that the user under which PocketBase is running (specified in pocketbase.service) has read/write permissions to /opt/pocketbase/pb_data.

HTTPS Not Working or Domain Not Opening

What to check: Check Caddy's status (sudo systemctl status caddy) and its logs (sudo journalctl -u caddy --since "1 hour ago"). Ensure that your domain correctly points to the VPS IP address (A-record in DNS). Verify that UFW allows ports 80 and 443. Make sure the correct domain is specified in the Caddyfile and there are no typos.

How to fix: Common issues: DNS record not updated (wait), typo in the domain, Caddy cannot obtain a certificate due to incorrect DNS or firewall configuration. Try temporarily disabling UFW (sudo ufw disable) for diagnosis, then re-enable it.

What is the minimum suitable VPS configuration?

For small projects, prototypes, or personal needs, PocketBase can run even on a VPS with 1 vCore CPU, 1 GB RAM, and 20-25 GB SSD. This is sufficient for PocketBase itself and the operating system. However, if you plan to store many files or anticipate even a small amount of traffic, 2 vCore CPU, 2 GB RAM, and 50 GB NVMe SSD are recommended for better database performance and overall system responsiveness.

What to choose — VPS or dedicated for this task?

For deploying PocketBase, a VPS is sufficient in the vast majority of cases. PocketBase is very efficient and does not require huge resources. Dedicated servers are only needed for very large projects with high loads (millions of requests per day), specific isolation requirements, or when many other resource-intensive services are running simultaneously on the server. For most developers and small/medium businesses, a VPS will be the optimal choice in terms of price/performance ratio.

How to update PocketBase to a new version?

Updating PocketBase is done manually. You need to stop the PocketBase service (sudo systemctl stop pocketbase), download the new version of the executable from the official GitHub repository, replace the old file in /opt/pocketbase/ with the new one, and then restart the service (sudo systemctl start pocketbase). Always back up the pb_data folder before updating in case of unforeseen compatibility issues.

Where is PocketBase data stored?

All PocketBase data is stored by default in the directory specified when launching with the --dir flag. In our case, this is /opt/pocketbase/pb_data/. Inside this directory, you will find the SQLite database file data.db and, if you use PocketBase's file storage features, a subdirectory files/.

How to change the port PocketBase runs on?

The PocketBase port can be changed in the systemd service file: /etc/systemd/system/pocketbase.service. Find the line ExecStart=/opt/pocketbase/pocketbase serve --http "0.0.0.0:8090" --dir "/opt/pocketbase/pb_data" and change 8090 to the desired port. After saving the file, run sudo systemctl daemon-reload and sudo systemctl restart pocketbase. Don't forget to also update your Caddy configuration if you are using it as a reverse proxy, so it points to the new port.

Conclusion and Next Steps

Congratulations! You have successfully deployed PocketBase on your VPS, configured secure HTTPS access with Caddy, and set up a basic backup system. You now have a powerful, flexible, and fully controlled backend for your applications, allowing you to quickly create and iterate on ideas.

Here are some next steps you can take to further develop your project:

• Custom Domain Setup: If you haven't already, link your own domain to the VPS and update your Caddyfile to use it for your PocketBase instance.
• Frontend Integration: Start developing your web or mobile frontend using PocketBase client SDKs (JavaScript, Dart/Flutter) or directly via the REST/Realtime API.
• Monitoring and Logging: Set up a monitoring system (e.g., Prometheus + Grafana) to track the performance of your VPS and PocketBase, as well as centralized logging for more effective problem detection and troubleshooting.
• Scaling: As your project grows, explore horizontal scaling options (e.g., using SQLite replicas or migrating to a more powerful database if PocketBase adds such support in the future) or vertical scaling by upgrading your VPS plan.