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:

brew install python@3.13

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install python3.13 python3.13-venv

Install FFmpeg

macOS:

brew install ffmpeg

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install ffmpeg

Quick Start (One Command)

# 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

./dev-stop.sh

Manual Development (Two Terminals)

If you prefer to run servers in separate terminals:

Terminal 1 - Backend:

./dev-backend.sh

Terminal 2 - Frontend:

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

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

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

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

DATABASE_URL=sqlite+aiosqlite:///./data/youmusic.db
MUSIC_DIR=./data/music
UPLOAD_DIR=./data/uploads
TEMP_DIR=./data/temp
FFMPEG_LOCATION=ffmpeg

Frontend (.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

rm data/youmusic.db
# Restart backend

Clear Downloaded Music

rm -rf data/music/*

Update Dependencies

Backend:

cd backend
source .venv/bin/activate
uv sync

Frontend:

cd frontend
npm install

View Logs in Real-time

# Backend logs
tail -f logs/backend.log

# Frontend logs
tail -f logs/frontend.log

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

Check Running Processes

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

lsof -ti:8000 | xargs kill -9

Frontend (3000):

lsof -ti:3000 | xargs kill -9

Virtual Environment Issues

# Delete and recreate
rm -rf backend/.venv
cd backend
uv venv --python 3.13
source .venv/bin/activate
uv sync

Node Modules Issues

# Delete and reinstall
rm -rf frontend/node_modules
cd frontend
npm install

FFmpeg Not Found

# Check installation
which ffmpeg
ffmpeg -version

# Install if missing (macOS)
brew install ffmpeg

Permission Denied on Scripts

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

# Install sqlite3 if needed
sqlite3 data/youmusic.db

# View tables
.tables

# Query music
SELECT * FROM music LIMIT 5;

# Exit
.quit

5. Clean Restart

./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! 🎵