Use this guide when you are upgrading a self-hosted BaseBuddy install.

The setup source of truth is the selected BaseBuddy app-data backend. The default is basebuddy-data/basebuddy.config.json; Supabase/Postgres app-data installs use BaseBuddy-owned basebuddy tables. Upgrades should preserve app data and verify the content database mapping still works.

Before you change anything

1. Record the current BaseBuddy version or commit.
2. Back up BaseBuddy app data.
3. Back up the content Postgres database.
4. Confirm where production stores app data.
5. Check release notes for config schema, mapping, permission, or runtime changes.

Upgrade code and dependencies

Update your checkout or deployment image, then install dependencies:

shpnpm install

Build before putting editors back into the app:

shpnpm build

Run setup checks

From the app working directory:

shpnpm basebuddy doctor

Then open:

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

Fix any app-data, owner, auth, content database, or storage issue before asking editors to resume work.

Smoke test mapped content

After checks pass:

1. Sign in.
2. Open an existing project.
3. Confirm members and permissions still appear.
4. Open mapping and confirm the saved mapping loads.
5. Edit one safe mapped field and save.
6. Confirm publish, unpublish, and archive still require explicit actions.

Roll back if needed

If the upgrade fails, restore the previous code version and the backed-up app data. Restore the content database only if content data itself was changed and needs rollback.

Do not run old database setup scripts against the content schema as a rollback strategy. BaseBuddy never repairs upgrades by mutating your user content tables.

Related pages

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