OnyxMunk/AudioForge

1# AudioForge Quick Start Guide
2
3Get AudioForge running in 5 minutes!
4
5## Option 1: Docker Compose (Fastest) ⚡
6
7```bash
8# Clone the repository (if not already done)
9cd AudioForge
10
11# Start everything
12docker-compose up -d
13
14# Wait for services to start (30-60 seconds)
15docker-compose logs -f
16
17# When you see "Application startup complete", open:
18# Frontend: http://localhost:3000
19# API Docs: http://localhost:8000/api/docs
20```
21
22That's it! 🎉
23
24## Option 2: Manual Setup
25
26### Step 1: Backend (2 minutes)
27
28```bash
29cd backend
30
31# Windows PowerShell
32.\scripts\setup.ps1
33
34# Linux/macOS
35chmod +x scripts/setup.sh
36./scripts/setup.sh
37
38# Or manually:
39python -m venv .venv
40.venv\Scripts\activate  # Windows
41# source .venv/bin/activate  # Linux/macOS
42pip install uv
43uv pip install -e ".[dev]"
44cp .env.example .env
45```
46
47**Start PostgreSQL & Redis:**
48```bash
49# Using Docker (easiest)
50docker-compose up -d postgres redis
51
52# Or install locally and start services
53```
54
55**Initialize Database:**
56```bash
57python scripts/init_db.py
58```
59
60**Start Backend:**
61```bash
62uvicorn app.main:app --reload
63```
64
65Backend running at http://localhost:8000 ✅
66
67### Step 2: Frontend (1 minute)
68
69```bash
70cd frontend
71pnpm install  # or: npm install
72echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local
73pnpm dev
74```
75
76Frontend running at http://localhost:3000 ✅
77
78## Test It Works
79
801. Open http://localhost:3000
812. Enter a prompt: "An upbeat electronic dance track"
823. Click "Generate Music"
834. Wait for generation (may take 1-2 minutes first time as models download)
84
85## Troubleshooting
86
87**Backend won't start?**
88```bash
89cd backend
90python scripts/verify_setup.py
91```
92
93**Database connection error?**
94- Check PostgreSQL is running: `docker-compose ps`
95- Verify DATABASE_URL in `.env`
96
97**Frontend can't connect to backend?**
98- Check NEXT_PUBLIC_API_URL in `.env.local`
99- Ensure backend is running on port 8000
100
101**Models downloading slowly?**
102- First generation downloads MusicGen models (~2GB)
103- Subsequent generations are faster
104- Set `MUSICGEN_DEVICE=cpu` in `.env` if no GPU
105
106## Next Steps
107
108- Read [SETUP.md](SETUP.md) for detailed setup
109- Read [ARCHITECTURE.md](ARCHITECTURE.md) for system design
110- Read [CONTRIBUTING.md](CONTRIBUTING.md) for development
111
112## Need Help?
113
114- Check logs: `docker-compose logs -f` or backend console
115- API docs: http://localhost:8000/api/docs
116- Verify setup: `python backend/scripts/verify_setup.py`
117