​

Full Environment Setup Guide

​

Prerequisites

​

Required Software

1. Node.js + npm
   • Version: Node.js 18.x or later
   • Download: https://nodejs.org/
   • Verify: node -v and npm -v
2. Python
   • Version: Python 3.8 or later
   • Download: https://www.python.org/downloads/
   • Verify: python --version
   • Ensure Python is added to PATH during installation
3. Google Cloud SDK (gcloud)
   • Optional but recommended for GCP operations
   • Download: https://cloud.google.com/sdk/docs/install

​

Service Account Credentials

• Option 1: Place credentials.json in the project root directory
• Option 2: Use Application Default Credentials (ADC)
  • Run: gcloud auth application-default login
  • Credentials will be stored in your user profile

​

One-Time Setup

​

1. Place Credentials File (if using service account JSON)

payroll-pipeline-cbs/
  credentials.json  <-- Place your service account JSON here
  ...

​

2. Environment Variables

• GCP_PROJECT_ID: Defaults to payroll-bi-gauntlet if not set
• GOOGLE_APPLICATION_CREDENTIALS: Set automatically if credentials.json exists in project root
• GCP_REGION: Defaults to us-central1 (for Vertex AI)
• VERTEX_MODEL: Optional (code handles defaults)

​

Commands

​

Bootstrap Virtual Environment

powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap-venv.ps1

• Creates ./venv directory if it doesn’t exist
• Activates virtual environment
• Upgrades pip
• Installs dependencies from requirements-api.txt
• Validates imports (fastapi, uvicorn, google.cloud.bigquery, vertexai)

[BOOTSTRAP] Virtual environment created successfully
[BOOTSTRAP] Dependencies installed successfully
[BOOTSTRAP] ✓ fastapi imported successfully
[BOOTSTRAP] ✓ uvicorn imported successfully
[BOOTSTRAP] ✓ google.cloud.bigquery imported successfully
[BOOTSTRAP] Venv bootstrap complete and dependencies validated.

​

Start Backend

.\start-backend.bat

powershell -ExecutionPolicy Bypass -File .\scripts\start-backend.ps1

• Checks for virtual environment (prompts to bootstrap if missing)
• Activates virtual environment
• Sets environment variables:
  • BACKEND_ENV=local
  • GCP_PROJECT_ID=payroll-bi-gauntlet (if not set)
  • GOOGLE_APPLICATION_CREDENTIALS (if credentials.json exists)
  • GCP_REGION=us-central1 (if not set)
• Starts FastAPI/uvicorn server on http://localhost:8000

[BACKEND] Starting backend server...
[BACKEND] Environment Summary:
  PROJECT: payroll-bi-gauntlet
  CREDS: C:\Projects\payroll-pipeline-cbs\credentials.json
  REGION: us-central1
[BACKEND] Starting uvicorn server...
INFO:     Uvicorn running on http://0.0.0.0:8000

• API: http://localhost:8000
• API Docs: http://localhost:8000/docs
• Health Check: http://localhost:8000/api/health

​

Start Frontend

.\start-frontend.bat

powershell -ExecutionPolicy Bypass -File .\scripts\start-frontend.ps1

• Changes to ./dashboard directory
• Runs npm install if node_modules doesn’t exist
• Starts Next.js dev server on http://localhost:3000

[FRONTEND] Starting Next.js dev server...
  ▲ Next.js 14.2.33
  - Local:        http://localhost:3000

• Dashboard: http://localhost:3000
• Login: Use test credentials (see below)

​

Start Full Stack (Both Services)

.\start-full-stack.bat

powershell -ExecutionPolicy Bypass -File .\scripts\run-full-stack.ps1

• Bootstraps venv if missing
• Starts backend in a new PowerShell window
• Starts frontend in another new PowerShell window
• Polls health endpoints to verify services are running
• Prints status summary

[FULL-STACK] Starting full-stack application...
[FULL-STACK] ✅ Backend is running on http://localhost:8000
[FULL-STACK] ✅ Frontend is running on http://localhost:3000

​

Run Diagnostics

powershell -ExecutionPolicy Bypass -File .\scripts\diagnose-backend.ps1

• Checks Python and Node versions
• Verifies virtual environment
• Lists environment variables
• Validates credentials file
• Tests Python package imports
• Checks backend health endpoint
• Writes report to ./diagnostics/diagnostic-report.md

• Troubleshooting setup issues
• Verifying environment configuration
• Before reporting bugs

​

Test Users

python scripts/seed_user.py

​

Troubleshooting

​

Backend Not Starting

• Solution: Run .\scripts\bootstrap-venv.ps1 first

• Solution:
  1. Activate venv: .\venv\Scripts\activate.ps1
  2. Install dependencies: pip install -r requirements-api.txt

• Solution:
  1. Verify GCP_PROJECT_ID is set (defaults to payroll-bi-gauntlet)
  2. Ensure credentials.json exists OR run gcloud auth application-default login
  3. Check that service account has BigQuery permissions

• Solution:
  Copy

  Ask AI

  # Find process using port 8000
  netstat -ano | findstr :8000
  # Kill process (replace PID)
  taskkill /PID <PID> /F
  

• Solution:
  1. Check PowerShell execution policy: Get-ExecutionPolicy
  2. If Restricted, run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  3. Or use the .bat files which bypass execution policy

​

Frontend Not Starting

• Solution:
  1. Verify Node.js is installed: node -v
  2. Restart terminal after installing Node.js
  3. Verify npm is in PATH: npm -v

• Solution:
  Copy

  Ask AI

  # Find process using port 3000
  netstat -ano | findstr :3000
  # Kill process
  taskkill /PID <PID> /F
  

• Solution:
  1. Clear npm cache: npm cache clean --force
  2. Delete node_modules and package-lock.json
  3. Run npm install again

• Solution:
  1. Check Node.js version (should be 18.x or later)
  2. Run npm run build to see detailed errors
  3. Check dashboard/tsconfig.json configuration

​

Vertex AI / BigQuery Permission Issues

• Solution:
  1. Verify service account has required permissions:
     • BigQuery Data Viewer
     • BigQuery Job User
     • Vertex AI User (if using AI features)
  2. Check that GCP_PROJECT_ID matches your project
  3. Verify credentials file is valid JSON

• Solution:
  1. Check GCP_REGION is set (defaults to us-central1)
  2. Verify project has Vertex AI API enabled
  3. Check service account has Vertex AI permissions

• Solution:
  1. Verify GCP_PROJECT_ID=payroll-bi-gauntlet (or your actual project ID)
  2. Check that project exists in GCP Console
  3. Verify you have access to the project

​

Environment Variable Issues

• Solution: Set GCP_PROJECT_ID before starting:
  Copy

  Ask AI

  $env:GCP_PROJECT_ID = "your-project-id"
  .\start-backend.bat
  

• Solution:
  1. Place credentials.json in project root, OR
  2. Run gcloud auth application-default login

​

Quick Reference

​

File Structure

payroll-pipeline-cbs/
├── scripts/
│   ├── bootstrap-venv.ps1      # Create and setup venv
│   ├── start-backend.ps1        # Start backend server
│   ├── start-frontend.ps1       # Start frontend server
│   ├── run-full-stack.ps1       # Start both services
│   └── diagnose-backend.ps1     # Run diagnostics
├── start-backend.bat            # Backend launcher
├── start-frontend.bat           # Frontend launcher
├── start-full-stack.bat         # Full-stack launcher
├── credentials.json             # GCP service account (gitignored)
├── requirements-api.txt          # Python dependencies
├── venv/                        # Python virtual environment
├── api/                         # FastAPI backend
└── dashboard/                   # Next.js frontend

​

Additional Resources

• API Documentation: http://localhost:8000/docs (when backend is running)
• Makefile Commands: See Makefile for additional development commands
• Local Development Guide: See LOCAL_DEVELOPMENT_GUIDE.md