# Vision Videoke EC2 Deployment Package

## Overview

This package contains everything needed to deploy Vision Videoke on Amazon EC2 with Amazon Linux. Vision Videoke is a revolutionary platform that transforms vision boards into personalized music videos with karaoke lyrics.

## What's Included

### 🚀 One-Click Installation
- **customer-installer.sh** - Automated installer for customers
- **advanced-installer.sh** - Advanced installer with additional features
- **minimal-installer.sh** - Minimal installer without application package

### 🔧 System Scripts
- **ec2-setup.sh** - Complete EC2 system setup
- **configure-nginx.sh** - Nginx web server configuration
- **production-config.sh** - Production environment configuration
- **build-and-deploy.sh** - Application build and deployment
- **setup-ssl.sh** - SSL certificate setup with Let's Encrypt

### 📋 Configuration Files
- **nginx.conf** - Production-ready Nginx configuration
- **ecosystem.config.js** - PM2 process management configuration
- **Environment templates** - Production environment templates

### 📚 Documentation
- **DEPLOYMENT_GUIDE.md** - Complete technical deployment guide
- **CUSTOMER_GUIDE.md** - Customer-friendly setup instructions
- **TROUBLESHOOTING.md** - Common issues and solutions
- **API_DOCUMENTATION.md** - API integration guides

### 🛠️ Management Tools
- **package-creator.sh** - Creates customer distribution packages
- **Health monitoring scripts** - Automated system health checks
- **Backup and restore scripts** - Data protection utilities
- **Performance optimization scripts** - System tuning utilities

## Quick Start

### For Customers (Recommended)

1. **Upload package to EC2 instance:**
   ```bash
   scp -i your-key.pem VisionVideoke-EC2-Installer-1.0.0.tar.gz ec2-user@your-server-ip:~/
   ```

2. **Extract and run installer:**
   ```bash
   tar -xzf VisionVideoke-EC2-Installer-1.0.0.tar.gz
   cd VisionVideoke-EC2-Installer-1.0.0
   ./customer-installer.sh
   ```

3. **Follow the prompts** for domain, email, and API keys

### For Advanced Users

1. **Clone or download this repository**
2. **Run individual scripts as needed:**
   ```bash
   ./scripts/ec2-setup.sh
   ./scripts/configure-nginx.sh your-domain.com
   ./scripts/production-config.sh
   ./scripts/build-and-deploy.sh
   ```

## System Requirements

### AWS Infrastructure
- **EC2 Instance**: t3.medium or larger (2 vCPUs, 4GB RAM minimum)
- **Operating System**: Amazon Linux 2
- **Storage**: 20GB+ EBS volume (gp3 recommended)
- **Network**: VPC with public subnet and internet gateway
- **Security Group**: Ports 22 (SSH), 80 (HTTP), 443 (HTTPS)

### Prerequisites
- Domain name with DNS management access
- API keys for OpenAI, Udio, and ElevenLabs
- Email address for SSL certificate
- Basic AWS knowledge

### Estimated Costs
- **AWS Infrastructure**: ~$40-60/month
- **API Usage**: ~$0.60-2.60 per song created
- **SSL Certificate**: Free (Let's Encrypt)

## Features

### 🎨 Vision Board to Music Video
- Upload 3-10 images as vision board
- AI analyzes images for mood and themes
- Generates custom lyrics based on visual content
- Creates music with Udio AI
- Produces slideshow video with karaoke lyrics

### 🤖 AI-Powered Creation
- **OpenAI GPT-4 Vision** for image analysis and lyric generation
- **Udio API** for high-quality music generation
- **ElevenLabs** for voice cloning and personalization
- **Veo API** for advanced video generation (optional)

### 🎵 Professional Features
- Real-time lyric editing and refinement
- Multiple music genres and styles
- Voice cloning for personalized singing
- Social media ready video exports
- Payment processing with Stripe

### 🔒 Production-Ready Security
- SSL/TLS encryption with auto-renewal
- Firewall configuration (firewalld)
- Intrusion prevention (fail2ban)
- Secure file permissions and access controls
- Regular security updates

### 📊 Monitoring & Maintenance
- Automated health checks and alerts
- Daily backup system with retention
- Log rotation and management
- Performance monitoring with PM2
- System resource monitoring

## Architecture

### Application Stack
- **Frontend**: React 18 with TypeScript and Tailwind CSS
- **Backend**: Node.js with Express (optional)
- **Process Manager**: PM2 with cluster mode
- **Web Server**: Nginx with reverse proxy
- **SSL**: Let's Encrypt with automatic renewal

### File Structure
```
/var/www/visionvideoke/          # Application directory
├── dist/                        # Built application files
├── src/                         # Source code (if deployed)
├── .env                         # Environment configuration
├── package.json                 # Node.js dependencies
└── ecosystem.config.js          # PM2 configuration

/var/log/visionvideoke/          # Application logs
├── combined.log                 # All application logs
├── error.log                    # Error logs only
└── access.log                   # Access logs

/var/backups/visionvideoke/      # Automated backups
├── backup-YYYYMMDD-HHMMSS.tar.gz
└── ...

/etc/nginx/sites-available/      # Nginx configuration
└── visionvideoke                # Site configuration

/etc/letsencrypt/live/           # SSL certificates
└── your-domain.com/
```

### Network Architecture
```
Internet → CloudFront (optional) → ALB (optional) → Nginx → PM2 → React App
                                                         ↓
                                                    API Services
                                                    (OpenAI, Udio, ElevenLabs)
```

## API Integrations

### Required APIs
- **OpenAI API** - GPT-4 Vision for image analysis and lyric generation
- **Udio API** - Music generation from lyrics and style prompts
- **ElevenLabs API** - Voice cloning and speech synthesis

### Optional APIs
- **Veo API** - Advanced video generation capabilities
- **Stripe API** - Payment processing for premium features
- **AWS S3** - File storage for uploads and generated content

### API Configuration
All API keys are configured in the environment file:
```env
REACT_APP_OPENAI_API_KEY=your_openai_key
REACT_APP_UDIO_API_KEY=your_udio_key
REACT_APP_ELEVENLABS_API_KEY=your_elevenlabs_key
```

## Deployment Options

### 1. One-Click Customer Installer
- **Best for**: Non-technical customers
- **Time**: 15-20 minutes
- **Includes**: Complete automated setup
- **Features**: All security, monitoring, and backup features

### 2. Manual Script-Based Deployment
- **Best for**: Technical users who want control
- **Time**: 30-45 minutes
- **Includes**: Individual scripts for each component
- **Features**: Customizable configuration options

### 3. Advanced Enterprise Deployment
- **Best for**: High-traffic production deployments
- **Time**: 1-2 hours
- **Includes**: Load balancing, auto-scaling, database setup
- **Features**: Enterprise-grade monitoring and alerting

## Management Commands

### Application Management
```bash
pm2 status              # Check application status
pm2 logs                # View application logs
pm2 restart all         # Restart application
pm2 reload all          # Zero-downtime reload
pm2 monit               # Monitor resources
```

### System Management
```bash
./status.sh             # Complete system status check
./backup.sh             # Create manual backup
./update-app.sh         # Update application
./optimize-performance.sh # Performance optimization
sudo systemctl status nginx # Check web server
```

### SSL Management
```bash
sudo certbot certificates    # Check certificate status
sudo certbot renew          # Renew certificates
sudo certbot renew --dry-run # Test renewal process
```

### Log Management
```bash
tail -f /var/log/visionvideoke/combined.log  # Real-time app logs
sudo tail -f /var/log/nginx/access.log       # Web server access logs
sudo tail -f /var/log/nginx/error.log        # Web server error logs
```

## Monitoring & Alerts

### Health Checks
- **Application health**: HTTP endpoint monitoring
- **System resources**: CPU, memory, disk usage
- **Service status**: PM2, Nginx, SSL certificate
- **API connectivity**: External service availability

### Automated Monitoring
- **Health check script**: Runs every 5 minutes
- **Backup script**: Runs daily at 2 AM
- **Log rotation**: Weekly log cleanup
- **SSL renewal**: Automatic certificate renewal

### Alert Conditions
- Application downtime
- High resource usage (>80%)
- SSL certificate expiry (30 days)
- Disk space low (<10%)
- API service failures

## Scaling & Performance

### Vertical Scaling
- **t3.medium** → **t3.large** → **t3.xlarge**
- No configuration changes required
- Automatic resource utilization

### Horizontal Scaling
- Application Load Balancer (ALB)
- Auto Scaling Groups
- RDS for shared database
- ElastiCache for session storage
- S3 for file storage

### Performance Optimization
- PM2 cluster mode (automatic)
- Nginx gzip compression
- Static asset caching
- CDN integration (CloudFront)
- Database query optimization

## Security Features

### Network Security
- **Firewall**: Minimal required ports only
- **Fail2ban**: Intrusion prevention system
- **SSL/TLS**: End-to-end encryption
- **Security headers**: HSTS, CSP, X-Frame-Options

### Application Security
- **Environment isolation**: Secure configuration management
- **File permissions**: Restricted access controls
- **Input validation**: API request sanitization
- **Rate limiting**: API abuse prevention

### Data Protection
- **Encrypted storage**: SSL for data in transit
- **Secure backups**: Encrypted backup files
- **API key protection**: Environment-based storage
- **Access logging**: Complete audit trail

## Troubleshooting

### Common Issues
1. **Application won't start** → Check PM2 status and logs
2. **502 Bad Gateway** → Verify application and Nginx status
3. **SSL certificate issues** → Check certificate status and renewal
4. **High memory usage** → Restart PM2 with memory limits
5. **API connectivity** → Verify API keys and network access

### Diagnostic Tools
- `./status.sh` - Complete system health check
- `pm2 logs` - Application logs and errors
- `sudo nginx -t` - Nginx configuration validation
- `curl http://localhost:3000/health` - Application health check

### Log Analysis
- Application logs: `/var/log/visionvideoke/`
- Web server logs: `/var/log/nginx/`
- System logs: `/var/log/messages`
- PM2 logs: `pm2 logs`

## Support & Documentation

### Documentation Files
- **DEPLOYMENT_GUIDE.md** - Technical deployment instructions
- **CUSTOMER_GUIDE.md** - Customer-friendly setup guide
- **TROUBLESHOOTING.md** - Common issues and solutions
- **API_DOCUMENTATION.md** - API integration details

### Getting Help
1. **Check documentation** in the `docs/` directory
2. **Run diagnostics** with `./status.sh`
3. **Collect logs** for support requests
4. **Search error messages** in troubleshooting guide

### Version Information
- **Package Version**: 1.0.0
- **Build Date**: $(date)
- **Supported OS**: Amazon Linux 2
- **Node.js Version**: 18.x LTS
- **PM2 Version**: Latest stable

## License & Legal

### Software Licenses
- Vision Videoke: Proprietary license
- Node.js: MIT License
- Nginx: BSD-2-Clause License
- PM2: AGPL-3.0 License
- Let's Encrypt: Free SSL certificates

### API Terms
- OpenAI: Subject to OpenAI Terms of Service
- Udio: Subject to Udio API Terms
- ElevenLabs: Subject to ElevenLabs Terms
- Stripe: Subject to Stripe Terms of Service

### Data Privacy
- User data processed according to privacy policy
- API data handling per service provider terms
- Backup data encrypted and secured
- Log data retention policies applied

## Contributing

### Development Setup
1. Clone the repository
2. Set up development environment
3. Test changes in isolated environment
4. Submit pull requests for review

### Package Updates
1. Update version numbers
2. Test all installation methods
3. Update documentation
4. Create new distribution packages

### Bug Reports
- Include system information
- Provide error logs
- Describe reproduction steps
- Test with latest version

---

**Vision Videoke EC2 Deployment Package v1.0.0**

*Transform vision boards into personalized music videos with AI-powered creativity and professional deployment infrastructure.*

For technical support and updates, refer to the documentation in the `docs/` directory or contact your system administrator.

