you-music/PROCESS_MANAGER.md

Local Development with Process Manager

Quick Start

# 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)

brew install overmind tmux

Option 2: hivemind

brew install hivemind

Option 3: Ruby foreman

gem install foreman

Option 4: node-foreman

npm install -g foreman

Usage

Start All Services

./dev-stack.sh

overmind Shortcuts

While running:

• Ctrl+C - Stop all services

In another terminal:

# 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

# 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

# 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

# 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:

brew install hivemind

Processes Won't Stop

# Kill all overmind processes
pkill overmind

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

Why This is Better

Before (./dev.sh):

./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):

./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:

./dev.sh              # Start in background
tail -f logs/*.log    # View logs separately
./dev-stop.sh         # Stop

New way:

./dev-stack.sh        # Start, view logs, stop with Ctrl+C

Much simpler! 🚀