Documentation

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

Docs/Configuration

Configuration

Understand BaseBuddy app data, env values, database roles, and storage settings.

BaseBuddy keeps app state in basebuddy-data/basebuddy.config.json by default. Onboarding and CLI setup create basebuddy-data/ automatically in the folder where the app runs.

The config file stores:

  • install metadata;
  • local users and signed sessions;
  • project records;
  • members, roles, permission overrides, and author scopes;
  • saved mapping and sidebar revisions;
  • invitations.

Do not commit basebuddy-data/.

You can also store BaseBuddy app data in Postgres/Supabase:

ChoiceEnvUse it when
basebuddy-dataLeave BASEBUDDY_APP_STATE_BACKEND blankYou run one BaseBuddy server and want the simplest setup.
supabase-same-projectBASEBUDDY_APP_STATE_BACKEND=supabase-same-projectYou want app data in the same Supabase/Postgres project as your content.
supabase-split-projectBASEBUDDY_APP_STATE_BACKEND=supabase-split-project plus BASEBUDDY_APP_STATE_DATABASE_URLYou want BaseBuddy app data in a separate project.

Use App data storage options for the full comparison before choosing a production backend.

The Supabase/Postgres app-data options use a BaseBuddy-owned basebuddy schema. They do not store content database passwords or storage keys in project rows.

Before creating the owner account with a Supabase/Postgres app-data backend, prepare the BaseBuddy tables:

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

If the app-data role cannot create schemas or tables, print the SQL and run it with an admin role in your database SQL editor:

shpnpm basebuddy app-data:sql

That SQL creates only basebuddy.app_state and basebuddy.audit_events.

Use CLI reference when an operator or agent needs to update config-backed users, projects, members, mapping, sidebar layout, or storage mapping metadata without opening the UI.

Content Connection

The content database URL is an env value:

shBASEBUDDY_CONTENT_DATABASE_URL=postgresql://...

Use .env for local testing and your host's environment settings in production. Do not put database URLs or service keys in basebuddy-data/basebuddy.config.json.

For production, use a restricted database role instead of the broad postgres owner. BaseBuddy checks the role name during setup and checks Postgres column update privileges when the editor opens. Fields the role cannot update become read-only.

If you choose supabase-split-project, add:

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

If your app-data database cannot create schemas automatically, run pnpm basebuddy app-data:sql or use the repository file docs/sql/basebuddy-app-state-postgres.sql.

Optional Supabase Storage

Supabase can still be used for mapped images and files. These values are only required when you want BaseBuddy to upload or browse objects in Supabase Storage:

sh# For Supabase media bucket storage.
BASEBUDDY_SUPABASE_URL=
BASEBUDDY_SUPABASE_PUBLISHABLE_KEY=
BASEBUDDY_SUPABASE_SECRET_KEY=

Optional S3-Compatible Storage

S3-compatible credentials are only required when you want mapped images or files to use an S3-style bucket:

sh# For S3 bucket storage.
BASEBUDDY_S3_ACCESS_KEY_ID=
BASEBUDDY_S3_SECRET_ACCESS_KEY=

Keep bucket policies, CORS, and public URL behavior aligned with the storage provider you choose.

Public Branding Env

These optional values are public and can be set before build:

VariablePurpose
NEXT_PUBLIC_BASEBUDDY_APP_NAMEDisplay app name
NEXT_PUBLIC_BASEBUDDY_DOCS_URLDocumentation link
NEXT_PUBLIC_BASEBUDDY_SUPPORT_URLSupport link
NEXT_PUBLIC_SITE_INDEXABLEAllows public indexing when set to true

Most self-host admin installs should keep indexing disabled.