Support/How to configure production setup

How to configure production setup

Set up BaseBuddy app data, production secrets, content database connection, and verification checks.

Use this guide when you are moving BaseBuddy from local setup to a production app, changing hosts, or reviewing setup after an upgrade.

BaseBuddy stores app state in one selected app-data backend. The default backend is:

textbasebuddy-data/basebuddy.config.json

That file lives inside basebuddy-data/ and stores local users, sessions, projects, members, permissions, invitations, saved mappings, and sidebar layout. Auth signing, content database access, and optional storage credentials stay in env.

If the app will run on more than one server, or the host does not keep local files after deploy, choose Supabase/Postgres app data instead:

sh# same database as content, inside BaseBuddy-owned basebuddy tables
BASEBUDDY_APP_STATE_BACKEND=supabase-same-project

# or separate database for BaseBuddy app data
BASEBUDDY_APP_STATE_BACKEND=supabase-split-project
BASEBUDDY_APP_STATE_DATABASE_URL=postgresql://...

Use App data storage options for the detailed tradeoffs before setting these values.

Required production secrets:

shBASEBUDDY_AUTH_SECRET=replace-with-at-least-32-random-characters
BASEBUDDY_CONTENT_DATABASE_URL=postgresql://...

Create app data

The easiest path is the browser setup flow:

texthttps://cms.example.com/onboarding

You can also create the same app data from the CLI:

shpnpm basebuddy app-data:migrate
pnpm basebuddy app-data:check

Run those two commands only when you choose Supabase/Postgres app data. Use pnpm basebuddy app-data:sql if your runtime role cannot create schemas or tables.

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

Add these only if you want images or files in BaseBuddy:

shBASEBUDDY_SUPABASE_URL=https://your-project-ref.supabase.co
BASEBUDDY_SUPABASE_PUBLISHABLE_KEY=your-publishable-key
BASEBUDDY_SUPABASE_SECRET_KEY=your-server-key

Persist app data

If you use the default backend, make sure your production host keeps basebuddy-data/ on persistent storage. If the host rebuilds from Git and discards local files on every deploy, mount a volume or use the host's persistent file storage for that folder.

Do not deploy the editable app to Vercel, Netlify, or another immutable serverless host with the default basebuddy-data backend unless you provide durable writable storage. For those hosts, use Supabase/Postgres app data.

Do not commit live app data. It contains user/session data and project state. Secrets should stay in .env or the production host env.

Optional public env values

These are still normal environment variables because they are public app customization values:

Purpose	Env value
Allow public search indexing	`NEXT_PUBLIC_SITE_INDEXABLE=true`
Custom app name	`NEXT_PUBLIC_BASEBUDDY_APP_NAME=Your CMS Name`
Custom docs link	`NEXT_PUBLIC_BASEBUDDY_DOCS_URL=https://docs.example.com`
Custom support link	`NEXT_PUBLIC_BASEBUDDY_SUPPORT_URL=https://support.example.com`

NEXT_PUBLIC_* values are visible to the browser. Do not put secrets in them.

Restart after setup changes

After editing setup from the UI or CLI, restart only if your deployment platform requires it. BaseBuddy reads projects, permissions, mappings, and sidebar settings from the selected app-data backend at runtime.

After changing host env values, redeploy or restart the app because Next.js reads environment variables when the server starts.

Verify production

From the production working directory, run:

shpnpm basebuddy doctor

Then open:

texthttps://cms.example.com/onboarding?diagnostics=1

The diagnostics view shows whether app data exists, validates, has an owner user, has local auth configuration, and can reach the content database.

Common mistakes

Problem	What it usually means	What to do
Setup disappears after deploy	`basebuddy-data/` is on ephemeral storage	Mount persistent storage or switch to Supabase/Postgres app data
Sign-in fails for every user	The config file has no owner user or `BASEBUDDY_AUTH_SECRET` is missing	Set env, then run onboarding or `pnpm basebuddy setup` again
Mapping cannot load schemas	The content database URL is wrong or unreachable	Recopy the Postgres URL and rerun doctor
Storage checks fail	Optional Supabase storage values are incomplete	Set URL, publishable key, and server key together, or remove all three

Production BaseBuddy does not need setup scripts in your content schema. Supabase/Postgres app-data mode creates BaseBuddy-owned tables only in the basebuddy schema.