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