local-dev-server

What this skill does

# 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

```bash
# 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

```bash
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:**
```javascript
{
  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:**
```bash
cd /Users/benknight/Code/empathy-ledger-v2
pm2 start npm --name "empathy-ledger-solo" -- run dev
```

**Check Status:**
```bash
pm2 list
```

**View Logs:**
```bash
pm2 logs empathy-ledger-solo
```

**Restart After Code Changes:**
```bash
pm2 restart empathy-ledger-solo
```

**Stop Server:**
```bash
pm2 stop empathy-ledger-solo
pm2 delete empathy-ledger-solo  # Remove from PM2
```

---

### Pattern 2: Full ACT Ecosystem

**Start All Projects (Recommended):**
```bash
/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:**
```bash
/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh restart
```

**Stop All:**
```bash
/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh stop
```

**View All Logs:**
```bash
pm2 logs
```

**Monitor All Projects:**
```bash
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**
```bash
# 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)**
```bash
pm2 restart empathy-ledger
```

**Solution 3: Use Ecosystem Script**
```bash
/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh restart
```

---

## Troubleshooting

### Server Won't Start

**Check PM2 Status:**
```bash
pm2 list
pm2 logs empathy-ledger --lines 50
```

**Check Port Availability:**
```bash
lsof -i :3030
lsof -i :3001  # If using ecosystem config
```

**Force Kill and Restart:**
```bash
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:**
```bash
pm2 logs empathy-ledger --err --lines 100
```

If you see "max restarts reached", there's likely a code error. Check the error logs:
```bash
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:
```bash
pm2 restart empathy-ledger
```

Option 2: Enable watch mode (not recommended for Next.js):
```bash
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:**
   ```bash
   /Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh start
   ```

2. **Check All Running:**
   ```bash
   pm2 list
   ```

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

4. **View Logs When Needed:**
   ```bash
   pm2 logs empathy-ledger
   ```

5. **End of Day:**
   ```bash
   /Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh stop
   ```

### Testing Workflow

1. **Make Code Changes**

2. **Restart Server:**
   ```bash
   pm2 restart empathy-ledger
   ```

3. **Wait 3-5 Seconds for Startup**

4. **Test API/Feature**

5. **Check Logs for Errors:**
   ```bash
   pm2 logs empathy-ledger --lines 20
   ```

---

## Integration with Existing Tools

### Works With Supabase Local Dev

```bash
# 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

```bash
# Run migration
npx supabase db push

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

### Works With Testing Scripts

```bash
# 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

| Command | Purpose |
|---------|---------|
| `pm2 start <script>` | Start a process |
| `pm2 list` | Show all processes |
| `pm2 logs` | View all logs (live) |
| `pm2 logs <name>` | View specific process logs |
| `pm2 restart <name>` | Restart process |
| `pm2 stop <name>` | Stop process |
| `pm2 delete <name>` | Remove from PM2 |
| `pm2 monit` | Open monitoring dashboard |
| `pm2 flush` | Clear all logs |
| `pm2 save` | Save current process list |
| `pm2 startup` | Enable PM2 on system boot |

---

## Automation Recommendations

### Create Project-Specific Script

Add to `package.json`:

```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:**
```bash
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)

```bash
# Empathy Ledger shortcuts
alias el-start='pm2 start npm --na