LAUNCH_GUIDE.md

# 🚀 AudioForge Production Launch Guide

**Complete step-by-step guide for launching AudioForge to production**

---

## 📋 Pre-Launch Requirements

### System Requirements
- **Python**: 3.11+
- **Node.js**: 18+ 
- **pnpm**: 8+
- **Docker**: 24+ (optional, for containerized deployment)
- **PostgreSQL**: 16+
- **Redis**: 7+

### Hardware Recommendations
- **CPU**: 4+ cores (8+ recommended for music generation)
- **RAM**: 8GB minimum (16GB+ recommended)
- **Storage**: 50GB+ (models require ~10GB, audio storage scales with usage)
- **GPU**: Optional but highly recommended (CUDA-compatible for faster generation)

---

## 🔍 Step 1: Automated Verification

Run the comprehensive verification script to check all systems:

```bash

# From project root

python scripts/launch_verification.py --verbose



# Auto-fix common issues

python scripts/launch_verification.py --fix



# Export results to JSON

python scripts/launch_verification.py --json launch-report.json

```

**Expected Output**: 100% success rate on all checks

---

## 🛠️ Step 2: Environment Setup

### Backend Configuration

1. **Create `.env` file**:
```bash

cd backend

cp .env.example .env

```

2. **Configure environment variables**:
```bash

# Database

DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/audioforge



# Redis

REDIS_URL=redis://localhost:6379/0



# AI Models

MUSICGEN_DEVICE=cuda  # or 'cpu'

BARK_DEVICE=cuda      # or 'cpu'

DEMUCS_DEVICE=cuda    # or 'cpu'



# Application

DEBUG=false

ENVIRONMENT=production

SECRET_KEY=<generate-secure-key>

ALLOWED_ORIGINS=https://yourdomain.com



# Optional: Monitoring

SENTRY_DSN=<your-sentry-dsn>

```

3. **Generate secure secret key**:
```bash

python -c "import secrets; print(secrets.token_urlsafe(32))"

```

### Frontend Configuration

1. **Create `.env.local`**:
```bash

cd frontend

echo "NEXT_PUBLIC_API_URL=https://api.yourdomain.com" > .env.local

```

2. **For production build**:
```bash

# .env.production

NEXT_PUBLIC_API_URL=https://api.yourdomain.com

NEXT_PUBLIC_SENTRY_DSN=<your-sentry-dsn>

```

---

## 📦 Step 3: Install Dependencies

### Backend
```bash

cd backend



# Using uv (recommended)

uv pip install -e ".[dev]"



# Or using pip

pip install -e ".[dev]"



# Verify installation

python scripts/verify_setup.py

```

### Frontend
```bash

cd frontend



# Install dependencies

pnpm install



# Verify no errors

pnpm run type-check

pnpm run lint

```

---

## 🗄️ Step 4: Database Setup

### Initialize Database

```bash

cd backend



# Run migrations

python scripts/init_db.py



# Verify connection

python -c "from app.db.database import engine; print('✅ Database connected')"

```

### Create Required Tables

The `init_db.py` script automatically creates:
- `generations` table
- Indexes on frequently queried fields
- Initial schema

### Backup Strategy

```bash

# Create backup

pg_dump audioforge > backup_$(date +%Y%m%d).sql



# Restore backup

psql audioforge < backup_20260116.sql

```

---

## 🎵 Step 5: Download AI Models

### Automatic Download (Recommended)

Models will download automatically on first use. To pre-download:

```bash

cd backend

python -c "

from app.services.music_generation import MusicGenerationService

service = MusicGenerationService()

print('✅ Models downloaded')

"

```

### Manual Download

If automatic download fails:

1. **MusicGen** (~2GB):
```bash

python -c "

from transformers import AutoProcessor, MusicgenForConditionalGeneration

model = MusicgenForConditionalGeneration.from_pretrained('facebook/musicgen-small')

processor = AutoProcessor.from_pretrained('facebook/musicgen-small')

"

```

2. **Bark** (for vocals, ~3GB):
```bash

python -c "

from transformers import AutoProcessor, BarkModel

model = BarkModel.from_pretrained('suno/bark-small')

processor = AutoProcessor.from_pretrained('suno/bark-small')

"

```

3. **Demucs** (for separation, ~300MB):
```bash

python -c "

import torch

torch.hub.load('facebookresearch/demucs', 'demucs')

"

```

---

## 🧪 Step 6: Run Tests

### Backend Tests
```bash

cd backend

pytest tests/ -v --cov=app --cov-report=html



# Run specific test

pytest tests/test_prompt_understanding.py -v

```

### Frontend Tests
```bash

cd frontend



# Unit tests

pnpm test



# Integration tests

pnpm test src/test/integration.test.tsx



# Coverage report

pnpm test:coverage



# Watch mode during development

pnpm test:watch

```

### Integration Tests
```bash

# Ensure both services are running

# Terminal 1: Backend

cd backend && uvicorn app.main:app --reload



# Terminal 2: Frontend  

cd frontend && pnpm dev



# Terminal 3: Run E2E tests

python scripts/launch_verification.py --section integration

```

---

## 🚀 Step 7: Build for Production

### Backend

```bash

cd backend



# No build step needed for Python

# Ensure all dependencies are installed

pip freeze > requirements-lock.txt

```

### Frontend

```bash

cd frontend



# Production build

pnpm run build



# Test production build locally

pnpm run start



# Verify at http://localhost:3000

```

### Build Verification

```bash

# Check build output

ls -lh frontend/.next/



# Expected: optimized bundles, static assets

# Build should complete in < 2 minutes

```

---

## 🐳 Step 8: Docker Deployment (Recommended)

### Build Images

```bash

# Build all services

docker-compose build



# Build specific service

docker-compose build backend

docker-compose build frontend

```

### Start Services

```bash

# Start all services

docker-compose up -d



# Check status

docker-compose ps



# View logs

docker-compose logs -f



# Stop services

docker-compose down

```

### Health Checks

```bash

# Backend health

curl http://localhost:8000/health



# Frontend health

curl http://localhost:3000



# Database health

docker-compose exec postgres pg_isready



# Redis health

docker-compose exec redis redis-cli ping

```

---

## 🔧 Step 9: Manual Deployment

### Backend Deployment

1. **Using systemd** (Linux):

Create `/etc/systemd/system/audioforge-backend.service`:
```ini

[Unit]

Description=AudioForge Backend API

After=network.target postgresql.service redis.service



[Service]

Type=simple

User=audioforge

WorkingDirectory=/opt/audioforge/backend

Environment="PATH=/opt/audioforge/venv/bin"

ExecStart=/opt/audioforge/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Restart=always

RestartSec=10



[Install]

WantedBy=multi-user.target

```

Enable and start:
```bash

sudo systemctl enable audioforge-backend

sudo systemctl start audioforge-backend

sudo systemctl status audioforge-backend

```

2. **Using Gunicorn** (alternative):
```bash

gunicorn app.main:app \

  --workers 4 \

  --worker-class uvicorn.workers.UvicornWorker \

  --bind 0.0.0.0:8000 \

  --access-logfile - \

  --error-logfile -

```

### Frontend Deployment

1. **Using PM2**:
```bash

cd frontend



# Install PM2

npm install -g pm2



# Start application

pm2 start pnpm --name "audioforge-frontend" -- start



# Save configuration

pm2 save



# Setup startup script

pm2 startup

```

2. **Using systemd**:

Create `/etc/systemd/system/audioforge-frontend.service`:
```ini

[Unit]

Description=AudioForge Frontend

After=network.target



[Service]

Type=simple

User=audioforge

WorkingDirectory=/opt/audioforge/frontend

Environment="NODE_ENV=production"

ExecStart=/usr/bin/pnpm start

Restart=always

RestartSec=10



[Install]

WantedBy=multi-user.target

```

---

## 🌐 Step 10: Reverse Proxy Setup

### Nginx Configuration

Create `/etc/nginx/sites-available/audioforge`:

```nginx

# Backend API

upstream backend {

    server localhost:8000;

}



# Frontend

upstream frontend {

    server localhost:3000;

}



# Redirect HTTP to HTTPS

server {

    listen 80;

    server_name yourdomain.com api.yourdomain.com;

    return 301 https://$server_name$request_uri;

}



# Frontend HTTPS

server {

    listen 443 ssl http2;

    server_name yourdomain.com;



    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;

    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;

    ssl_ciphers HIGH:!aNULL:!MD5;



    # Security headers

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    add_header X-Frame-Options "SAMEORIGIN" always;

    add_header X-Content-Type-Options "nosniff" always;

    add_header X-XSS-Protection "1; mode=block" always;



    location / {

        proxy_pass http://frontend;

        proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;

        proxy_set_header Connection 'upgrade';

        proxy_set_header Host $host;

        proxy_cache_bypass $http_upgrade;

        proxy_set_header X-Real-IP $remote_addr;

        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        proxy_set_header X-Forwarded-Proto $scheme;

    }

}



# Backend API HTTPS

server {

    listen 443 ssl http2;

    server_name api.yourdomain.com;



    ssl_certificate /etc/letsencrypt/live/api.yourdomain.com/fullchain.pem;

    ssl_certificate_key /etc/letsencrypt/live/api.yourdomain.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;

    ssl_ciphers HIGH:!aNULL:!MD5;



    # Security headers

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    add_header X-Content-Type-Options "nosniff" always;



    # CORS headers (if needed)

    add_header Access-Control-Allow-Origin "https://yourdomain.com" always;

    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;

    add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;



    location / {

        proxy_pass http://backend;

        proxy_http_version 1.1;

        proxy_set_header Host $host;

        proxy_set_header X-Real-IP $remote_addr;

        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        proxy_set_header X-Forwarded-Proto $scheme;

        

        # Increase timeouts for long-running generation requests

        proxy_read_timeout 300s;

        proxy_connect_timeout 75s;

    }



    # API documentation

    location /docs {

        proxy_pass http://backend/docs;

        proxy_set_header Host $host;

    }

}

```

Enable and reload:
```bash

sudo ln -s /etc/nginx/sites-available/audioforge /etc/nginx/sites-enabled/

sudo nginx -t

sudo systemctl reload nginx

```

### SSL Certificates (Let's Encrypt)

```bash

# Install certbot

sudo apt install certbot python3-certbot-nginx



# Obtain certificates

sudo certbot --nginx -d yourdomain.com -d api.yourdomain.com



# Auto-renewal is configured automatically

# Test renewal

sudo certbot renew --dry-run

```

---

## 📊 Step 11: Monitoring Setup

### Application Monitoring

1. **Sentry** (Error Tracking):
```bash

# Backend

pip install sentry-sdk[fastapi]



# Add to app/main.py

import sentry_sdk

sentry_sdk.init(dsn="YOUR_SENTRY_DSN")



# Frontend

pnpm add @sentry/nextjs

# Configure in next.config.js

```

2. **Prometheus** (Metrics):
```bash

# Install prometheus client

pip install prometheus-client



# Expose metrics endpoint

# Already configured in app/core/metrics.py

```

3. **Grafana** (Dashboards):
```bash

docker run -d \

  -p 3001:3000 \

  --name=grafana \

  -e "GF_SECURITY_ADMIN_PASSWORD=admin" \

  grafana/grafana

```

### System Monitoring

```bash

# Install monitoring tools

sudo apt install htop iotop nethogs



# Monitor processes

htop



# Monitor disk I/O

iotop



# Monitor network

nethogs

```

### Log Aggregation

```bash

# Using journalctl

sudo journalctl -u audioforge-backend -f

sudo journalctl -u audioforge-frontend -f



# Centralized logging (optional)

# Configure with ELK stack or similar

```

---

## ✅ Step 12: Final Verification

### Automated Checks

```bash

# Run full verification

python scripts/launch_verification.py --verbose



# Expected: 100% pass rate

```

### Manual Verification Checklist

- [ ] Backend health endpoint responds: `curl https://api.yourdomain.com/health`
- [ ] Frontend loads: Visit `https://yourdomain.com`
- [ ] API documentation accessible: `https://api.yourdomain.com/docs`
- [ ] Create test generation works
- [ ] Audio playback works
- [ ] Status updates in real-time
- [ ] Error messages are user-friendly
- [ ] Mobile responsive design works
- [ ] All animations smooth (60fps)
- [ ] SSL certificates valid
- [ ] Monitoring dashboards active

### Performance Benchmarks

```bash

# Backend API response time

ab -n 1000 -c 10 https://api.yourdomain.com/health



# Frontend load time

lighthouse https://yourdomain.com --view



# Expected metrics:

# - Backend: < 200ms average

# - Frontend FCP: < 1.5s

# - Frontend TTI: < 3s

# - Lighthouse score: > 90

```

---

## 🚨 Step 13: Launch Day Procedures

### T-1 Hour

```bash

# 1. Final backup

pg_dump audioforge > pre-launch-backup.sql



# 2. Final verification

python scripts/launch_verification.py



# 3. Monitor system resources

htop



# 4. Clear logs

sudo journalctl --vacuum-time=1d



# 5. Notify team

echo "Launch in 1 hour" | mail -s "AudioForge Launch" team@example.com

```

### Launch (T=0)

```bash

# 1. Start services (if not already running)

docker-compose up -d



# 2. Verify all services healthy

docker-compose ps



# 3. Test end-to-end flow

curl -X POST https://api.yourdomain.com/api/v1/generations \

  -H "Content-Type: application/json" \

  -d '{"prompt": "Launch test", "duration": 10}'



# 4. Monitor logs

docker-compose logs -f

```

### T+1 Hour

```bash

# 1. Check error rates

curl https://api.yourdomain.com/metrics | grep error_total



# 2. Check generation success rate

# View in monitoring dashboard



# 3. Review user feedback

# Check support channels



# 4. Monitor system resources

htop

```

---

## 🔧 Troubleshooting

### Backend Won't Start

```bash

# Check logs

docker-compose logs backend



# Common issues:

# 1. Database connection

docker-compose exec postgres pg_isready



# 2. Missing dependencies

cd backend && pip install -e ".[dev]"



# 3. Port already in use

sudo lsof -i :8000

```

### Frontend Won't Build

```bash

# Check Node version

node --version  # Should be 18+



# Clear cache

rm -rf frontend/.next frontend/node_modules

cd frontend && pnpm install



# Check for TypeScript errors

pnpm run type-check

```

### Generation Fails

```bash

# Check model files

ls -lh ~/.cache/huggingface/



# Check GPU availability

python -c "import torch; print(torch.cuda.is_available())"



# Check disk space

df -h



# Check memory

free -h

```

### High CPU/Memory Usage

```bash

# Identify process

top -o %CPU



# Restart service

docker-compose restart backend



# Scale workers

# Edit docker-compose.yml: --workers 2

```

---

## 📈 Post-Launch Monitoring

### Daily Checks

- [ ] Error rate < 5%
- [ ] Average response time < 200ms
- [ ] Generation success rate > 95%
- [ ] Disk space > 20% free
- [ ] Database connections healthy
- [ ] SSL certificates valid (> 30 days)

### Weekly Tasks

- [ ] Review user feedback
- [ ] Analyze performance metrics
- [ ] Update dependencies
- [ ] Database backup verification
- [ ] Security audit

### Monthly Tasks

- [ ] Performance optimization review
- [ ] Cost analysis
- [ ] Feature roadmap update
- [ ] Team retrospective

---

## 🎉 Success Metrics

### Week 1 Goals
- 100+ generations created
- < 5% error rate
- Average processing time < 60s
- 90%+ user satisfaction

### Month 1 Goals
- 1,000+ total generations
- 100+ active users
- Feature requests collected
- Roadmap for v2 defined

---

## 📞 Support

### Emergency Contacts
- **Backend Issues**: Check `/var/log/audioforge/backend.log`
- **Frontend Issues**: Check browser console + Next.js logs
- **Database Issues**: Check PostgreSQL logs
- **Infrastructure**: Contact DevOps team

### Useful Commands

```bash

# Restart everything

docker-compose restart



# View all logs

docker-compose logs -f --tail=100



# Check service status

systemctl status audioforge-*



# Database backup

pg_dump audioforge > backup.sql



# Restore from backup

psql audioforge < backup.sql

```

---

**🐼⚡ You're ready to launch! The panda believes in you.** 🎵

*Remember: Launch is just the beginning. Listen to users, iterate fast, and keep the creative energy flowing.*