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

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

pm2 start <script>

pm2 list

pm2 logs

pm2 logs <name>

pm2 restart <name>

pm2 stop <name>

pm2 delete <name>

pm2 monit

pm2 flush

pm2 save

pm2 startup

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 --name empathy-ledger-solo -- run dev'
alias el-restart='pm2 restart empathy-ledger-solo'
alias el-stop='pm2 stop empathy-ledger-solo && pm2 delete empathy-ledger-solo'
alias el-logs='pm2 logs empathy-ledger-solo'
alias el-status='pm2 list | grep empathy'

# ACT Ecosystem shortcuts
alias act-start='/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh start'
alias act-restart='/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh restart'
alias act-stop='/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh stop'
alias act-logs='pm2 logs'
alias act-status='pm2 list'

Reload shell:

source ~/.zshrc  # or source ~/.bashrc

Usage:

el-start      # Start Empathy Ledger
el-restart    # Restart
el-logs       # View logs
el-stop       # Stop

ACT Ecosystem Deployment Script

Location:

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

Commands:

./deploy-act-ecosystem.sh start    # Start all projects
./deploy-act-ecosystem.sh stop     # Stop all projects
./deploy-act-ecosystem.sh restart  # Restart all projects
./deploy-act-ecosystem.sh status   # Show status
./deploy-act-ecosystem.sh logs     # Show all logs
./deploy-act-ecosystem.sh monitor  # Open PM2 dashboard

Features:

• ✅ Starts all 6 ACT projects
• ✅ Auto-opens sites in Chrome (via AppleScript)
• ✅ Centralized logging to

  /Users/benknight/act-global-infrastructure/deployment/logs/

• ✅ Auto-restart on crashes
• ✅ Color-coded status output

Ports:

• ACT Studio: 3002
• Empathy Ledger: 3030
• JusticeHub: 3003
• Harvest: 3004
• ACT Farm: 3005
• Placemat: 3999

Note: All projects use consistent ports across standalone and ecosystem modes

Common Scenarios

Scenario 1: "Address Already in Use" Error

User sees:

Error: listen EADDRINUSE: address already in use :::3030

Claude Response:

# Kill existing process
lsof -ti :3030 | xargs kill -9

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

# Verify running
pm2 list

Scenario 2: Server Needs Restart After Schema Fix

User says: "I fixed the schema, now restart the server"

Claude Response:

# If using PM2
pm2 restart empathy-ledger

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

# Wait for startup
sleep 5

# Test
curl http://localhost:3030

Scenario 3: Testing Syndication System

User says: "Test the syndication API"

Claude Response:

# Ensure server is running
pm2 list | grep empathy || pm2 start npm --name "empathy-ledger-solo" -- run dev

# Wait for startup
sleep 5

# Run test
bash test-syndication.sh

# Check logs if errors
pm2 logs empathy-ledger-solo --lines 50

Integration with Development Workflow

Sprint Development Cycle

Sprint Start:

act-start  # Start all ACT projects

During Development:

# Make code changes
# ...

# Restart to test
pm2 restart empathy-ledger

# View logs
pm2 logs empathy-ledger

End of Sprint:

# Stop all projects
act-stop

# Or keep running if continuing tomorrow
pm2 save  # Save current state

Log Management

View Live Logs:

pm2 logs empathy-ledger

View Last N Lines:

pm2 logs empathy-ledger --lines 100

View Error Logs Only:

pm2 logs empathy-ledger --err

Clear All Logs:

pm2 flush

Log File Locations (Ecosystem):

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

When Claude Should Use This Skill

Trigger Phrases:

• "Start the dev server"
• "Restart the server"
• "Address already in use"
• "Port 3030 is busy"
• "Server won't start"
• "Test the API" (ensure server running first)
• "Deploy locally"
• "Run all ACT projects"

Actions Claude Should Take:

1. Check if server is running:

   pm2 list | grep empathy
   

2. If not running, start it:

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

3. If running but needs restart:

   pm2 restart empathy-ledger-solo
   

4. Wait for startup:

   sleep 5
   

5. Verify responsive:

   curl -s http://localhost:3030 > /dev/null && echo "✅ Server running" || echo "❌ Server not responding"
   

6. Proceed with testing/development

Success Criteria

After following this skill, user should:

• ✅ Have server running reliably
• ✅ Be able to restart server easily
• ✅ No more "address already in use" errors
• ✅ Have access to centralized logs
• ✅ Know how to use PM2 for all ACT projects

This skill eliminates the "local deployment shit fight" by providing a consistent, reliable, PM2-based workflow that aligns with the ACT ecosystem deployment strategy.