Skip to main content

Local Development Guide

note

Content migrating from various repository README files

Prerequisites​

  • Node.js 22+ (for frontends and MCP servers)
  • Python 3.12+ (for Lambda functions)
  • Docker (for Lambda container builds)
  • AWS CLI configured
  • Terraform 1.13+

Repository Setup​

Clone the required repositories:

cd ~/Code

# Main application
git clone git@github.com:alianzacap/alianza-hq.git

# Infrastructure
git clone git@github.com:alianzacap/alianza-infra.git

# MCP servers
git clone git@github.com:alianzacap/mcp-framework.git
git clone git@github.com:alianzacap/mcp-jppr.git
git clone git@github.com:alianzacap/mcp-baseline.git
git clone git@github.com:alianzacap/mcp-crim.git

# Documentation
git clone git@github.com:alianzacap/docs.git

Alianza HQ (Next.js)​

cd alianza-hq
bun install
bun run dev

Open http://localhost:3000.

Environment Variables​

Copy the example and fill in credentials:

cp .env.example .env.local

Required variables:

  • AUTH0_SECRET - Auth0 session secret
  • AUTH0_BASE_URL - http://localhost:3000
  • AUTH0_ISSUER_BASE_URL - Auth0 domain
  • AUTH0_CLIENT_ID - Auth0 client ID
  • AUTH0_CLIENT_SECRET - Auth0 client secret
  • SUPABASE_URL - Supabase project URL
  • SUPABASE_ANON_KEY - Supabase anon key

CoquiTitle Lambdas​

Container-based Lambdas​

cd alianza-hq/backend/coquititle/lambdas/api-handler

# Build and test locally
docker build -t coquititle-api .
docker run -p 9000:8080 coquititle-api

# Test the function
curl -X POST "http://localhost:9000/2015-03-31/functions/function/invocations" \
  -d '{"httpMethod": "GET", "path": "/health"}'

Deploying​

./deploy-container.sh

MCP Servers​

Local Development​

cd mcp-jppr
npm install
npm run build

# STDIO mode (for Claude Desktop testing)
npm run start:stdio

# Cloudflare Worker local dev
npm run dev:worker

Claude Desktop Integration​

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jppr": {
      "command": "node",
      "args": ["/Users/you/Code/mcp-jppr/dist/server-stdio.js"]
    }
  }
}

Infrastructure (Terraform)​

cd alianza-infra

# Initialize
cd roots/foundation
terraform init

# Plan changes
terraform plan -var-file=../../environments/dev/terraform.tfvars

# Apply (requires approval)
terraform apply

Database Access​

Supabase Studio​

Access at: https://supabase.com/dashboard/project/yodutvdnvvmbuaxccbex

Direct Connection​

# Connection string format
postgresql://postgres:[PASSWORD]@db.yodutvdnvvmbuaxccbex.supabase.co:5432/postgres

Common Issues​

Node version mismatch​

Use the correct Node version:

nvm use 22

Lambda build failures​

Ensure Docker is running for container builds:

docker info

Auth0 callback errors​

Verify AUTH0_BASE_URL matches your local server URL exactly.