you-music/PROCESS_MANAGER.md

# Local Development with Process Manager

## Quick Start

```bash
# Recommended: Use the unified stack runner
./dev-stack.sh
```

This will:
- ✅ Auto-install overmind (if using Homebrew)
- ✅ Start both backend and frontend
- ✅ Show all logs in one place
- ✅ Color-coded output
- ✅ Easy to stop (Ctrl+C stops everything)

## What is overmind?

**overmind** is like foreman but better for local development:
- 🚀 Faster startup
- 🎨 Color-coded logs
- 🔄 Can restart individual processes
- 💻 Connect to individual processes
- ⌨️  Tmux-based (powerful terminal multiplexing)

## Installation Options

### Option 1: overmind (Recommended)
```bash
brew install overmind tmux
```

### Option 2: hivemind
```bash
brew install hivemind
```

### Option 3: Ruby foreman
```bash
gem install foreman
```

### Option 4: node-foreman
```bash
npm install -g foreman
```

## Usage

### Start All Services
```bash
./dev-stack.sh
```

### overmind Shortcuts

**While running:**
- `Ctrl+C` - Stop all services

**In another terminal:**
```bash
# Connect to a specific service
overmind connect backend
overmind connect frontend

# Restart a service
overmind restart backend
overmind restart frontend

# Stop a specific service
overmind stop backend

# View processes
overmind ps
```

### View Logs

When using overmind, all logs appear in the same terminal with color coding:
```
backend  | [log output in one color]
frontend | [log output in another color]
```

## Process Configuration

The `Procfile.dev` defines what runs:

```
backend: cd backend && .venv/bin/python main.py
frontend: cd frontend && npm run dev -- --host
```

## Comparison with Old Method

| Feature | ./dev.sh (old) | ./dev-stack.sh (new) |
|---------|----------------|----------------------|
| Start | Background processes | Foreground (better) |
| Logs | Separate files | One terminal |
| Stop | ./dev-stop.sh | Ctrl+C |
| Colors | No | Yes |
| Restart | Stop + start | overmind restart |
| Connect | Can't | overmind connect |

## Advanced: overmind Features

### Connect to Running Process
```bash
# Start in one terminal
./dev-stack.sh

# In another terminal, connect to backend
overmind connect backend

# Type in the backend process directly!
# Ctrl+B, D to disconnect (keeps running)
```

### Restart Individual Service
```bash
# Restart just the frontend without stopping backend
overmind restart frontend
```

### Environment Variables
Edit `.env` file to set ports:
```
PORT=8000
FRONTEND_PORT=3000
```

## Troubleshooting

### Port Already in Use
```bash
# Find and kill process on port 8000
lsof -ti:8000 | xargs kill -9

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

### overmind Won't Install
If Homebrew fails, use another manager:
```bash
brew install hivemind
```

### Processes Won't Stop
```bash
# Kill all overmind processes
pkill overmind

# Or use the old stop script
./dev-stop.sh
```

## Why This is Better

### Before (./dev.sh):
```bash
./dev.sh
# Backend logs: logs/backend.log
# Frontend logs: logs/frontend.log
# Need to tail -f each file separately
# Hard to see errors quickly
```

### After (./dev-stack.sh):
```bash
./dev-stack.sh
# All logs in one terminal
# Color-coded by service
# Ctrl+C stops everything
# Easy to see errors
```

## Example Output

```
🚀 YouMusic - Starting Development Stack
=========================================

✅ Using overmind (best option)

Shortcuts:
  Ctrl+C       - Stop all
  overmind c   - Connect to services
  overmind r   - Restart a service

Starting services...

backend  | INFO:     Started server process [12345]
backend  | INFO:     Waiting for application startup.
backend  | INFO:     Application startup complete.
backend  | INFO:     Uvicorn running on http://0.0.0.0:8000
frontend | 
frontend |   VITE v5.4.5  ready in 234 ms
frontend | 
frontend |   ➜  Local:   http://localhost:3000/
frontend |   ➜  Network: http://192.168.1.10:3000/
```

All in one place, color-coded, beautiful! 🎨

## Summary

**Old way:**
```bash
./dev.sh              # Start in background
tail -f logs/*.log    # View logs separately
./dev-stop.sh         # Stop
```

**New way:**
```bash
./dev-stack.sh        # Start, view logs, stop with Ctrl+C
```

Much simpler! 🚀