Run Grout locally

This guide creates a local PostgreSQL database, applies migrations, and loads the demo company.

Check prerequisites

Install Node.js 22.18.0, npm 10.9.3, and Docker Desktop. Grout uses a dedicated PostgreSQL 16 container for each worktree.

Install and start the application

npm install
cp .env.example .env.local
npm run dev:isolated

Open http://localhost:3000.

The command applies committed migrations, provisions the restricted grout_app role, seeds an empty database, and starts the app through that role. It reuses only this worktree's disposable database. Run npm run db:local:down when you want to remove its container and volume.

Sign in with demo accounts

Signing in goes through Clerk, so set CLERK_SECRET_KEY and NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY before seeding. The seed creates each demo persona in Clerk and gives it the password in E2E_PERSONA_PASSWORD.

Without Clerk keys the seed still runs and every other part of the application works — there is simply no way to sign in, and the seed says so when it finishes.

Your Clerk instance must not have Force organization selection enabled. Grout treats somebody with no organization membership as a customer, so forcing the choice leaves every customer with a pending session and no way in.

The seed also prints a demo API key and creates an embedded form.

Explore the main workflows

1. Open /book and create a native booking
2. Open /admin and review the booking, calendar, and dispatch queues
3. Open /pro as Maria and update a job through its work states
4. Open /account as Nina and manage a booking or payment method
5. Open /docs/playground and inspect the API

Run verification

npm test
npm run test:migrations
npm run typecheck
npm run lint
npm run build
npm run test:e2e

Read Configure Grout before enabling production integrations.