OnyxMunk/AudioForge

1# AudioForge Setup Guide
2
3Complete setup guide to get AudioForge running locally without errors.
4
5## Prerequisites
6
7- **Python 3.11+** (check with `python --version`)
8- **Node.js 20+** (check with `node --version`)
9- **PostgreSQL 16+** (or use Docker)
10- **Redis 7+** (or use Docker)
11- **Docker & Docker Compose** (optional, recommended)
12
13## Quick Start (Docker)
14
15The easiest way to get started:
16
17```bash
18# Clone and navigate to project
19cd AudioForge
20
21# Start all services
22docker-compose up -d
23
24# Backend will be at http://localhost:8000
25# Frontend will be at http://localhost:3000
26```
27
28## Manual Setup
29
30### Backend Setup
31
32#### Windows (PowerShell)
33
34```powershell
35cd backend
36.\scripts\setup.ps1
37```
38
39#### Linux/macOS
40
41```bash
42cd backend
43chmod +x scripts/setup.sh
44./scripts/setup.sh
45```
46
47#### Manual Steps
48
491. **Create virtual environment:**
50```bash
51cd backend
52python -m venv .venv
53# Windows
54.venv\Scripts\activate
55# Linux/macOS
56source .venv/bin/activate
57```
58
592. **Install dependencies:**
60```bash
61# Install uv (modern Python package manager)
62pip install uv
63
64# Install project dependencies
65uv pip install -e ".[dev]"
66```
67
683. **Configure environment:**
69```bash
70# Copy example env file
71cp .env.example .env
72
73# Edit .env with your settings
74# At minimum, set DATABASE_URL and REDIS_URL
75```
76
774. **Start PostgreSQL and Redis:**
78
79**Option A: Docker**
80```bash
81docker-compose up -d postgres redis
82```
83
84**Option B: Local Installation**
85- Install PostgreSQL and start service
86- Install Redis and start service
87- Update `.env` with connection URLs
88
895. **Run database migrations:**
90```bash
91alembic upgrade head
92```
93
946. **Start backend server:**
95```bash
96uvicorn app.main:app --reload
97```
98
99Backend will be available at http://localhost:8000
100API docs at http://localhost:8000/api/docs
101
102### Frontend Setup
103
1041. **Install dependencies:**
105```bash
106cd frontend
107pnpm install
108# or: npm install
109```
110
1112. **Configure environment:**
112```bash
113# Create .env.local
114echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local
115```
116
1173. **Start development server:**
118```bash
119pnpm dev
120# or: npm run dev
121```
122
123Frontend will be available at http://localhost:3000
124
125## Verification
126
127### Backend Health Check
128
129```bash
130curl http://localhost:8000/health
131# Should return: {"status":"healthy","version":"0.1.0"}
132```
133
134### Frontend Check
135
136Open http://localhost:3000 in your browser. You should see the AudioForge interface.
137
138## Common Issues & Solutions
139
140### Issue: Database Connection Error
141
142**Solution:**
143- Ensure PostgreSQL is running: `docker-compose ps` or `pg_isready`
144- Check DATABASE_URL in `.env` matches your PostgreSQL setup
145- Verify database exists: `createdb audioforge` (if needed)
146
147### Issue: Redis Connection Error
148
149**Solution:**
150- Ensure Redis is running: `docker-compose ps` or `redis-cli ping`
151- Check REDIS_URL in `.env`
152- Redis is optional for basic functionality
153
154### Issue: Model Loading Errors
155
156**Solution:**
157- MusicGen models download automatically on first use (can be slow)
158- Ensure sufficient disk space (~2GB for models)
159- For CPU-only: Set `MUSICGEN_DEVICE=cpu` in `.env`
160- Models load lazily - first generation may take longer
161
162### Issue: Port Already in Use
163
164**Solution:**
165- Backend: Change port in `uvicorn` command or `.env`
166- Frontend: Change port in `next.config.js` or use `pnpm dev -p 3001`
167- Stop conflicting services
168
169### Issue: Import Errors
170
171**Solution:**
172- Ensure virtual environment is activated
173- Reinstall dependencies: `uv pip install -e ".[dev]"`
174- Check Python version: `python --version` (needs 3.11+)
175
176### Issue: Frontend Build Errors
177
178**Solution:**
179- Clear cache: `rm -rf .next node_modules`
180- Reinstall: `pnpm install`
181- Check Node version: `node --version` (needs 20+)
182
183## Development Workflow
184
1851. **Backend changes:** Server auto-reloads with `--reload` flag
1862. **Frontend changes:** Next.js hot-reloads automatically
1873. **Database changes:** Create migration: `alembic revision --autogenerate -m "description"`
1884. **Apply migrations:** `alembic upgrade head`
189
190## Testing
191
192### Backend Tests
193```bash
194cd backend
195pytest tests/ -v
196```
197
198### Frontend Tests
199```bash
200cd frontend
201pnpm test
202```
203
204## Production Deployment
205
206See `ARCHITECTURE.md` for production deployment considerations.
207
208## Getting Help
209
210- Check logs: Backend logs to console, check for errors
211- API docs: http://localhost:8000/api/docs
212- Review `ARCHITECTURE.md` for system design
213- Check `CONTRIBUTING.md` for development guidelines
214