Local Development¶

Available Commands¶

# Development
npm run dev          # Start dev server at localhost:3000
npm run build        # Production build
npm run lint         # Run ESLint
npm run type-check   # TypeScript validation
npm run test         # Run tests

# Database
npm run db:generate  # Generate Prisma client
npm run db:push      # Push schema to database

# Local database
docker compose up -d   # Start local SQL Server
docker compose down    # Stop local SQL Server
docker compose logs    # View database logs

Development Workflow¶

1. Start the Database¶

docker compose up -d

This starts Azure SQL Edge (SQL Server compatible) on port 1433.

2. Start the Dev Server¶

npm run dev

The app runs at http://localhost:3000.

3. Make Changes¶

Edit files in src/
Changes hot-reload automatically
TypeScript errors show in terminal

4. Verify Before Committing¶

npm run lint         # Fix any linting errors
npm run type-check   # Fix any type errors
npm run build        # Ensure build succeeds

Database Management¶

Connection String¶

Local development uses this connection string (in .env.local):

DATABASE_URL="sqlserver://localhost:1433;database=master;user=sa;password=LocalDev123!;encrypt=true;trustServerCertificate=true"

Prisma Commands¶

# Generate client after schema changes
npm run db:generate

# Push schema to database
npm run db:push

# Open Prisma Studio (GUI)
npx prisma studio

Stage 0

Currently there are no Prisma models - only the datasource config. Models will be added in later stages.

Docker Build¶

Test the production Docker build locally:

# Build for App Runner (linux/amd64)
docker build --platform linux/amd64 -t luminarium-proof .

# Run with local database
docker run -p 3000:3000 \
  -e DATABASE_URL="sqlserver://host.docker.internal:1433;database=master;user=sa;password=LocalDev123!;encrypt=true;trustServerCertificate=true" \
  luminarium-proof

# Test health endpoint
curl http://localhost:3000/api/health

Troubleshooting¶

Database Connection Issues¶

Symptom: Cannot connect to SQL Server

Solutions:

Check Docker is running: docker ps
Check database container: docker compose ps
View logs: docker compose logs
Restart database: docker compose restart

Port Already in Use¶

Symptom: Port 3000 is already in use

Solutions:

# Find process using port 3000
lsof -i :3000

# Kill it
kill -9 <PID>

# Or use a different port
npm run dev -- -p 3001

Build Failures¶

Symptom: npm run build fails

Solutions:

Run npm run lint and fix errors
Run npm run type-check and fix type errors
Delete .next folder and rebuild: rm -rf .next && npm run build