Spaces:

OnyxMunk
/

AudioForge

Build error

App Files Files Community

AudioForge / LAUNCH_GUIDE.md

OnyxlMunkey

c618549 15 days ago

preview code

raw

history blame contribute delete

16.8 kB

🚀 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:

# 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

Create .env file:

cd backend
cp .env.example .env

Configure environment variables:

# 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>

Generate secure secret key:

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

Frontend Configuration

Create .env.local:

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

For production build:

# .env.production
NEXT_PUBLIC_API_URL=https://api.yourdomain.com
NEXT_PUBLIC_SENTRY_DSN=<your-sentry-dsn>

📦 Step 3: Install Dependencies

Backend

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

cd frontend

# Install dependencies
pnpm install

# Verify no errors
pnpm run type-check
pnpm run lint

🗄️ Step 4: Database Setup

Initialize Database

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

# 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:

cd backend
python -c "
from app.services.music_generation import MusicGenerationService
service = MusicGenerationService()
print('✅ Models downloaded')
"

Manual Download

If automatic download fails:

MusicGen (~2GB):

python -c "
from transformers import AutoProcessor, MusicgenForConditionalGeneration
model = MusicgenForConditionalGeneration.from_pretrained('facebook/musicgen-small')
processor = AutoProcessor.from_pretrained('facebook/musicgen-small')
"

Bark (for vocals, ~3GB):

python -c "
from transformers import AutoProcessor, BarkModel
model = BarkModel.from_pretrained('suno/bark-small')
processor = AutoProcessor.from_pretrained('suno/bark-small')
"

Demucs (for separation, ~300MB):

python -c "
import torch
torch.hub.load('facebookresearch/demucs', 'demucs')
"

🧪 Step 6: Run Tests

Backend Tests

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

# Run specific test
pytest tests/test_prompt_understanding.py -v

Frontend Tests

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

# 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

cd backend

# No build step needed for Python
# Ensure all dependencies are installed
pip freeze > requirements-lock.txt

Frontend

cd frontend

# Production build
pnpm run build

# Test production build locally
pnpm run start

# Verify at http://localhost:3000

Build Verification

# 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

# Build all services
docker-compose build

# Build specific service
docker-compose build backend
docker-compose build frontend

Start Services

# 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

# 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

Using systemd (Linux):

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

[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:

sudo systemctl enable audioforge-backend
sudo systemctl start audioforge-backend
sudo systemctl status audioforge-backend

Using Gunicorn (alternative):

gunicorn app.main:app \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000 \
  --access-logfile - \
  --error-logfile -

Frontend Deployment

Using PM2:

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

Using systemd:

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

[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:

# 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:

sudo ln -s /etc/nginx/sites-available/audioforge /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

SSL Certificates (Let's Encrypt)

# 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

Sentry (Error Tracking):

# 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

Prometheus (Metrics):

# Install prometheus client
pip install prometheus-client

# Expose metrics endpoint
# Already configured in app/core/metrics.py

Grafana (Dashboards):

docker run -d \
  -p 3001:3000 \
  --name=grafana \
  -e "GF_SECURITY_ADMIN_PASSWORD=admin" \
  grafana/grafana

System Monitoring

# Install monitoring tools
sudo apt install htop iotop nethogs

# Monitor processes
htop

# Monitor disk I/O
iotop

# Monitor network
nethogs

Log Aggregation

# 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

# 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

# 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

# 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)

# 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

# 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

# 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

# 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

# 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

# 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

# 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.