Use this guide when you want to run BaseBuddy on your own VPS with Docker and an HTTPS reverse proxy.

The public BaseBuddy app repo does not need setup scripts in your content schema. By default, it needs a persistent basebuddy-data/ folder in the running app. If you prefer database-backed app data, use Supabase/Postgres app data instead.

Before you start

You need:

• a VPS with Docker;
• HTTPS proxying to the app container;
• env values for BASEBUDDY_AUTH_SECRET and BASEBUDDY_CONTENT_DATABASE_URL;
• optional Supabase Storage env values for mapped media or file fields;
• a Docker volume for basebuddy-data/, unless you use Supabase/Postgres app data.

Build the image

Use your own Dockerfile or deployment scaffolding around the repo scripts:

shpnpm install --frozen-lockfile
pnpm build
pnpm start

Expose port 8080 inside the container.

Mount persistent setup storage

If you use the default backend, mount a volume so this folder survives container replacement:

text/app/basebuddy-data

Make sure the app can write this folder and your deployment does not replace it with an empty folder.

For database-backed app data, set:

shBASEBUDDY_APP_STATE_BACKEND=supabase-same-project

or:

shBASEBUDDY_APP_STATE_BACKEND=supabase-split-project
BASEBUDDY_APP_STATE_DATABASE_URL=postgresql://...

Create setup

After the container is running, open:

texthttps://cms.example.com/onboarding

Or run inside the container:

shpnpm basebuddy setup \
  --owner-email "owner@example.com" \
  --owner-name "Owner" \
  --owner-password "choose-a-strong-password"

Verify

Run:

shpnpm basebuddy doctor

Then test sign-in, project creation, mapping save, reload persistence, and one safe mapped content edit.

Common issues

Related pages

• Deployment
• Operations
• Production readiness
• How to run setup checks after deployment or upgrade