SETUP.md

# AudioForge Setup Guide

Complete setup guide to get AudioForge running locally without errors.

## Prerequisites

- **Python 3.11+** (check with `python --version`)
- **Node.js 20+** (check with `node --version`)
- **PostgreSQL 16+** (or use Docker)
- **Redis 7+** (or use Docker)
- **Docker & Docker Compose** (optional, recommended)

## Quick Start (Docker)

The easiest way to get started:

```bash
# Clone and navigate to project
cd AudioForge

# Start all services
docker-compose up -d

# Backend will be at http://localhost:8000
# Frontend will be at http://localhost:3000
```

## Manual Setup

### Backend Setup

#### Windows (PowerShell)

```powershell
cd backend
.\scripts\setup.ps1
```

#### Linux/macOS

```bash
cd backend
chmod +x scripts/setup.sh
./scripts/setup.sh
```

#### Manual Steps

1. **Create virtual environment:**
```bash
cd backend
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate
```

2. **Install dependencies:**
```bash
# Install uv (modern Python package manager)
pip install uv

# Install project dependencies
uv pip install -e ".[dev]"
```

3. **Configure environment:**
```bash
# Copy example env file
cp .env.example .env

# Edit .env with your settings
# At minimum, set DATABASE_URL and REDIS_URL
```

4. **Start PostgreSQL and Redis:**

**Option A: Docker**
```bash
docker-compose up -d postgres redis
```

**Option B: Local Installation**
- Install PostgreSQL and start service
- Install Redis and start service
- Update `.env` with connection URLs

5. **Run database migrations:**
```bash
alembic upgrade head
```

6. **Start backend server:**
```bash
uvicorn app.main:app --reload
```

Backend will be available at http://localhost:8000
API docs at http://localhost:8000/api/docs

### Frontend Setup

1. **Install dependencies:**
```bash
cd frontend
pnpm install
# or: npm install
```

2. **Configure environment:**
```bash
# Create .env.local
echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local
```

3. **Start development server:**
```bash
pnpm dev
# or: npm run dev
```

Frontend will be available at http://localhost:3000

## Verification

### Backend Health Check

```bash
curl http://localhost:8000/health
# Should return: {"status":"healthy","version":"0.1.0"}
```

### Frontend Check

Open http://localhost:3000 in your browser. You should see the AudioForge interface.

## Common Issues & Solutions

### Issue: Database Connection Error

**Solution:**
- Ensure PostgreSQL is running: `docker-compose ps` or `pg_isready`
- Check DATABASE_URL in `.env` matches your PostgreSQL setup
- Verify database exists: `createdb audioforge` (if needed)

### Issue: Redis Connection Error

**Solution:**
- Ensure Redis is running: `docker-compose ps` or `redis-cli ping`
- Check REDIS_URL in `.env`
- Redis is optional for basic functionality

### Issue: Model Loading Errors

**Solution:**
- MusicGen models download automatically on first use (can be slow)
- Ensure sufficient disk space (~2GB for models)
- For CPU-only: Set `MUSICGEN_DEVICE=cpu` in `.env`
- Models load lazily - first generation may take longer

### Issue: Port Already in Use

**Solution:**
- Backend: Change port in `uvicorn` command or `.env`
- Frontend: Change port in `next.config.js` or use `pnpm dev -p 3001`
- Stop conflicting services

### Issue: Import Errors

**Solution:**
- Ensure virtual environment is activated
- Reinstall dependencies: `uv pip install -e ".[dev]"`
- Check Python version: `python --version` (needs 3.11+)

### Issue: Frontend Build Errors

**Solution:**
- Clear cache: `rm -rf .next node_modules`
- Reinstall: `pnpm install`
- Check Node version: `node --version` (needs 20+)

## Development Workflow

1. **Backend changes:** Server auto-reloads with `--reload` flag
2. **Frontend changes:** Next.js hot-reloads automatically
3. **Database changes:** Create migration: `alembic revision --autogenerate -m "description"`
4. **Apply migrations:** `alembic upgrade head`

## Testing

### Backend Tests
```bash
cd backend
pytest tests/ -v
```

### Frontend Tests
```bash
cd frontend
pnpm test
```

## Production Deployment

See `ARCHITECTURE.md` for production deployment considerations.

## Getting Help

- Check logs: Backend logs to console, check for errors
- API docs: http://localhost:8000/api/docs
- Review `ARCHITECTURE.md` for system design
- Check `CONTRIBUTING.md` for development guidelines