Self-Hosting VeloCMS

Why self-host VeloCMS

Most people just want the managed cloud — and that's fine. But if you have data residency requirements, a compliance mandate (GDPR, HIPAA, SOC 2 internal policy), cost-at-scale concerns, or simply the principle that your data should live on your own iron, this guide gets you to a running production instance in under 30 minutes on a $6/mo VPS. Self-hosting means full control over schema, storage, backups, and the upgrade cycle. The tradeoff is that you own the ops. VeloCMS tries to make that tradeoff genuinely worth taking.

System requirements

VeloCMS is lighter than it looks. PocketBase is a single Go binary with embedded SQLite, and the Next.js container idles at around 150MB RSS. You don't need a beefy server for a typical blog deployment.

Docker Compose quickstart

VeloCMS ships two pre-built Docker images: `velocms/velocms:latest` (Next.js 16 app) and `velocms/pocketbase:latest` (PocketBase 0.36 with the VeloCMS schema pre-loaded). You don't need the source code to run it. The Compose template at `public/install/docker-compose.yml` wires the two services together with sensible defaults — shared volume, internal DNS, and health-check ordering so PocketBase is ready before the Next.js process attempts a schema migration.

# 1. Create a working directory
mkdir velocms && cd velocms

# 2. Download the official Compose template + env example
curl -O https://velocms.org/install/docker-compose.yml
curl -O https://velocms.org/install/.env.example
cp .env.example .env

# 3. Edit .env — fill in the required secrets (see Environment Variables table below)
nano .env   # or: vim .env / code .env

# 4. Pull images and start in the background
docker compose up -d

# Verify both containers are running and healthy
docker compose ps

The full Compose file is maintained in the repo at `public/install/docker-compose.yml`. Here is the canonical structure as of the Q3 2026 release:

version: "3.9"

services:
  pocketbase:
    image: velocms/pocketbase:latest
    restart: unless-stopped
    volumes:
      - pb_data:/pb/pb_data
    ports:
      - "8090:8090"          # Expose only internally in prod; reverse-proxy to 3000
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8090/api/health"]
      interval: 10s
      timeout: 5s
      retries: 5

  velocms:
    image: velocms/velocms:latest
    restart: unless-stopped
    depends_on:
      pocketbase:
        condition: service_healthy
    ports:
      - "3000:3000"
    env_file: .env
    environment:
      POCKETBASE_URL: http://pocketbase:8090  # Internal Docker DNS — do not change

volumes:
  pb_data:

Environment variables reference

All configuration goes through environment variables — no config files, no UI settings panel for server behavior. The `.env.example` in the install bundle mirrors this table exactly. Required variables are enforced at startup; missing ones will cause the app to log a clear error and refuse to serve requests.

Single-instance vs multi-tenant mode

The choice between modes is a deployment topology decision, not a feature tier. Single-instance is a genuinely good fit for a personal blog, an agency client site, or a small business that wants one clean installation with no multi-tenancy overhead. Multi-tenant mode is for when you're building a SaaS product on top of VeloCMS — your customers get their own isolated PocketBase instances, their own subdomain, and optionally their own Stripe account via BYOK billing. Production at velocms.org runs multi-mode.

If you're unsure, start with single. You can migrate to multi later — the schema is the same, the main difference is where the PocketBase files live and how the middleware routes requests.

First admin user bootstrap

PocketBase has its own admin UI — it's the low-level control panel for the database. The first time you visit it, you'll be prompted to create a superuser. That superuser becomes the credentials you log into VeloCMS with at /login. You only get this 'create superuser' prompt once on a fresh DB, so do it before you do anything else.

# While Docker Compose is running, open the PocketBase admin UI:
open http://localhost:8090/_/

# Create your superuser email + password when prompted.
# Then log into VeloCMS:
open http://localhost:3000/login

If you'd rather bootstrap headlessly — useful in CI or automated provisioning — PocketBase also accepts credentials via environment variables on first start. The `POCKETBASE_ADMIN_EMAIL` and `POCKETBASE_ADMIN_PASSWORD` vars in your `.env` are read by the PB container during schema initialization. After first boot, changing those env vars has no effect on an existing DB; superuser management then lives entirely in the PB admin UI.

Once you're logged into the VeloCMS admin at `/admin`, optionally run the demo content seeder to populate your install with sample posts, a theme, and a few media items so the interface isn't completely empty while you're evaluating it.

# Optional: seed demo content (posts + default tenant + media placeholders)
# Run this from inside the velocms container or from the repo if you have it locally:
node scripts/seed-multi-tenant.mjs

Custom domain and TLS setup

For a single-instance deployment, point your domain's A record at your server IP and configure a reverse proxy (nginx or Caddy) to forward port 443 → 3000. Caddy is the easiest path — it handles Let's Encrypt automatically.

# Caddyfile — put in /etc/caddy/Caddyfile or your Caddy config path
yourdomain.com {
    reverse_proxy localhost:3000
}

# Caddy auto-provisions TLS via Let's Encrypt. No certbot needed.
# Reload after editing: systemctl reload caddy

For multi-tenant mode you additionally need a wildcard DNS record. The wildcard must be DNS-only (gray cloud in Cloudflare) — not proxied. Cloudflare's proxy doesn't issue wildcard certificates on the free plan, and Railway handles TLS termination for each subdomain if you deploy there.

# Add these two records in the Cloudflare DNS dashboard:
#
# Type   Name                 Content            Proxy status
# A      yourdomain.com       <server-IP>        Proxied  (orange cloud)
# A      *.yourdomain.com     <server-IP>        DNS only (grey cloud)
#
# The apex domain stays proxied (CDN + DDoS protection).
# The wildcard MUST be grey cloud — Railway or your Caddy handles TLS.

Backup strategy

PocketBase stores all data in SQLite files on disk. Backing up is straightforward: copy the `pb_data` directory while PocketBase is either stopped or using the PB backup API (which triggers a hot checkpoint). The recommended approach is a daily cron that runs `pocketbase backup` and streams the result to R2. That way your backups live separately from your primary storage and survive a server failure.

#!/usr/bin/env bash
# Daily PocketBase backup -> Cloudflare R2
# Add to crontab: 0 3 * * * /opt/velocms/backup-daily.sh

set -euo pipefail

DATE=$(date +%Y-%m-%d)
BACKUP_FILE="velocms-backup-${DATE}.zip"
PB_URL="${POCKETBASE_URL:-http://localhost:8090}"
R2_BUCKET="${R2_BUCKET_NAME:-velocms-backups}"

# Trigger PocketBase hot backup via API (requires superuser auth)
curl -s -X POST \
  -H "Authorization: ${PB_ADMIN_TOKEN}" \
  "${PB_URL}/api/backups" \
  -d "{"name":"${BACKUP_FILE}"}"

# Wait for backup to appear in PB's local backup folder, then stream to R2
# Assumes rclone is configured with the Cloudflare R2 remote named "r2"
rclone copy "${PB_DATA_DIR}/backups/${BACKUP_FILE}" "r2:${R2_BUCKET}/daily/"

echo "[backup] ${BACKUP_FILE} uploaded to R2 at $(date)"

# Prune local backups older than 7 days
find "${PB_DATA_DIR}/backups/" -name "*.zip" -mtime +7 -delete

Restore is the reverse: download the zip from R2, place it in `pb_data/backups/`, and call the PB restore API. Run a restore drill at least monthly — a backup you've never tested is a backup you don't actually have.

# Download a backup from R2:
rclone copy "r2:velocms-backups/daily/velocms-backup-2026-04-26.zip" ./restore/

# Restore via PocketBase API (while PB is running):
curl -X PUT \
  -H "Authorization: <admin-token>" \
  "${PB_URL}/api/backups/velocms-backup-2026-04-26.zip/restore"

# PocketBase will restart automatically after restore.

Updating VeloCMS

Updates are a two-step pull-and-restart. VeloCMS applies PocketBase migrations automatically on startup — you don't need to run migration scripts manually unless you're upgrading a major version that ships a breaking schema change (those are documented in the release notes with explicit pre-upgrade steps).

# 1. Pull the latest images (do this from your velocms working directory)
docker compose pull

# 2. Take a backup before upgrading (see backup strategy above)
./backup-daily.sh

# 3. Restart with the new images — zero-downtime if using a load balancer
docker compose up -d --remove-orphans

# 4. Verify the app is healthy
docker compose ps
curl -s http://localhost:3000/api/health | jq .

To pin to a specific release rather than tracking `latest`, replace the image tag in your `docker-compose.yml`. For example, `velocms/velocms:1.2.0` and `velocms/pocketbase:1.2.0`. Pinned tags are recommended for production — they let you control the upgrade window and rule out an image pull as the cause if something breaks.

Troubleshooting

Most startup failures are either a missing env var or a network reachability issue between the Next.js container and PocketBase. The Docker logs (`docker compose logs -f velocms`) are the first place to look — VeloCMS logs structured JSON errors to stdout, so `| jq .` helps parse them.

Reference appendix

Docker images

Hardware sizing quick-reference

Key file paths inside the Docker container