Documentation

Practical product docs for setting up, mapping, editing, and operating BaseBuddy.

Docs/Installation

Installation

Install BaseBuddy, open onboarding, and create BaseBuddy app data.

BaseBuddy installs as one self-hosted app. The simplest app-data backend is one local data folder:

textbasebuddy-data/basebuddy.config.json

BaseBuddy creates basebuddy-data/ in the folder where the app runs. Do not commit this folder. It contains local user/session data and project setup state; secrets stay in env. Onboarding can also store app data in BaseBuddy-owned Supabase/Postgres tables when you choose that option.

App data storage options explains which choice fits local setup, VPS hosting, Docker volumes, multi-instance installs, and immutable hosts.

Requirements

RequirementWhy
Node.js 22 recommendedMatches the runtime used by the repo scripts
pnpm@10.32.1Matches the lockfile and package manager metadata
A Postgres or Supabase content databaseThis is where your existing content tables live
Permission for the app to write app dataOnboarding and CLI setup create basebuddy-data/ by default, or BaseBuddy-owned Supabase/Postgres app-data tables when selected

BaseBuddy setup does not rename, reshape, or migrate your content tables. Set BASEBUDDY_AUTH_SECRET and BASEBUDDY_CONTENT_DATABASE_URL from .env.example before completing setup.

Install Locally

shpnpm install
pnpm dev

The dev server runs on port 8080.

Open:

texthttp://localhost:8080/onboarding

Finish Setup

Onboarding has a short page-by-page setup flow:

  1. Choose where to store BaseBuddy data selects basebuddy-data/ or a Supabase/Postgres app-data backend.
  2. Connect to your database shows the env keys you need in .env or your deployment environment.
  3. Prepare BaseBuddy data tables appears only for Supabase/Postgres app data.
  4. Create account on BaseBuddy creates the first local owner.
  5. Let's check the setup now verifies env values, owner account, app data, and the database connection.

When setup succeeds, BaseBuddy creates the selected app-data backend, writes the first local owner, and shows the path into the app. Database URLs, signing secrets, and storage keys remain in env.

You can also do the same setup from the CLI:

shpnpm basebuddy app-data:migrate
pnpm basebuddy app-data:check
pnpm basebuddy setup \
  --owner-email owner@example.com \
  --owner-name "Owner" \
  --owner-password "replace-with-a-strong-password"

Skip app-data:migrate and app-data:check when you use the default basebuddy-data/ folder.

For project creation, users, members, invites, permissions, mapping, sidebar, and storage mapping commands, use CLI reference.

Verify

shpnpm setup:check
pnpm basebuddy doctor

After setup is ready, sign in and open /projects. Create a project, save a mapping, then reload the app to confirm the mapping persists.