Quick Start

Verified against starter commit e632762.

Start with Core: the customer app, durable worker, PostgreSQL, Redis, and private local object storage. Your first milestone is a complete local workflow: sign in, inspect the demo credit grant, run one mock image job, and see its private result and ledger entry. No Stripe, email, or AI provider account is needed for this local walkthrough.

Choose your starting point

You can add the other applications later. These profiles select local tools and build targets; they do not change product plans, permissions, or available API routes.

1. Prepare your machine

• Git
• Node.js >=24.22.1 <25 (the repository’s .nvmrc pins the tested version)
• pnpm 10.22.0
• Docker with Compose, running locally

2. Run Core

Run these commands in a terminal. The branch starts from the reviewed source revision so the instructions and code match.

git clone https://github.com/PansaLegrand/sushi-saas-template.git
cd sushi-saas-template
git switch -c my-saas e63276252e4b64566229cb87225afc72da6991de
export SAAS_STARTER_PROFILE=core
pnpm starter core install
pnpm starter core setup
pnpm starter core doctor
pnpm starter core demo

demo runs the read-only doctor first, seeds the local account only after it passes, and then starts Core with mock images enabled, simulated provider failures set to zero, and the local captcha disabled. Email, Slack, and Stripe are disabled for these processes; environment files stay unchanged. No commercial AI provider is contacted. Use bash/zsh or WSL for the shell commands. Ordinary pnpm starter core dev remains the normal development workflow; it does not enable this demo mode.

Keep the terminal running. Open localhost:3000/login.

Setup writes missing ignored environment files, starts PostgreSQL, Redis, and Garage, creates the local app/test and restore-drill databases, applies Drizzle migrations, and provisions the private sushi-dev bucket. Core skips Content Studio installation, environment files, database creation, and migrations. Setup is safe to rerun and never overwrites an existing environment file.

Setup checks for a working Docker daemon, Docker Compose, and ownership of ports 5432/6379 before writing environment files. Missing tools, stopped Docker, or a conflicting service stop setup with an error; resolve the reported prerequisite before retrying.

doctor is read-only: it checks tools, environment boundaries, infrastructure, migrations, storage, and ports without printing secret values. Demo runs doctor before seeding, then starts web and worker without a redundant second doctor run. Ctrl-C stops both processes.

Keep SAAS_STARTER_PROFILE=core exported in each shell used for ordinary pnpm lint or commits, so checks use the same selection after the filtered install. These export commands use a POSIX shell; in PowerShell use $env:SAAS_STARTER_PROFILE="core".

3. Reach your first working screen

1. For a new account, sign in with demo@example.test and DemoPass123!, or the DEV_SEED_PASSWORD used when it was created. An existing account keeps its original password; demo output reports it as unchanged.
2. Open Account → Credits. Find the one-time 1,000-credit demo grant in the ledger. The worker can also deliver the separate 10-credit signup grant, so a fresh balance can become 1,010. The demo grant is not a promise that the total always stays at 1,000.
3. Open Account → Profile & security to explore account settings. Your workspace and session now use the real local application.

These credentials are for local development only. The seed creates a verified reserved-domain account and repairs missing fixtures without issuing the same credit grant twice. It does not require delivery of an email. Existing demo activity can change the displayed balance.

4. Complete your first image task

1. Once startup credit grants have settled, refresh Account → Credits and note your balance. Keep the same workspace selected throughout this walkthrough.
2. Open the local image task. Keep the org query parameter that the app adds to its URL. Enter My first Sushi SaaS image task in Prompt, then select Generate image once.
3. The task may briefly show Queued for the worker… and Generating and storing the image…. Wait for Image ready. The expected result is a blue/purple SVG labeled Image generation mock containing your prompt. It is a mock response, not an AI-generated illustration.
4. Refresh the same task URL. It should recover the same task ID and image without another charge. Generate another image intentionally creates a new task and costs another five credits.
5. Open Account → Credits in the same workspace. Find one Image generation debit of −5. With no other ledger activity, the balance is your recorded baseline minus five: 1,000 → 995, or 1,010 → 1,005 after the signup grant. In Account → Files, the result appears as generated-<task ID>.svg.

The output is in the private local Garage bucket. The page displays it through a signed URL valid for 15 minutes; reopening the saved task URL obtains a new URL. A signed URL itself grants temporary access to its holder, so it is not a permanent public asset URL.

You have now exercised: authentication → workspace authorization → one five-credit spend → durable worker → private output → recoverable task UI. Free includes this image example; no subscription or --paid-examples seed is needed.

If the first run stalls

Verify the local stack

In another terminal, check the services:

curl http://localhost:3000/api/health
curl http://localhost:3000/api/ready
pnpm test:fast

Stop the dev runner with Ctrl-C before building, because development and production builds share .next:

pnpm starter core build

The build retains the root test suite and bundles the worker runtime. For the full browser workflow, follow Testing and CI Contracts; it covers real local storage and mock-provider jobs in disposable environments.

5. Make it yours

Run pnpm customize to set your product identity, appearance, and locales. Then follow Customize Your Product and Architecture and Error Contracts. Configure external services only when you reach the feature that needs them, starting with Environment Configuration.

Add applications when you need them

Stop the current dev runner before switching profiles. To add the admin console at http://localhost:3001:

export SAAS_STARTER_PROFILE=operations
pnpm starter operations install
pnpm starter operations setup
pnpm starter operations dev

Continue with Admin Console Setup for operator access and MFA; the seeded customer is not automatically an administrator.

To also add Content Studio at http://localhost:3002/admin:

export SAAS_STARTER_PROFILE=publishing
pnpm starter publishing install
pnpm starter publishing setup
pnpm starter publishing dev

Publishing provisions the separate Payload database and migrations. Keep its authentication and database separate from the SaaS; see Content Studio and Marketing.

All profiles support doctor, lint, build, and --dry-run. The unqualified pnpm run setup, pnpm dev:all, and pnpm build commands retain the complete-stack defaults when no profile is selected. For the interactive full-stack customizer, use ./scripts/setup.sh development in a shell without SAAS_STARTER_PROFILE.

Reset local demo data deliberately

pnpm dev:reset -- --dry-run
pnpm dev:reset

Preview the targets first. Reset refuses external services, requires explicit confirmation, recreates only this Compose project’s local data, reruns migrations, and reseeds unless told otherwise. Environment profiles are preserved. It is not needed for a normal restart.