Deployment Guide

This guide covers deploying Primo to production. Choose the deployment method that matches your needs and technical expertise.

Persistent Storage Required: Primo stores all data in a SQLite database and needs persistent disk storage to function. Traditional serverless platforms (Vercel, Netlify, Cloudflare Pages) have ephemeral file systems and won’t work.

Quick Deploy: Railway

The fastest way to deploy Primo to production.

Prerequisites

Railway account; review plan and resource pricing
Domain name (optional, Railway provides a free subdomain)

Deployment Steps

Click deploy button

Configure environment (optional)

Set environment variables if you want automated setup:

PRIMO_SUPERUSER_EMAIL
PRIMO_SUPERUSER_PASSWORD
PRIMO_USER_EMAIL and PRIMO_USER_PASSWORD: create the regular Developer account used for Primo sign-in
PRIMO_APP_URL: set the public HTTPS URL used for backend links
PRIMO_DOMAIN_PROVIDER=railway and PRIMO_RAILWAY_TOKEN: connect custom site domains from the Primo dashboard (see below). Leave these unset when you only use the Railway-generated hostname

Wait for deployment

Railway will:

Pull the Docker image
Create a persistent volume
Deploy the container
Generate a URL

Access your instance

Click the generated URL to access Primo. If you did not create a superuser through environment variables, complete the setup screen. If you did, sign in to Primo with the regular account created by PRIMO_USER_EMAIL and PRIMO_USER_PASSWORD; the superuser account is for PocketBase at /_/.

Connect site domains from the dashboard

To connect domains to sites without leaving the Primo dashboard, give Primo access to your Railway service:

In your Railway project, go to Settings → Tokens → New Project Token
Add two variables to the service, then redeploy:
- PRIMO_DOMAIN_PROVIDER = railway
- PRIMO_RAILWAY_TOKEN = the token
In the Primo dashboard, open a site’s menu and choose Assign domain. Primo attaches the domain to your Railway deployment, shows the DNS records to add at your registrar, and marks the site live once the certificate is issued.

Without these variables, connect the domain by hand:

In your Railway service, go to Settings → Networking → Custom Domain and add the domain.
Add the DNS records Railway shows at your registrar, and wait for Railway to issue the certificate.
In the Primo dashboard, choose Assign domain on the site, enter the domain, and click Mark as connected.

Verify the volume mounts at /app/pb_data before creating content. See Railway volumes for the host controls. Cost: Check Railway plan and resource pricing. Compute, volume storage, and bandwidth contribute to usage.

Railway manages the infrastructure and certificates. You still configure domains, backups, and access for your Primo instance.

VPS Deployment

Deploy to any VPS for full control over your infrastructure.

Prerequisites

VPS with Docker installed (Hetzner, DigitalOcean, etc.)
SSH access to your server
Domain name pointed to your server IP
Basic command line knowledge

Option 1: Docker Compose (Recommended)

SSH into your server

ssh user@your-server-ip

Create project directory

mkdir primo
cd primo

Create docker-compose.yml

services:
  primo:
    image: ghcr.io/primocms/primo:latest
    restart: always
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - primo-data:/app/pb_data
    environment:
      - PRIMO_APP_URL=https://your-domain.com
      # Optional: automated setup
      # - PRIMO_SUPERUSER_EMAIL=admin@example.com
      # - PRIMO_SUPERUSER_PASSWORD=${SUPERUSER_PASSWORD:?Set SUPERUSER_PASSWORD}
      # - PRIMO_USER_EMAIL=developer@example.com
      # - PRIMO_USER_PASSWORD=${USER_PASSWORD:?Set USER_PASSWORD}

volumes:
  primo-data:

Start the container

Leave the account variables commented out for browser setup. For automated setup, enable both account pairs and set distinct generated passwords in a private .env file before starting.

docker compose up -d

Verify it's running

docker compose logs -f

You should see logs indicating the server started on port 8080.

Option 2: Docker Run

For simpler setups without compose:

docker run -d \
  --name primo \
  --restart always \
  -p 127.0.0.1:8080:8080 \
  -v primo-data:/app/pb_data \
  -e PRIMO_APP_URL=https://your-domain.com \
  ghcr.io/primocms/primo:latest

Configure Reverse Proxy

The VPS examples bind port 8080 to the server’s loopback address. Run the reverse proxy on that host and expose ports 80 and 443 for public traffic. Replace your-domain.com with a hostname whose DNS points to the VPS.

Nginx
Caddy
Traefik

Install Nginx and Certbot for your operating system using the Certbot instructions. On a typical Linux installation, save this initial HTTP configuration as /etc/nginx/conf.d/primo.conf:

primo.conf

server {
    listen 80;
    server_name your-domain.com;
    client_max_body_size 32m;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_read_timeout 360s;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Test and reload Nginx, then verify the hostname reaches the instance over HTTP. Complete account setup after HTTPS is enabled.

sudo nginx -t
sudo systemctl reload nginx
curl -I http://your-domain.com/admin/

Obtain a certificate and let Certbot add HTTPS and the HTTP redirect:

sudo certbot --nginx --redirect -d your-domain.com
sudo nginx -t
sudo certbot renew --dry-run

Open https://your-domain.com/admin/ and verify the certificate before signing in. This sequence starts without certificate paths; Certbot adds them after issuance.

Caddy automatically handles SSL certificates:

your-domain.com {
    reverse_proxy localhost:8080
}

Start Caddy:

caddy run --config Caddyfile

Use an existing Traefik installation with its Docker provider, a websecure entry point, and a letsencrypt certificate resolver configured. Put Traefik and Primo on the same Docker network. Merge these labels into the Primo service from the Compose example:

services:
  primo:
    image: ghcr.io/primocms/primo:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.primo.rule=Host(`your-domain.com`)"
      - "traefik.http.routers.primo.entrypoints=websecure"
      - "traefik.http.routers.primo.tls.certresolver=letsencrypt"
      - "traefik.http.services.primo.loadbalancer.server.port=8080"

Platform-Specific Guides

Hetzner Cloud

Hetzner offers affordable VPS hosting in Europe and the US.

Choose a current VPS plan with enough memory and persistent storage for your sites

Install Docker:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Follow VPS deployment steps above
Configure firewall to allow ports 80, 443, and 22

DigitalOcean

DigitalOcean provides simple VPS hosting with excellent documentation.

Choose a current Droplet plan with persistent storage
Choose “Docker” from one-click apps (or install manually)
Follow VPS deployment steps above
Use DigitalOcean’s cloud firewalls for security

Fly.io

Fly.io bills compute and persistent volumes by usage. New accounts have a trial, not an ongoing free tier; check Fly.io pricing. Use one Machine for this single-volume SQLite deployment:

Install Fly CLI

curl -L https://fly.io/install.sh | sh

fly auth login

Create fly.toml

app = "your-app-name"
primary_region = "sjc"

[build]
  image = "ghcr.io/primocms/primo:latest"

[http_service]
  internal_port = 8080
  force_https = true

[[mounts]]
  source = "primo_data"
  destination = "/app/pb_data"

[env]
  PRIMO_APP_URL = "https://your-app-name.fly.dev"

Create volume

fly apps create your-app-name
fly volumes create primo_data --app your-app-name --region sjc --size 3

Deploy

fly deploy --app your-app-name --ha=false

Database Backups

Primo uses SQLite, stored in /app/pb_data. Back up this directory regularly.

Backups stored on the same volume do not protect against losing that volume. Keep an off-site copy and separately back up uploads stored in S3; PocketBase backups exclude S3-uploaded files.

PocketBase Automated Backups (Recommended)

PocketBase has built-in automated backups that you can configure through the admin UI. New instances back up daily at 03:00 and keep the 7 most recent backups, stored locally. To use a different schedule from the start, set PRIMO_BACKUP_CRON. To change it later, or add off-site storage, use the admin UI:

Access PocketBase Admin

Navigate to https://your-domain.com/_/ and sign in with your PocketBase superuser credentials.

Go to Settings → Backups

Click on Settings in the sidebar, then select the Backups tab.

Configure backup schedule

Set a cron expression for your backup schedule:

Daily at 2 AM: 0 2 * * *
Every 6 hours: 0 */6 * * *
Hourly: 0 * * * *
Every minute (not recommended): * * * * *

Choose backup location

Local storage: Backups saved to /app/pb_data/backups
S3-compatible storage: Configure AWS S3, Backblaze B2, or similar for off-site backups

Set retention policy

Configure how many backup files to keep. For example, retaining 7 files gives you about 7 days of history with one successful daily backup.

For production sites, configure S3-compatible storage for off-site backups. This protects against server failures.

Manual backups with Docker

Prefer PocketBase’s built-in backups for a running instance. A raw copy of pb_data must be made while Primo is stopped to keep SQLite and its associated files consistent. See PocketBase backup and restore. For the container named primo created with the Docker Run example:

backup-primo.sh

#!/usr/bin/env bash
set -euo pipefail

task_backup_path="./backups/pb_data_$(date +%Y%m%d_%H%M%S)"
mkdir -p ./backups
docker inspect --format '{{.Image}}' primo > "${task_backup_path}.image"
docker stop primo
trap 'docker start primo >/dev/null' EXIT
docker cp primo:/app/pb_data "$task_backup_path"
printf 'Backup saved to %s\n' "$task_backup_path"

This briefly stops the site. Run the script on the Docker host and copy the backup and image record off-server. For Compose, use docker compose stop primo, get its container ID with docker compose ps -aq primo, copy from that ID, and restart with docker compose start primo. Do not use docker compose down before copying: it removes the container.

Restore from a backup

For a PocketBase backup ZIP, use Settings → Backups → Restore in /_/. Test on an isolated instance before restoring production. For a raw pb_data directory made with the script above, restore into a new named volume and container. Keep the existing instance and backup until you verify the restored site. Set task_backup_path to your actual backup folder; the recorded image must still exist on the Docker host, or you must pull the same version from the registry.

set -euo pipefail
task_backup_path=./backups/pb_data_20261011_020000
task_restore_image=$(cat "${task_backup_path}.image")
test -f "$task_backup_path/data.db"

docker create --name primo-restored \
  -p 127.0.0.1:8081:8080 \
  -v primo-restored-data:/app/pb_data \
  "$task_restore_image"
docker cp "$task_backup_path/." primo-restored:/app/pb_data
docker start primo-restored

Use a new container and volume name for each restore attempt. Open http://localhost:8081/admin/ on the Docker host and check sign-in, pages, content, and uploads before switching your reverse proxy. Hostname routing may require a matching Host header or a temporary domain assignment in the isolated copy. Restore separately stored S3 media too. Docker supports copying into a stopped container.

Restoring replaces the site’s state with the backup’s state. Keep a backup of the current instance and verify the restore before routing production traffic to it.

Updating Primo

Docker Compose

# Pull latest image
docker compose pull

# Restart with new image
docker compose up -d

Docker Run

# Stop and remove old container
docker stop primo
docker rm primo

# Pull latest image
docker pull ghcr.io/primocms/primo:latest

# Start new container (same command as initial deploy)
docker run -d \
  --name primo \
  --restart always \
  -p 127.0.0.1:8080:8080 \
  -v primo-data:/app/pb_data \
  -e PRIMO_APP_URL=https://your-domain.com \
  ghcr.io/primocms/primo:latest

Keep the original environment variables and volume when recreating the container.

Always backup before updating, especially for major version changes.

Performance Optimization

Enable Gzip Compression

In your reverse proxy: Nginx:

gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml text/javascript;

Caddy:

encode gzip

Cache published assets carefully

Keep /admin, /api, and authentication traffic out of CDN caches. Use long-lived immutable caching only for assets whose URLs change when their contents change. Fixed image names, HTML, and unversioned scripts need revalidation or short cache lifetimes. For a reverse proxy, keep asset requests routed to Primo and verify the response headers after publishing. A new Nginx location block without proxy_pass would try to serve files from Nginx’s own filesystem.

Use a CDN

Point your domain through Cloudflare (free tier) for:

Global CDN
DDoS protection
SSL certificates
Caching

Security Checklist

Use strong passwords

Generate random passwords for all accounts. Never use default or simple passwords.

Enable firewall

Only allow ports 80, 443, and 22 (SSH). Block all other inbound traffic.

Keep Docker updated

Regularly update Docker and the Primo image for security patches.

Use HTTPS everywhere

Never serve Primo over HTTP in production. Use Let’s Encrypt for free SSL certificates.

Restrict SSH access

Disable password authentication
Use SSH keys only
Change default SSH port
Use fail2ban to block brute force attempts

Regular backups

Automate daily backups and store them off-server (S3, Backblaze, etc.).

Monitor logs

Check Docker logs regularly for suspicious activity:

docker compose logs -f --tail=100

Troubleshooting

See the Troubleshooting Guide for common deployment issues and solutions.

Run the CMS from source

Contributor setup

These steps run the CMS application from its source repository. To build a site locally, use CLI local development instead.

devenv (install here) or Dev Container compatible environment (VS Code)
Git

Local Development Steps:

Clone the repository

git clone https://github.com/primocms/primo.git
cd primo

Open the devenv shell

devenv shell

If you have configured direnv to automatically open the devenv shell, you may ignore this step.

Install dependencies

npm install

Build the application

npm run build

Initial build is required before starting the dev server.

Start development server

npm run dev

Access the application

Main app (dev): http://localhost:5173
Built app: http://localhost:8090
PocketBase Admin: http://localhost:8090/_

Local development is for testing only. All code and content is stored in local database under pb_data directory.

Getting Started

Building Sites

CLI

Collaboration

Content Management

Dashboard

Reference

Quick Deploy: Railway

Prerequisites

Deployment Steps

VPS Deployment

Prerequisites

Option 1: Docker Compose (Recommended)

Option 2: Docker Run

Configure Reverse Proxy

Platform-Specific Guides

Hetzner Cloud

DigitalOcean

Fly.io

Database Backups

PocketBase Automated Backups (Recommended)

Manual backups with Docker

Restore from a backup

Updating Primo

Docker Compose

Docker Run

Performance Optimization

Enable Gzip Compression

Cache published assets carefully

Use a CDN

Security Checklist

Troubleshooting

Run the CMS from source

Next Steps

Environment Variables

Troubleshooting

​Quick Deploy: Railway

​Prerequisites

​Deployment Steps

​VPS Deployment

​Prerequisites

​Option 1: Docker Compose (Recommended)

​Option 2: Docker Run

​Configure Reverse Proxy

​Platform-Specific Guides

​Hetzner Cloud

​DigitalOcean

​Fly.io

​Database Backups

​PocketBase Automated Backups (Recommended)

​Manual backups with Docker

​Restore from a backup

​Updating Primo

​Docker Compose

​Docker Run

​Performance Optimization

​Enable Gzip Compression

​Cache published assets carefully

​Use a CDN

​Security Checklist

​Troubleshooting

​Run the CMS from source

​Next Steps

Environment Variables

Troubleshooting

Quick Deploy: Railway

Prerequisites

Deployment Steps

VPS Deployment

Prerequisites

Option 1: Docker Compose (Recommended)

Option 2: Docker Run

Configure Reverse Proxy

Platform-Specific Guides

Hetzner Cloud

DigitalOcean

Fly.io

Database Backups

PocketBase Automated Backups (Recommended)

Manual backups with Docker

Restore from a backup

Updating Primo

Docker Compose

Docker Run

Performance Optimization

Enable Gzip Compression

Cache published assets carefully

Use a CDN

Security Checklist

Troubleshooting

Run the CMS from source

Next Steps