v

Universal_AI_Agent/docs/DEPLOYMENT_GUIDE.md

@@ -0,0 +1,644 @@
+# Universal AI Agent - Complete Deployment Guide
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Local Development](#local-development)
+3. [Docker Deployment](#docker-deployment)
+4. [Kubernetes Production Deployment](#kubernetes-production-deployment)
+5. [Cloud Platform Deployment](#cloud-platform-deployment)
+6. [Mobile App Setup](#mobile-app-setup)
+7. [Monitoring and Analytics](#monitoring-and-analytics)
+8. [Security Configuration](#security-configuration)
+9. [Troubleshooting](#troubleshooting)
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18+
+- Docker and Docker Compose
+- Redis (optional, for caching)
+- PostgreSQL (optional, for persistence)
+
+### 1-Minute Setup
+
+```bash
+# Clone and setup
+git clone <repository-url>
+cd Universal_AI_Agent
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your API keys
+
+# Start with Docker
+docker-compose up -d
+
+# Access the application
+open http://localhost:8787
+```
+
+## Local Development
+
+### Environment Setup
+
+1. **Install Dependencies**
+
+   ```bash
+   npm install
+   ```
+
+2. **Configure Environment Variables**
+
+   ```bash
+   # Copy example environment file
+   cp .env.example .env
+   
+   # Edit .env file with your configuration
+   nano .env
+   ```
+
+3. **Required Environment Variables**
+
+   ```env
+   # Core Configuration
+   PORT=8787
+   NODE_ENV=development
+   
+   # AI Provider Keys
+   OPENAI_API_KEY=your_openai_key_here
+   ANTHROPIC_API_KEY=your_anthropic_key_here
+   
+   # Azure Speech (for voice features)
+   AZURE_SPEECH_KEY=your_azure_speech_key
+   AZURE_SPEECH_REGION=your_azure_region
+   
+   # Database URLs (optional)
+   REDIS_URL=redis://localhost:6379
+   POSTGRES_URL=postgres://user:password@localhost:5432/agent
+   
+   # Security
+   AUTH_TOKEN=your_secure_bearer_token
+   JWT_SECRET=your_jwt_secret_key
+   
+   # Rate Limiting
+   RATE_LIMIT_WINDOW_MS=60000
+   RATE_LIMIT_MAX=100
+   
+   # Feature Flags
+   ALLOW_WEB_FETCH=true
+   ALLOW_GIT_INFO=true
+   ALLOW_FS_READ=true
+   ALLOW_POWERSHELL=false
+   LOG_JSON=true
+   ```
+
+4. **Start Development Server**
+
+   ```bash
+   npm run dev
+   ```
+
+### Development Features
+
+- **Hot Reload**: Server automatically restarts on file changes
+- **Debug Mode**: Detailed logging and error traces
+- **Memory Persistence**: File-based memory for development
+- **Plugin Development**: Hot-reload plugins without restart
+
+## Docker Deployment
+
+### Single Container
+
+```bash
+# Build the image
+docker build -t universal-ai-agent .
+
+# Run with environment file
+docker run -d \
+  --name ai-agent \
+  --env-file .env \
+  -p 8787:8787 \
+  -v $(pwd)/memory:/app/memory \
+  universal-ai-agent
+```
+
+### Full Stack with Docker Compose
+
+```bash
+# Start all services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Scale the application
+docker-compose up -d --scale app=3
+
+# Stop all services
+docker-compose down
+```
+
+### Docker Compose Configuration
+
+```yaml
+version: '3.8'
+services:
+  app:
+    build: .
+    ports:
+      - "8787:8787"
+    environment:
+      - REDIS_URL=redis://redis:6379
+      - POSTGRES_URL=postgres://postgres:postgres@postgres:5432/agent
+    depends_on:
+      - redis
+      - postgres
+    volumes:
+      - ./memory:/app/memory
+      - ./logs:/app/logs
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+
+  postgres:
+    image: postgres:15-alpine
+    environment:
+      POSTGRES_DB: agent
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  redis_data:
+  postgres_data:
+```
+
+## Kubernetes Production Deployment
+
+### Prerequisites
+
+- Kubernetes cluster (1.20+)
+- kubectl configured
+- Ingress controller (nginx recommended)
+- cert-manager for SSL certificates
+
+### 1. Create Namespace
+
+```bash
+kubectl create namespace ai-agent
+```
+
+### 2. Create Secrets
+
+```bash
+# AI API Keys
+kubectl create secret generic ai-keys \
+  --from-literal=openai-key=your_openai_key \
+  --from-literal=anthropic-key=your_anthropic_key \
+  --from-literal=azure-speech-key=your_azure_key \
+  --from-literal=azure-speech-region=your_region \
+  -n ai-agent
+
+# Database Connection
+kubectl create secret generic postgres-secret \
+  --from-literal=connection-string=postgres://user:pass@postgres:5432/agent \
+  -n ai-agent
+
+# Authentication
+kubectl create secret generic auth-secret \
+  --from-literal=bearer-token=your_secure_token \
+  --from-literal=jwt-secret=your_jwt_secret \
+  -n ai-agent
+```
+
+### 3. Deploy Infrastructure
+
+```bash
+# Deploy Redis
+kubectl apply -f k8s/redis.yaml -n ai-agent
+
+# Deploy PostgreSQL
+kubectl apply -f k8s/postgres.yaml -n ai-agent
+
+# Wait for databases to be ready
+kubectl wait --for=condition=ready pod -l app=redis -n ai-agent --timeout=300s
+kubectl wait --for=condition=ready pod -l app=postgres -n ai-agent --timeout=300s
+```
+
+### 4. Deploy Application
+
+```bash
+# Deploy the main application
+kubectl apply -f k8s/deployment.yaml -n ai-agent
+
+# Check deployment status
+kubectl get pods -n ai-agent
+kubectl logs -f deployment/universal-ai-agent -n ai-agent
+```
+
+### 5. Configure Ingress
+
+```bash
+# Update the ingress with your domain
+sed -i 's/ai-agent.yourdomain.com/your-actual-domain.com/g' k8s/deployment.yaml
+
+# Apply ingress configuration
+kubectl apply -f k8s/deployment.yaml -n ai-agent
+
+# Check ingress status
+kubectl get ingress -n ai-agent
+```
+
+### 6. Monitor Deployment
+
+```bash
+# Check all resources
+kubectl get all -n ai-agent
+
+# View application logs
+kubectl logs -f deployment/universal-ai-agent -n ai-agent
+
+# Check horizontal pod autoscaler
+kubectl get hpa -n ai-agent
+```
+
+## Cloud Platform Deployment
+
+### AWS EKS
+
+```bash
+# Create EKS cluster
+eksctl create cluster --name ai-agent-cluster --region us-west-2
+
+# Configure kubectl
+aws eks update-kubeconfig --region us-west-2 --name ai-agent-cluster
+
+# Deploy application
+kubectl apply -f k8s/ -n ai-agent
+```
+
+### Google GKE
+
+```bash
+# Create GKE cluster
+gcloud container clusters create ai-agent-cluster \
+  --zone us-central1-a \
+  --num-nodes 3
+
+# Get credentials
+gcloud container clusters get-credentials ai-agent-cluster --zone us-central1-a
+
+# Deploy application
+kubectl apply -f k8s/ -n ai-agent
+```
+
+### Azure AKS
+
+```bash
+# Create resource group
+az group create --name ai-agent-rg --location eastus
+
+# Create AKS cluster
+az aks create \
+  --resource-group ai-agent-rg \
+  --name ai-agent-cluster \
+  --node-count 3 \
+  --enable-addons monitoring \
+  --generate-ssh-keys
+
+# Get credentials
+az aks get-credentials --resource-group ai-agent-rg --name ai-agent-cluster
+
+# Deploy application
+kubectl apply -f k8s/ -n ai-agent
+```
+
+### Serverless Deployment
+
+#### Vercel
+
+```bash
+# Install Vercel CLI
+npm i -g vercel
+
+# Deploy
+vercel --prod
+
+# Configure environment variables in Vercel dashboard
+```
+
+#### Netlify
+
+```bash
+# Install Netlify CLI
+npm i -g netlify-cli
+
+# Deploy
+netlify deploy --prod --dir=.
+
+# Configure environment variables in Netlify dashboard
+```
+
+## Mobile App Setup
+
+### React Native Setup
+
+1. **Prerequisites**
+
+   ```bash
+   # Install React Native CLI
+   npm install -g react-native-cli
+   
+   # For iOS development (macOS only)
+   sudo gem install cocoapods
+   
+   # For Android development
+   # Install Android Studio and configure SDK
+   ```
+
+2. **Initialize Project**
+
+   ```bash
+   # Create new React Native project
+   npx react-native init UniversalAIAgent
+   cd UniversalAIAgent
+   
+   # Copy the mobile app code
+   cp ../mobile/react-native-app.js App.js
+   
+   # Install dependencies
+   npm install @react-native-async-storage/async-storage
+   npm install @react-native-netinfo/netinfo
+   npm install @react-native-voice/voice
+   npm install expo-av
+   ```
+
+3. **Configure API Endpoints**
+
+   ```javascript
+   // Update API_BASE_URL in App.js
+   const API_BASE_URL = 'https://your-deployed-domain.com';
+   const WS_URL = 'wss://your-deployed-domain.com';
+   ```
+
+4. **Build and Run**
+
+   ```bash
+   # For iOS
+   npx react-native run-ios
+   
+   # For Android
+   npx react-native run-android
+   ```
+
+### Flutter Alternative
+
+```bash
+# Create Flutter project
+flutter create universal_ai_agent
+cd universal_ai_agent
+
+# Add dependencies to pubspec.yaml
+flutter pub add http
+flutter pub add web_socket_channel
+flutter pub add shared_preferences
+flutter pub add speech_to_text
+
+# Run the app
+flutter run
+```
+
+## Monitoring and Analytics
+
+### Built-in Analytics Dashboard
+
+Access the analytics dashboard at: `https://your-domain.com/analytics`
+
+Features:
+
+- Real-time metrics
+- Performance monitoring
+- User analytics
+- Cost tracking
+- System health
+
+### External Monitoring
+
+#### Prometheus + Grafana
+
+```bash
+# Deploy monitoring stack
+kubectl apply -f monitoring/prometheus.yaml
+kubectl apply -f monitoring/grafana.yaml
+
+# Access Grafana dashboard
+kubectl port-forward svc/grafana 3000:3000
+```
+
+#### DataDog Integration
+
+```javascript
+// Add to server.js
+import { StatsD } from 'node-statsd';
+const statsd = new StatsD();
+
+// Track metrics
+statsd.increment('requests.total');
+statsd.timing('response.time', responseTime);
+```
+
+## Security Configuration
+
+### SSL/TLS Setup
+
+#### Let's Encrypt with cert-manager
+
+```bash
+# Install cert-manager
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
+
+# Create ClusterIssuer
+kubectl apply -f k8s/cert-issuer.yaml
+```
+
+### Authentication Options
+
+#### JWT Authentication
+
+```env
+AUTH_TOKEN=your_bearer_token
+JWT_SECRET=your_jwt_secret_256_bit
+```
+
+#### OAuth Integration
+
+```env
+GOOGLE_CLIENT_ID=your_google_client_id
+GOOGLE_CLIENT_SECRET=your_google_client_secret
+GITHUB_CLIENT_ID=your_github_client_id
+GITHUB_CLIENT_SECRET=your_github_client_secret
+```
+
+### Security Best Practices
+
+1. **Environment Variables**: Never commit secrets to version control
+2. **Rate Limiting**: Configure appropriate limits for your use case
+3. **CORS**: Configure CORS for your domain
+4. **Input Validation**: Enable strict input validation
+5. **Monitoring**: Set up security monitoring and alerts
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Application Won't Start
+
+```bash
+# Check logs
+docker-compose logs app
+
+# Common causes:
+# - Missing environment variables
+# - Database connection issues
+# - Port conflicts
+```
+
+#### 2. Database Connection Errors
+
+```bash
+# Test Redis connection
+redis-cli -h localhost -p 6379 ping
+
+# Test PostgreSQL connection
+psql -h localhost -p 5432 -U postgres -d agent
+```
+
+#### 3. High Memory Usage
+
+```bash
+# Monitor memory usage
+docker stats
+
+# Restart if needed
+docker-compose restart app
+```
+
+#### 4. SSL Certificate Issues
+
+```bash
+# Check certificate status
+kubectl describe certificate ai-agent-tls -n ai-agent
+
+# Force certificate renewal
+kubectl delete certificate ai-agent-tls -n ai-agent
+kubectl apply -f k8s/deployment.yaml -n ai-agent
+```
+
+### Performance Optimization
+
+#### 1. Database Optimization
+
+```sql
+-- Create indexes for better performance
+CREATE INDEX idx_conversations_user_id ON conversations(user_id);
+CREATE INDEX idx_conversations_timestamp ON conversations(timestamp);
+CREATE INDEX idx_vector_embeddings ON documents USING ivfflat (embedding vector_cosine_ops);
+```
+
+#### 2. Caching Strategy
+
+```javascript
+// Configure Redis caching
+const cacheConfig = {
+  conversations: 3600, // 1 hour
+  embeddings: 86400,   // 24 hours
+  responses: 1800      // 30 minutes
+};
+```
+
+#### 3. Load Balancing
+
+```yaml
+# Update deployment for multiple replicas
+spec:
+  replicas: 5
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxSurge: 2
+      maxUnavailable: 1
+```
+
+### Health Checks
+
+#### Application Health
+
+```bash
+# Health check endpoint
+curl https://your-domain.com/health
+
+# Expected response:
+{
+  "status": "healthy",
+  "uptime": 3600,
+  "memory": "512MB",
+  "connections": {
+    "redis": "connected",
+    "postgres": "connected"
+  }
+}
+```
+
+#### Kubernetes Health
+
+```bash
+# Check pod health
+kubectl get pods -n ai-agent
+
+# Check service endpoints
+kubectl get endpoints -n ai-agent
+
+# Check ingress status
+kubectl describe ingress ai-agent-ingress -n ai-agent
+```
+
+## Support and Maintenance
+
+### Backup Strategy
+
+```bash
+# Database backups
+kubectl exec -it postgres-pod -- pg_dump -U postgres agent > backup.sql
+
+# Redis backup
+kubectl exec -it redis-pod -- redis-cli BGSAVE
+```
+
+### Updates and Upgrades
+
+```bash
+# Update application
+docker build -t universal-ai-agent:v2.0.0 .
+kubectl set image deployment/universal-ai-agent ai-agent=universal-ai-agent:v2.0.0 -n ai-agent
+
+# Monitor rollout
+kubectl rollout status deployment/universal-ai-agent -n ai-agent
+```
+
+### Scaling Guidelines
+
+- **CPU**: Scale up when CPU usage > 70%
+- **Memory**: Scale up when memory usage > 80%
+- **Response Time**: Scale up when avg response time > 2 seconds
+- **Queue Length**: Scale up when request queue > 100
+
+For additional support, please refer to the [API Documentation](API_REFERENCE.md) and [Plugin Development Guide](PLUGIN_DEVELOPMENT.md).