you-music/LOCAL_DEV_GUIDE.md

# Local Development Guide (macOS/Linux)

This guide is for developers who want to run the app locally without Docker for faster development.

## Prerequisites

- **Python 3.13** - `python3.13 --version`
- **uv** - Fast Python package installer (auto-installed by setup script)
- **Node.js 18+** - `node --version`
- **FFmpeg** - `ffmpeg -version`

### Install Python 3.13

**macOS:**
```bash
brew install python@3.13
```

**Ubuntu/Debian:**
```bash
sudo apt-get update
sudo apt-get install python3.13 python3.13-venv
```

### Install FFmpeg

**macOS:**
```bash
brew install ffmpeg
```

**Ubuntu/Debian:**
```bash
sudo apt-get update
sudo apt-get install ffmpeg
```

## Quick Start (One Command)

```bash
# First time setup
./dev-setup.sh

# Start both backend and frontend
./dev.sh
```

That's it! Visit **http://localhost:3000**

## What `dev.sh` Does

1. Starts the backend server on port 8000
2. Starts the frontend dev server on port 3000
3. Runs both in background with logs
4. Hot reload enabled for both

## Stop Development Servers

```bash
./dev-stop.sh
```

## Manual Development (Two Terminals)

If you prefer to run servers in separate terminals:

**Terminal 1 - Backend:**
```bash
./dev-backend.sh
```

**Terminal 2 - Frontend:**
```bash
./dev-frontend.sh
```

## URLs When Running Locally

- **Frontend**: http://localhost:3000 (main app)
- **Backend API**: http://localhost:8000
- **API Docs**: http://localhost:8000/docs
- **Alternative Docs**: http://localhost:8000/redoc

## Development Workflow

### 1. First Time Setup
```bash
./dev-setup.sh
```

This will:
- ✅ Check for Python 3.13
- ✅ Install uv (if not present)
- ✅ Create Python virtual environment (.venv)
- ✅ Install Python dependencies with uv
- ✅ Install Node.js dependencies
- ✅ Create data directories
- ✅ Create .env files

### 2. Start Development
```bash
./dev.sh
```

### 3. Make Changes
- Edit files in `backend/` or `frontend/`
- Changes auto-reload (hot reload enabled)
- Check logs: `tail -f logs/backend.log` or `tail -f logs/frontend.log`

### 4. Stop Development
```bash
./dev-stop.sh
```

## File Structure

```
you-music/
├── dev-setup.sh       # One-time setup
├── dev.sh             # Start both servers
├── dev-stop.sh        # Stop both servers
├── dev-backend.sh     # Start backend only
├── dev-frontend.sh    # Start frontend only
├── backend/
│   ├── .venv/         # Python virtual environment
│   └── .env           # Backend configuration
├── frontend/
│   ├── node_modules/  # npm packages
│   └── .env           # Frontend configuration
├── data/              # Music files and database
└── logs/              # Development logs
```

## Environment Variables

### Backend (.env)
```env
DATABASE_URL=sqlite+aiosqlite:///./data/youmusic.db
MUSIC_DIR=./data/music
UPLOAD_DIR=./data/uploads
TEMP_DIR=./data/temp
FFMPEG_LOCATION=ffmpeg
```

### Frontend (.env)
```env
VITE_API_URL=http://localhost:8000
```

## Hot Reload

Both servers support hot reload:

**Backend**: Edit any `.py` file → Server auto-restarts
**Frontend**: Edit any `.tsx`, `.ts`, `.css` file → Browser auto-updates

## Common Tasks

### Reset Database
```bash
rm data/youmusic.db
# Restart backend
```

### Clear Downloaded Music
```bash
rm -rf data/music/*
```

### Update Dependencies

**Backend:**
```bash
cd backend
source .venv/bin/activate
uv sync
```

**Frontend:**
```bash
cd frontend
npm install
```

### View Logs in Real-time

```bash
# Backend logs
tail -f logs/backend.log

# Frontend logs
tail -f logs/frontend.log

# Both at once
tail -f logs/*.log
```

### Check Running Processes
```bash
# See what's running
ps aux | grep -E "uvicorn|vite"

# See PIDs
cat logs/backend.pid
cat logs/frontend.pid
```

## Troubleshooting

### Port Already in Use

**Backend (8000):**
```bash
lsof -ti:8000 | xargs kill -9
```

**Frontend (3000):**
```bash
lsof -ti:3000 | xargs kill -9
```

### Virtual Environment Issues
```bash
# Delete and recreate
rm -rf backend/.venv
cd backend
uv venv --python 3.13
source .venv/bin/activate
uv sync
```

### Node Modules Issues
```bash
# Delete and reinstall
rm -rf frontend/node_modules
cd frontend
npm install
```

### FFmpeg Not Found
```bash
# Check installation
which ffmpeg
ffmpeg -version

# Install if missing (macOS)
brew install ffmpeg
```

### Permission Denied on Scripts
```bash
chmod +x dev-*.sh
```

## Why Local Development?

**Faster than Docker:**
- No container overhead
- Instant hot reload
- Native file system performance
- Easier debugging

**When to Use:**
- Active development
- Testing changes quickly
- Debugging issues
- Frontend/backend iteration

**When to Use Docker:**
- Production deployment
- Consistent environment
- Easy distribution
- CI/CD pipelines

## Development Tips

### 1. Use Two Monitors/Terminals
- One for code editor
- One for logs (`tail -f logs/*.log`)

### 2. Check API Docs
- Visit http://localhost:8000/docs
- Test endpoints interactively
- See request/response schemas

### 3. Browser DevTools
- Open Network tab
- Monitor API calls
- Check console for errors

### 4. Database Inspection
```bash
# Install sqlite3 if needed
sqlite3 data/youmusic.db

# View tables
.tables

# Query music
SELECT * FROM music LIMIT 5;

# Exit
.quit
```

### 5. Clean Restart
```bash
./dev-stop.sh
rm -rf data/youmusic.db
./dev.sh
```

## Performance Comparison

| Aspect | Local Dev | Docker |
|--------|-----------|--------|
| Startup Time | ~2-5 sec | ~10-30 sec |
| Hot Reload | Instant | 1-2 sec |
| File I/O | Native | Volume overhead |
| Memory | Lower | Higher |
| Setup Complexity | More steps | Single command |

## Scripts Reference

| Script | Purpose | Usage |
|--------|---------|-------|
| `dev-setup.sh` | Initial setup | Run once |
| `dev.sh` | Start both servers | Daily development |
| `dev-stop.sh` | Stop all servers | End of session |
| `dev-backend.sh` | Backend only | Backend work |
| `dev-frontend.sh` | Frontend only | Frontend work |

## Next Steps

1. Run `./dev-setup.sh` (first time)
2. Run `./dev.sh` (start development)
3. Open http://localhost:3000
4. Start coding!
5. Run `./dev-stop.sh` when done

Happy coding! 🎵