Local setup

These steps take a freshly scaffolded project to a running dev server. They assume you ran npx create-stackblaze-app already — see Scaffold a project.

Install dependencies

Skip if you let the scaffolder run install for you.


cd my-saas-app
npm install

Configure environment


cp .env.example .env.local

Open .env.local and fill in the values. At minimum you need a database URL and an auth secret:


# Generate a 32-byte secret
openssl rand -base64 32

Paste that into BETTER_AUTH_SECRET. See Environment variables for the full list, and AI providers for the AI keys.

drizzle-kit reads from .env.local. If your DB URL is only in .env, the db:* commands below won’t see it.

Start Postgres

Using the bundled Docker Postgres (host port 5432, which .env.example already targets):


docker compose up -d

If 5432 is already taken, remap with POSTGRES_PORT=5433 docker compose up -d and update DATABASE_URL to match. Or point DATABASE_URL at any hosted Postgres instead — see Deployment → Database.

Create the test database (optional)

Only needed if you’ll run the integration tests:


docker exec stackblaze-postgres psql -U stackblaze -d stackblaze \
  -c "CREATE DATABASE stackblaze_test;"

Apply the schema

Push the Drizzle schema into your database:


npm run db:push

Start the dev server


npm run dev

Open http://localhost:3000 .

The dev server sometimes lands on port 3002 if 3000 is taken — watch the startup log for the actual URL.

Verify it works

Visit /register and create an account.
The verification email prints to your terminal (the default EMAIL_PROVIDER=console backend) — click the link from the console.
You land in the dashboard with a personal workspace already created.

That’s the baseline. To exercise billing and AI chat, continue with Your first run →.