Quick Start

SaaS Starter is a TypeScript monorepo: Next.js (web), Hono (API), workers (BullMQ), Drizzle + PostgreSQL, Redis, and optional Docker. If you skip ahead without Postgres and Redis running, almost everything below will fail — that is normal, not a broken boilerplate.

TL;DR

1. Install Node 22+, pnpm 10+, PostgreSQL 16+, Redis 7+ (or use Docker for the databases).
2. git clone → pnpm cli init → ./setup.sh (or manual migrate + seed below).
3. Start the stack (pnpm dev or Docker Compose).
4. Check http://localhost:8000/health and open http://localhost:3000.
5. Sign in with the seeded admin (see First login), then read Configuration and Environment matrix.

What you are installing

| Path | Role | | --- | --- | | apps/web/ | Next.js 16 (App Router) — marketing, dashboard, auth UI | | apps/api/ | Hono on Node — REST, webhooks, Better Auth mount, admin APIs | | content/docs/ | Documentation content served by the web app at /[locale]/docs | | packages/db/ | Drizzle schema, migrations, seed scripts | | packages/auth/ | Better Auth configuration consumed by the API | | packages/shared/, packages/ai/, … | Plans, AI factory, storage adapters, etc. |

Authoritative folder map and conventions: Project structure.

Prerequisites

| Requirement | Version / notes | | --- | --- | | Node.js | 22+ (fnm / nvm) | | pnpm | 10+ (npm install -g pnpm) | | PostgreSQL | 16+ (local daemon or Docker volume) | | Redis | 7+; production uses separate Redis DBs for cache vs queue — see Environment matrix | | Disk | Plan for ~2 GB under node_modules after install (monorepo). | | Ports | Defaults below; free them or change your run configuration. |

Default ports

| Service | URL | | --- | --- | | Web | http://localhost:3000 | | API | http://localhost:8000 | | API health | http://localhost:8000/health (JSON; not under /api/) | | Docs (when started) | http://localhost:3002 |

Windows (WSL2) and Docker

• Prefer WSL2 with the repo on the Linux filesystem (~/projects/...), not /mnt/c/..., for native file-watch and symlink performance.
• If you use Docker Desktop, ensure WSL integration is enabled for your distro, and that docker compose works inside the same environment where you run pnpm.

One-command path (recommended)

git clone <YOUR_REPO_URL>
cd app

pnpm cli init
# alias: pnpm cli init

pnpm generate:active-modules
pnpm verify:modules

./setup.sh

pnpm dev

pnpm --filter @app/docs dev

Verify the install (commands)

From the repo root with services running:

curl -sS http://localhost:8000/health
pnpm verify:modules

• If curl fails with connection refused, the API is not listening on port 8000 — fix process manager / Docker port mapping first.
• If verify:modules fails, regenerate active modules (see wizard section above).

First login (seeded admin)

The seed script scripts/seed.ts creates a global admin when one does not already exist. Override with environment variables when you run the seed:

| Variable | Description | | --- | --- | | ADMIN_EMAIL | Email for the seeded admin account (set via env or wizard) | | ADMIN_PASSWORD | Password for the seeded admin account (set via env or wizard) |

1. Open /auth/login on the web app.
2. Sign in with those credentials.
3. Open /admin (global admin surface).
4. Change the password before sharing the environment or deploying beyond your machine.

Manual setup (when ./setup.sh is not an option)

pnpm install
cp .env.example .env
# Edit .env — at minimum DATABASE_URL, Redis URLs, AUTH_SECRET

Database:

pnpm --filter "@app/db" run migrate
pnpm --filter "@app/db" run seed

Run dev:

pnpm dev

Docker (all-in-one style):

docker compose up -d postgres redis-cache redis-queue api worker web

Service names, env files, and scaling notes: Docker & scaling. Variable names by surface: Environment matrix.

CLI commands you will reuse

From the repository root (after pnpm install), use pnpm so you run the workspace CLI in packages/cli — not a random global install:

pnpm cli init
pnpm cli add referrals
pnpm cli remove waitlist
pnpm doctor
pnpm cli deploy coolify   # see [Deployment](/deploy) for your target
# equivalent:
pnpm exec cli doctor

Reading cli doctor output

doctor prints pass/fail lines for environment and connectivity checks (exact list evolves with releases). Use it like this:

1. Run pnpm doctor after any .env change.
2. Fix the first failed check (often DATABASE_URL, Redis URL, or missing API keys) before chasing UI errors.
3. Re-run doctor until it is clean, then retry pnpm dev.

Troubleshooting

ECONNREFUSED to Postgres

• Is Postgres running? (pg_isready, Docker logs, or Windows Services.)
• Does DATABASE_URL match host, port, database, user, password?
• After fixing .env, run pnpm --filter "@app/db" run migrate again.

Redis connection errors

• Confirm the URL in .env matches how Redis is started (password, TLS, DB index).
• Cache vs queue may use different Redis logical databases or URLs — Environment matrix.
• In Docker Compose, start redis (and split variants) before api / worker.

Migrations fail

• Do not delete migration files to “fix” a bad state on a real database.
• On a throwaway dev DB, you may drop the database, recreate it, migrate, and seed again.

pnpm verify:modules fails

pnpm generate:active-modules
pnpm verify:modules

Web loads but API errors, 401, or CORS

• NEXT_PUBLIC_API_URL (web) must be the browser-reachable API origin (often http://localhost:8000 in dev).
• Session cookies and CORS are sensitive to exact origin — see Configuration and the API config schema in apps/api/src/config.ts (Zod — the source of truth for env names).

What to read next

Support

• Email: Use the contact channel from your purchase receipt
• Help hub: Help & support