OnyxMunk/AudioForge

1# AudioForge Setup Verification Checklist
2
3Use this checklist to verify your AudioForge installation is correct and ready to run.
4
5## ✅ Pre-Flight Checks
6
7### Backend
8
9- [ ] Python 3.11+ installed (`python --version`)
10- [ ] Virtual environment created and activated
11- [ ] Dependencies installed (`uv pip install -e ".[dev]"`)
12- [ ] `.env` file exists (copied from `.env.example`)
13- [ ] Storage directories exist (`storage/audio/{music,vocals,mixed,mastered}`)
14- [ ] PostgreSQL running and accessible
15- [ ] Redis running (optional but recommended)
16- [ ] Database initialized (`python scripts/init_db.py`)
17
18### Frontend
19
20- [ ] Node.js 20+ installed (`node --version`)
21- [ ] Dependencies installed (`pnpm install`)
22- [ ] `.env.local` exists with `NEXT_PUBLIC_API_URL`
23- [ ] No build errors (`pnpm build` succeeds)
24
25## ✅ Runtime Checks
26
27### Backend Health
28
29```bash
30# Should return: {"status":"healthy","version":"0.1.0"}
31curl http://localhost:8000/health
32```
33
34### Backend API Docs
35
36```bash
37# Should open Swagger UI
38open http://localhost:8000/api/docs
39```
40
41### Frontend
42
43```bash
44# Should open AudioForge interface
45open http://localhost:3000
46```
47
48### Database Connection
49
50```bash
51# Backend should connect without errors
52# Check logs for: "database_initialized_successfully"
53```
54
55## ✅ Functional Tests
56
57### Test Generation Flow
58
591. [ ] Open http://localhost:3000
602. [ ] Enter prompt: "A calm acoustic guitar melody"
613. [ ] Click "Generate Music"
624. [ ] See generation status change: pending → processing → completed
635. [ ] Audio file generated and playable
64
65### Test API Directly
66
67```bash
68# Create generation
69curl -X POST http://localhost:8000/api/v1/generations \
70  -H "Content-Type: application/json" \
71  -d '{"prompt": "Test music generation"}'
72
73# Should return generation ID and status: "pending"
74```
75
76## ✅ Code Quality Checks
77
78### Backend
79
80```bash
81cd backend
82
83# Type checking
84mypy app
85
86# Linting
87ruff check app
88
89# Formatting
90black --check app
91
92# Tests
93pytest tests/ -v
94```
95
96### Frontend
97
98```bash
99cd frontend
100
101# Type checking
102pnpm type-check
103
104# Linting
105pnpm lint
106
107# Tests
108pnpm test
109```
110
111## ✅ Performance Checks
112
113- [ ] Backend starts in < 5 seconds
114- [ ] Frontend builds in < 30 seconds
115- [ ] API responses < 100ms (excluding generation)
116- [ ] No memory leaks (check with `docker stats`)
117
118## ✅ Security Checks
119
120- [ ] `.env` not committed to git
121- [ ] `SECRET_KEY` changed from default
122- [ ] CORS configured correctly
123- [ ] No sensitive data in logs
124
125## ✅ Documentation Checks
126
127- [ ] README.md complete
128- [ ] SETUP.md complete
129- [ ] ARCHITECTURE.md complete
130- [ ] API docs accessible
131- [ ] Code comments present
132
133## Common Issues & Solutions
134
135### Issue: Backend won't start
136
137**Check:**
138```bash
139cd backend
140python scripts/verify_setup.py
141```
142
143**Common causes:**
144- Missing dependencies → `uv pip install -e ".[dev]"`
145- Database not running → `docker-compose up -d postgres`
146- Port 8000 in use → Change port or stop conflicting service
147
148### Issue: Frontend won't connect to backend
149
150**Check:**
151- `.env.local` has correct `NEXT_PUBLIC_API_URL`
152- Backend is running on correct port
153- CORS allows frontend origin
154
155### Issue: Generation fails
156
157**Check:**
158- Models downloading (first time takes time)
159- Sufficient disk space (~2GB for models)
160- GPU/CUDA if using GPU mode
161- Check backend logs for errors
162
163### Issue: Database errors
164
165**Check:**
166- PostgreSQL running: `docker-compose ps` or `pg_isready`
167- DATABASE_URL correct in `.env`
168- Database exists: `createdb audioforge` if needed
169- Migrations applied: `alembic upgrade head`
170
171## Verification Script
172
173Run automated verification:
174
175```bash
176# Backend
177cd backend
178python scripts/verify_setup.py
179
180# Should show all ✅ checks
181```
182
183## Production Readiness
184
185Before deploying to production:
186
187- [ ] All tests passing
188- [ ] Environment variables configured
189- [ ] Database migrations applied
190- [ ] Storage configured (S3 or persistent volume)
191- [ ] Monitoring set up
192- [ ] Logging configured
193- [ ] Security review completed
194- [ ] Performance tested
195- [ ] Documentation updated
196
197## Success Criteria
198
199✅ All checks pass
200✅ Backend responds to health check
201✅ Frontend loads without errors
202✅ Can create a generation
203✅ Generation completes successfully
204✅ Audio file is playable
205
206If all checks pass, you're ready to go! 🎉
207