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:

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

cd backend
.\scripts\setup.ps1

Linux/macOS

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

Manual Steps

1. Create virtual environment:

cd backend
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

2. Install dependencies:

# Install uv (modern Python package manager)
pip install uv

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

3. Configure environment:

# 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

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:

alembic upgrade head

6. Start backend server:

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:

cd frontend
pnpm install
# or: npm install

2. Configure environment:

# Create .env.local
echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local

3. Start development server:

pnpm dev
# or: npm run dev

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

Verification

Backend Health Check

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

cd backend
pytest tests/ -v

Frontend Tests

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