Skip to main content

How to Set Up Local Development

Set up a complete local development environment for AuditSwarm.

Prerequisites​

  • Node.js 18.17+ installed
  • pnpm 9.0+ installed (npm install -g pnpm)
  • Git
  • Google Cloud SDK (gcloud) - for Cloud SQL Proxy

Step 1: Clone the Repository​

git clone https://github.com/your-org/auditswarm.git
cd auditswarm

Step 2: Install Dependencies​

pnpm install

Step 3: Configure Environment Variables​

cp .env.example .env

Edit .env:

# Database (use localhost with Cloud SQL Proxy)
DATABASE_URL="postgresql://postgres:PASSWORD@localhost:5432/auditswarms"

# NextAuth
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="generate-with-openssl-rand-base64-32"

# OAuth (optional for local dev)
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# Encryption
ENCRYPTION_KEY="generate-with-openssl-rand-base64-32"

Step 4: Authenticate with Google Cloud​

Local development requires the Cloud SQL Proxy to connect to the production database:

# Authenticate with gcloud (required for Cloud SQL Proxy)
gcloud auth login

# Set the correct project
gcloud config set project reference-node-476016-q2

Step 5: Start Development Servers​

# Start both web app (port 3000) and MCP server (port 8080)
# This automatically starts Cloud SQL Proxy
pnpm dev:all

How it works:

  • Cloud SQL Proxy runs automatically and connects to reference-node-476016-q2:us-central1:auditswarms-db
  • Proxy listens on localhost:5432
  • DATABASE_URL in .env should use localhost:5432, NOT the direct Cloud SQL IP

Or start separately:

pnpm --filter @auditswarm/web dev     # Web app only
pnpm --filter @auditswarm/mcp dev     # MCP server only

Step 6: Verify Setup​

Open http://localhost:3000 and verify:

Troubleshooting​

Database Connection Errors​

Problem: "Can't reach database server at localhost:5432" or "Authentication failed"

Most Common Cause: gcloud auth token expired

Solution:

# Check if token is expired
gcloud projects list  # If this fails, your token is expired

# Re-authenticate (WSL/Linux without browser)
gcloud auth login --no-launch-browser
# Copy the URL to your browser, complete sign-in, paste the code back

# Set the correct project
gcloud config set project reference-node-476016-q2

# Kill old proxy and restart
pkill -f cloud-sql-proxy

# Restart dev servers
pnpm dev:all

Cloud SQL Proxy Not Running​

Problem: Database connections fail but token is valid

Solution:

# Check if proxy is running
ps aux | grep cloud-sql-proxy
# Should show: /tmp/cloud-sql-proxy -instances=reference-node-476016-q2:us-central1:auditswarms-db=tcp:5432

# Check proxy logs
cat /tmp/cloud-sql-proxy.log

# If you see "Reauthentication failed", re-authenticate gcloud

Prisma Client Errors​

Problem: Prisma client import errors

Solution:

pnpm --filter @auditswarm/database prisma:generate

Wrong DATABASE_URL Format​

Problem: Connection works but login fails

Solution: Verify DATABASE_URL uses localhost (proxy), not direct IP:

# Correct:
DATABASE_URL="postgresql://postgres:PASSWORD@localhost:5432/auditswarms"

# Wrong:
DATABASE_URL="postgresql://postgres:PASSWORD@34.70.50.142:5432/auditswarms"

Database Management​

# Generate Prisma client
pnpm --filter @auditswarm/database prisma:generate

# Run migrations
pnpm --filter @auditswarm/database prisma:migrate

# Open database GUI
pnpm --filter @auditswarm/database prisma:studio

# Seed custom lists
pnpm seed:custom-lists

# Verify custom lists
pnpm verify:custom-lists

Next Steps​