Get it running locally

1. Clone and install

Use the repository link from your purchase confirmation. Activate Node 24.18.1 before installing: nvm install then nvm use on macOS/Linux, or nvm install 24.18.1 then nvm use 24.18.1 with nvm-windows.

git clone <your-boilerplate-repo-url> my-saas
cd my-saas
# Activate the pinned Node version here, then:
node --version
corepack enable
pnpm --version
pnpm install --frozen-lockfile
pnpm run db:client:generate

Verify v24.18.1 and pnpm 11.20.0. Refresh both Prisma clients from the repository schemas before the first application start.

2. Prepare the selected providers

Choose DATABASE_PROVIDER=supabase|neon and AUTH_PROVIDER=supabase|better_auth independently. Prepare an empty database: init installs a fresh composition and does not upgrade an existing deployment or migrate between providers.

For a local first run, use http://localhost:3777 for the application URL. Better Auth must use that same origin. Supabase's Authentication → URL Configuration needs the corresponding Site URL and allowed redirect URLs; see Supabase redirect configuration. Init does not configure the hosted Auth dashboard or OAuth applications for you.

3. Run the init wizard

pnpm run init

Choose Simple for the first pass. It asks for branding, business and billing models, administrator email, providers, required credentials, scheduler, rate limits and installation inputs. Choose Advanced to configure optional services and connection limits interactively. The wizard step table lists the current order for both modes.

• Select B2C for personal Accounts or B2B for team workspaces. Billing values are subscription, one_time or hybrid.
• For Neon, choose postgres_pg_cron only after preparing its compute setting, or choose external_runner and arrange an authenticated HTTP scheduler. The wizard can offer Neon API preparation with explicit restart approval.
• Set the connection budget to the actual provider limit and maximum number of web/worker processes. Simple mode prints its assumptions; Advanced lets you change them before installation.
• Use Upstash for shared production rate limits. In-memory limits require exactly one long-lived process; the development-only choice leaves production startup blocked until rate limiting is configured.
• Choose fresh installation and keep automatic reset disabled. Existing populated targets require a separate, explicitly confirmed destructive reset.
• Review the answers, approve file generation/backups, and let init install, attest and configure the database.

Type :back at any prompt to revisit the previous section. Completed answers are saved for retry, including hidden secrets. A successful run removes the draft. The file safety reference explains generated files and backups. Do not copy .env.example over the result.

4. Start the application and scheduler

pnpm run dev

Open localhost:3777. Check /api/health for HTTP 200 and {"status":"ok"}. This is a bounded database probe, not an Auth, billing or worker readiness test.

For postgres_pg_cron, keep pnpm jobs:worker running in another terminal. PostgreSQL enqueues scheduled occurrences; the worker executes them. The generated Docker Compose profile starts separate critical and background workers. For supabase_pg_cron or external_runner, the scheduler must reach the authenticated /api/jobs/run endpoint. A hosted scheduler cannot call localhost; opening the landing page does not prove scheduled jobs are running.

Application startup validates providers, credentials and configuration. Release certification is separately enforced by pnpm run qa:release; missing release evidence does not itself prevent pnpm run dev.

5. Verify sign-in and administrator access

Simple mode defaults to EMAIL_PROVIDER=noop. It sends no email and logs only delivery metadata, so there is no sign-in link to copy from the normal console. Configure Brevo or Mailjet and a verified sender in .env.local before requesting an email, then restart Next.js. Follow Wire up the essentials.

Init stores the administrator email in app_settings.admin_email; it does not create an Auth user. Register through the application with that email. The administrator check can promote the active, enabled profile only after its verified email matches the canonical identity and configured administrator email. Checkout/onboarding may precede the normal dashboard when the selected product model requires them.

For automated verification without real email delivery:

# Start Docker first. This owns a separate disposable Supabase/Auth/PostgreSQL target.
pnpm run qa:local:gate

The runner records email inside its guarded test environment and verifies the supabase:supabase reference. It does not test or reset your hosted database and does not certify all four compositions.

If something went wrong

For failure stages, resumable database states and reset scope, see Automatic Setup. For SQL changes, follow SQL Sources & Installation; never execute fragments or use init as an upgrade tool.