QUICKSTART.md

AudioForge Quick Start Guide

Get AudioForge running in 5 minutes!

Option 1: Docker Compose (Fastest) ⚡

# Clone the repository (if not already done)
cd AudioForge

# Start everything
docker-compose up -d

# Wait for services to start (30-60 seconds)
docker-compose logs -f

# When you see "Application startup complete", open:
# Frontend: http://localhost:3000
# API Docs: http://localhost:8000/api/docs

That's it! 🎉

Option 2: Manual Setup

Step 1: Backend (2 minutes)

cd backend

# Windows PowerShell
.\scripts\setup.ps1

# Linux/macOS
chmod +x scripts/setup.sh
./scripts/setup.sh

# Or manually:
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/macOS
pip install uv
uv pip install -e ".[dev]"
cp .env.example .env

Start PostgreSQL & Redis:

# Using Docker (easiest)
docker-compose up -d postgres redis

# Or install locally and start services

Initialize Database:

python scripts/init_db.py

Start Backend:

uvicorn app.main:app --reload

Backend running at http://localhost:8000 ✅

Step 2: Frontend (1 minute)

cd frontend
pnpm install  # or: npm install
echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local
pnpm dev

Frontend running at http://localhost:3000 ✅

Test It Works

1. Open http://localhost:3000
2. Enter a prompt: "An upbeat electronic dance track"
3. Click "Generate Music"
4. Wait for generation (may take 1-2 minutes first time as models download)

Troubleshooting

Backend won't start?

cd backend
python scripts/verify_setup.py

Database connection error?

• Check PostgreSQL is running: docker-compose ps
• Verify DATABASE_URL in .env

Frontend can't connect to backend?

• Check NEXT_PUBLIC_API_URL in .env.local
• Ensure backend is running on port 8000

Models downloading slowly?

• First generation downloads MusicGen models (~2GB)
• Subsequent generations are faster
• Set MUSICGEN_DEVICE=cpu in .env if no GPU

Next Steps

• Read SETUP.md for detailed setup
• Read ARCHITECTURE.md for system design
• Read CONTRIBUTING.md for development

Need Help?

• Check logs: docker-compose logs -f or backend console
• API docs: http://localhost:8000/api/docs
• Verify setup: python backend/scripts/verify_setup.py