Skip to main content

Quickstart

Get the starter up and running locally in under 5 minutes.

Prerequisites​

  • Node.js 20+ (LTS recommended)
  • Docker (for PostgreSQL + Redis via docker compose)
  • Stripe CLI (install) — needed for local webhook testing

Steps​

1. Clone the repository​

git clone https://github.com/YOUR_ORG/YOUR_REPO.git && cd YOUR_REPO

2. Install dependencies​

npm install

3. Start databases​

docker compose up -d postgres redis

4. Configure environment variables​

cp .env.example .env

Open .env and fill in the required values:

VariableWhat to set
JWT_SECRETA random string, minimum 32 characters
JWT_REFRESH_SECRETA different random string, minimum 32 characters
STRIPE_SECRET_KEYYour Stripe secret key (use a sk_test_... key from the Stripe dashboard)
STRIPE_WEBHOOK_SECRETSee below

You can generate JWT secrets quickly with:

openssl rand -base64 32

Stripe webhook secret: In a separate terminal, run:

stripe listen --forward-to localhost:4000/billing/webhook

Copy the whsec_... value it prints into your .env as STRIPE_WEBHOOK_SECRET. Keep this terminal open while developing.

5. Set up the database​

npx prisma migrate dev --schema=apps/api/prisma/schema.prisma
cd apps/api && npx prisma db seed && cd ../..

prisma generate runs automatically as part of migrate dev.

6. Start the dev servers​

npm run dev

This starts both the API and the frontend in parallel via Turborepo.

7. Open the app​

ServiceURL
APIhttp://localhost:4000
Swaggerhttp://localhost:4000/api/docs
Frontendhttp://localhost:5173

Test accounts​

The seed script creates three accounts you can use immediately:

EmailPasswordRole
admin@example.compassword123Super Admin
demo@example.compassword123Member
test@example.compassword123Member (E2E)

All accounts belong to the "Acme Inc" team.

Required and optional services​

STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET are required — the Zod config validator enforces them at startup and the API will not start without them. Use Stripe test keys locally. Run stripe listen --forward-to localhost:4000/billing/webhook to get a local webhook signing secret.

The following are optional and the app degrades gracefully when they are absent:

  • Resend (RESEND_API_KEY) — emails are logged to the console instead of being sent.
  • Google OAuth (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET) — Google login button is hidden when absent.
  • AWS S3 (AWS_S3_BUCKET, AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) — storage endpoints return errors when absent.
  • Redis (REDIS_URL) — background job queue is disabled; email sending falls back to synchronous.

See the Environment Variables page for the full list of configuration options.

Troubleshooting​

EADDRINUSE: address already in use :::4000​

Another process is using port 4000. Find and kill it:

lsof -ti :4000 | xargs kill

Same fix for port 5173 (frontend) or 5432 (Postgres).

Error: Environment variable not found: DATABASE_URL​

Prisma can't find your .env file. When running Prisma from the project root, use the --schema flag:

npx prisma migrate dev --schema=apps/api/prisma/schema.prisma

For seeding, run from apps/api/:

cd apps/api && npx prisma db seed && cd ../..

ECONNREFUSED localhost:5432​

PostgreSQL isn't running. Start it with Docker:

docker compose up -d postgres redis

Check it's healthy: docker compose exec postgres pg_isready -U postgres

API won't start — Zod validation error​

The API validates environment variables at startup. If you see Environment validation failed, check that your .env has all required keys:

  • DATABASE_URL — must be a valid PostgreSQL connection string
  • JWT_SECRET — minimum 32 characters
  • JWT_REFRESH_SECRET — minimum 32 characters, different from JWT_SECRET
  • STRIPE_SECRET_KEY — must start with sk_test_ or sk_live_
  • STRIPE_WEBHOOK_SECRET — must start with whsec_

Generate JWT secrets: openssl rand -base64 32

Stripe webhook returns 400​

Make sure stripe listen is running and the STRIPE_WEBHOOK_SECRET in your .env matches the whsec_... value printed by stripe listen. Restart the API after changing the secret.

npm install fails or packages missing​

Make sure you're running npm install from the project root, not from apps/api/ or apps/web/. This is a monorepo — dependencies are hoisted.

Node version errors​

This project requires Node.js 20+. Check your version: node -v