Local Development Server Management

Purpose: Zero-friction local development server management for Empathy Ledger using PM2

Trigger: When user needs to start/stop/restart local dev server, or when "address already in use" errors occur

Quick Commands

# Single project (Empathy Ledger only)
pm2 start empathy-ledger       # Start server
pm2 restart empathy-ledger     # Restart server
pm2 stop empathy-ledger        # Stop server
pm2 logs empathy-ledger        # View logs

# Full ACT ecosystem (all projects)
/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh start
/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh restart
/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh stop
/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh logs

Problem This Solves

Pain Points:

• ❌ "address already in use" errors when port is occupied
• ❌ Forgetting to restart server after code changes
• ❌ Server crashes and doesn't auto-restart
• ❌ Can't find which process is using the port
• ❌ Manual npm run dev is fragile and doesn't persist

Solution:

• ✅ PM2 manages process lifecycle automatically
• ✅ Auto-restart on crashes
• ✅ Centralized logging
• ✅ Works with ACT ecosystem deployment script
• ✅ Simple commands for start/stop/restart

When to Use PM2 vs npm run dev

Use PM2 When:

• Working on multiple ACT projects simultaneously
• Need auto-restart on file changes
• Want centralized logging across projects
• Deploying locally for testing
• Server keeps crashing and you need persistence

Use npm run dev When:

• Quick one-off testing
• Actively debugging with console logs
• Only working on Empathy Ledger
• Making rapid code changes and want instant feedback

Setup (One-Time)

1. Install PM2 Globally

npm install -g pm2

2. Create Empathy Ledger PM2 Config

The global ecosystem config already has Empathy Ledger configured at: /Users/benknight/act-global-infrastructure/deployment/ecosystem.config.cjs

Empathy Ledger Config:

{
  name: 'empathy-ledger',
  script: '/Users/benknight/.nvm/versions/node/v20.19.3/bin/npm',
  args: 'run dev',
  cwd: '/Users/benknight/Code/empathy-ledger-v2',
  env: {
    PORT: 3001,  // Note: Different from standalone (3030)
    NODE_ENV: 'development',
  },
  autorestart: true,
  max_restarts: 10,
  min_uptime: '10s',
}

Usage Patterns

Pattern 1: Single Project (Empathy Ledger Only)

Start Server:

cd /Users/benknight/Code/empathy-ledger-v2
pm2 start npm --name "empathy-ledger-solo" -- run dev

Check Status:

pm2 list

View Logs:

pm2 logs empathy-ledger-solo

Restart After Code Changes:

pm2 restart empathy-ledger-solo

Stop Server:

pm2 stop empathy-ledger-solo
pm2 delete empathy-ledger-solo  # Remove from PM2

Pattern 2: Full ACT Ecosystem

Start All Projects (Recommended):

/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh start

This starts:

• ACT Regenerative Studio (port 3002)
• Empathy Ledger (port 3001)
• JusticeHub (port 3003)
• The Harvest Website (port 3004)
• ACT Farm (port 3005)
• ACT Placemat (port 3999)

Restart All:

/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh restart

Stop All:

/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh stop

View All Logs:

pm2 logs

Monitor All Projects:

pm2 monit

Pattern 3: Fix "Address Already in Use" Errors

Problem: Port 3030 (or any port) is occupied

Solution 1: Kill Process and Restart with PM2

# Find and kill process on port
lsof -ti :3030 | xargs kill -9

# Start with PM2 for auto-recovery
pm2 start npm --name "empathy-ledger-solo" -- run dev

Solution 2: Use PM2 Restart (Handles Cleanup)

pm2 restart empathy-ledger

Solution 3: Use Ecosystem Script

/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh restart

Troubleshooting

Server Won't Start

Check PM2 Status:

pm2 list
pm2 logs empathy-ledger --lines 50

Check Port Availability:

lsof -i :3030
lsof -i :3001  # If using ecosystem config

Force Kill and Restart:

pm2 delete empathy-ledger
lsof -ti :3030 | xargs kill -9
pm2 start npm --name "empathy-ledger-solo" -- run dev

Server Crashes Repeatedly

Check Max Restarts:

pm2 logs empathy-ledger --err --lines 100

If you see "max restarts reached", there's likely a code error. Check the error logs:

cat /Users/benknight/act-global-infrastructure/deployment/logs/empathy-ledger-error.log

Increase Max Restarts (if needed): Edit ecosystem config and increase max_restarts: 10 → max_restarts: 20

Code Changes Not Reflecting

PM2 Doesn't Auto-Reload by Default

Option 1: Restart manually after changes:

pm2 restart empathy-ledger

Option 2: Enable watch mode (not recommended for Next.js):

pm2 start npm --name "empathy-ledger-solo" --watch -- run dev

Option 3: Use npm run dev directly for active development

Best Practices

Development Workflow

1. Morning Startup:

   /Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh start
   

2. Check All Running:

   pm2 list
   

3. Work on Code (Auto-Restart Handles Crashes)

4. View Logs When Needed:

   pm2 logs empathy-ledger
   

5. End of Day:

   /Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh stop
   

Testing Workflow

1. Make Code Changes

2. Restart Server:

   pm2 restart empathy-ledger
   

3. Wait 3-5 Seconds for Startup

4. Test API/Feature

5. Check Logs for Errors:

   pm2 logs empathy-ledger --lines 20
   

Integration with Existing Tools

Works With Supabase Local Dev

# Start Supabase
npx supabase start

# Start Empathy Ledger with PM2
pm2 start npm --name "empathy-ledger-solo" -- run dev

# Both run together
pm2 list

Works With Database Migrations

# Run migration
npx supabase db push

# Restart server to load new schema
pm2 restart empathy-ledger

Works With Testing Scripts

# Server already running via PM2
pm2 list

# Run test script
bash test-syndication.sh

# Logs show the requests
pm2 logs empathy-ledger --lines 30

PM2 Cheat Sheet

Automation Recommendations

Create Project-Specific Script

Add to package.json:

{
  "scripts": {
    "dev": "next dev -p 3030",
    "dev:pm2": "pm2 start npm --name empathy-ledger-solo -- run dev",
    "dev:restart": "pm2 restart empathy-ledger-solo",
    "dev:stop": "pm2 stop empathy-ledger-solo && pm2 delete empathy-ledger-solo",
    "dev:logs": "pm2 logs empathy-ledger-solo"
  }
}

Usage:

npm run dev:pm2        # Start with PM2
npm run dev:restart    # Restart
npm run dev:logs       # View logs
npm run dev:stop       # Stop and remove

Create Alias in Shell (.zshrc or .bashrc)

# Empathy Ledger shortcuts
alias el-start='pm2 start npm --nam