Prerequisites

Bun 1.3+
Postgres
Git
A configured .env file or .env.local file

Optional but useful:

Stripe CLI for billing webhook validation
Supabase CLI when resetting a linked Supabase database
Docker Compose for the portable self-host stack

1. Install Dependencies

bun install

2. Configure Environment

cp .env.example .env

For local development, update at least:

NEXT_PUBLIC_BASE_URL
DATABASE_URL
BETTER_AUTH_SECRET
SCIM_CREDENTIAL_HASH_SECRET
BETTER_AUTH_TRUSTED_ORIGINS

Generate two different local secrets, then paste one into each matching variable:

openssl rand -hex 32 # BETTER_AUTH_SECRET
openssl rand -hex 32 # SCIM_CREDENTIAL_HASH_SECRET

Recommended local baseline:

NODE_ENV=development
NEXT_PUBLIC_BASE_URL=http://localhost:3080
DATABASE_URL=postgresql://user:password@localhost:5432/yayaw
BETTER_AUTH_SECRET=<first-generated-secret>
SCIM_CREDENTIAL_HASH_SECRET=<second-generated-secret>
BETTER_AUTH_TRUSTED_ORIGINS=http://localhost:3080

Production uses https://yayaw.app as the canonical NEXT_PUBLIC_BASE_URL. Use BETTER_AUTH_TRUSTED_ORIGINS only for extra preview/local origins; the canonical host and www variant are derived automatically.

For provider-specific setup, use:

Environment Variables for the full variable list
Deployment Environment Setup for where to retrieve production values

3. Initialize Database and Seed

bun run setup

setup runs:

Better Auth schema generation
generated Drizzle server actions
DB push
seed data

Run it again after schema or seed changes when you need local parity.

4. Start the Development Server

bun run dev

The app runs on http://localhost:3080.

5. Common Local Commands

bun run db:push
bun run seed
bun run docs:generate
bun run docs:llm:generate

Use bun run db:reset only when you intentionally want to reset a linked local database and reseed it. This command expects the Supabase CLI to be installed on your machine through Homebrew, Scoop, or the standalone binary rather than the project's npm dependencies.

Use the self-host compose stack when you want local parity with the portable runtime instead of a hosted provider:

Follow the complete Self-Hosting quick start. It generates all required, distinct Better Auth, SCIM, database, storage, and CMS secrets before the first image build.

The app is served through Caddy on http://localhost:8080, with Postgres, MinIO/S3 storage, and the Page AI DB worker running as separate services.

Quality Commands

bun run check
bun run docs:generate
bun run docs:check-links
bun run docs:check-translations
bun run docs:llm:check
bunx tsc --noEmit
bun run build

For billing work, also run:

bun run test

Branch Workflow

Start feature work from an updated main:

git checkout main
git pull --ff-only origin main
git checkout -b codex/<short-task-name>

Keep every task in its own branch and pull request. Do not mix generated docs, feature changes, and unrelated local experiments unless the task explicitly requires it.

Quickstart