This guide walks you through setting up a complete local development and preview environment for StackAudit.
Before installing StackAudit, ensure your system has the following tools installed and running:
| Requirement | Minimum Version | Notes |
|---|---|---|
| Node.js | >= 22.22.2 |
Engine requirement enforced by package.json |
| npm | >= 10.0.0 |
Included with modern Node.js distributions |
| Docker | Latest Desktop / Engine | Required to run the local Supabase Postgres instance |
| Git | >= 2.30.0 |
Required to clone the repository |
Note
The Supabase CLI is locked in package-lock.json and runs via npx supabase. You do not need to install it globally.
git clone https://github.com/nitin-kumar-code/StackAudit-Core.git
cd StackAudit-Core/stackauditImportant
All application commands, tests, and build scripts are executed from within the stackaudit/ directory.
Install the locked dependency tree using npm ci:
npm ciStackAudit uses a local Supabase stack (PostgreSQL, PostgREST, and GoTrue). Ensure Docker Desktop is open and running, then start the local database:
npx supabase startOnce started, retrieve the local credentials:
npx supabase statusYou will see output resembling:
API URL: http://127.0.0.1:54321
GraphQL URL: http://127.0.0.1:54321/graphql/v1
DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
Studio URL: http://127.0.0.1:54323
Inbucket URL: http://127.0.0.1:54324
anon key: eyJhbGciOi...
service_role key: eyJhbGciOi...
Create your local environment file:
cp .env.example .env.localOpen .env.local and fill in the SUPABASE_SERVICE_ROLE_KEY from the previous step:
# Database & API Endpoint
STACKAUDIT_DATABASE_MODE=local
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_SERVICE_ROLE_KEY=<service_role_key_from_supabase_status>
# Workspace Scope (pre-configured for demo seed)
STACKAUDIT_WORKSPACE_ORG_ID=8a775c7f-e31c-8f9b-9000-000000000001
# Demo Dataset Parameters (optional overrides)
DEMO_SEED=12345
DEMO_DATASET_DAYS=90Caution
The SUPABASE_SERVICE_ROLE_KEY has administrative access and bypasses RLS. Keep it strictly inside .env.local. Never commit it to git or prefix it with NEXT_PUBLIC_.
Initialize the database schema from the ordered migration history:
npx supabase db resetThis ensures a clean, validated schema matching the committed migration set in supabase/migrations/.
Run the automated setup script to load reference token pricing fixtures (OpenAI & Anthropic) and seed 90 days of deterministic usage, workloads, outcomes, and audit findings:
npm run setup(Alternatively, you can run npm run pricing:load followed by npm run seed).
npm run devVisit http://localhost:3000 in your browser. You will be greeted by the StackAudit dashboard with populated spend trends, workload unit economics, and anomaly alerts!
To verify your installation is running correctly:
# 1. Verify TypeScript types
npm run typecheck
# 2. Run unit tests
npm test
# 3. Run Supabase integration tests
npm run test:integration- Cause: Docker Desktop is not running.
- Fix: Launch Docker Desktop and wait until the whale icon in your menu bar shows "Engine running", then rerun
npx supabase start.
- Cause: Project placed inside
~/Documentsor~/Desktopwith iCloud Drive sync active, causing files to become "dataless" placeholders. - Fix: Move the repository to a non-synced folder (e.g.
~/Development/StackAudit-Core) and ensure free disk space > 10 GB.
- Cause: Setup ran without loading the reference pricing catalog.
- Fix: Run
npm run pricing:load.
- Cause: Migrations were not applied to the local database.
- Fix: Run
npx supabase db reset.
- Cause:
DEMO_DATASET_ENDwas set to a fixed date in the past. - Fix: Ensure
DEMO_DATASET_ENDis commented out in.env.localso the dataset terminates at today's UTC midnight, then runnpm run seed.