# Hosting Service Deployment Guide

This comprehensive guide covers deploying Utils Bot Plus to popular cloud hosting services using the automated Docker setup. Each platform has specific requirements and optimizations covered in detail.

## Table of Contents

1. [Overview](#overview)
2. [Render.com Deployment](#rendercom-deployment)
3. [Railway Deployment](#railway-deployment)
4. [Heroku Deployment](#heroku-deployment)
5. [Platform Comparison](#platform-comparison)
6. [Environment Configuration](#environment-configuration)
7. [Monitoring and Maintenance](#monitoring-and-maintenance)
8. [Cost Optimization](#cost-optimization)
9. [Migration Between Services](#migration-between-services)
10. [Troubleshooting by Platform](#troubleshooting-by-platform)

## Overview

Utils Bot Plus supports deployment to multiple hosting services with automated configuration. The bot includes:

- **Health Check Integration**: Monitoring endpoints for each platform
- **Environment Detection**: Automatic platform-specific optimizations
- **Graceful Scaling**: Resource-aware performance tuning
- **Persistent Storage**: Database and file management

### Supported Platforms

| Platform | Free Tier | Pros | Best For |
|----------|-----------|------|----------|
| **Render** | 750 hours/month | Excellent docs, automatic SSL | Production deployments |
| **Railway** | $5 credit/month | Simple setup, great DX | Development and testing |
| **Heroku** | Limited free tier | Mature platform, add-ons | Enterprise applications |

## Render.com Deployment

Render provides excellent Docker support with automatic deployments and SSL certificates.

### Prerequisites

1. [Render account](https://render.com)
2. GitHub repository with your bot code
3. Discord bot token

### Step-by-Step Deployment

#### 1. Prepare Repository

Ensure your repository has the required files:

```bash
# Verify required files exist
ls -la Dockerfile.prod render.yaml docker-setup.sh
```

#### 2. Create Render Service

1. **Connect Repository**:
   - Go to [Render Dashboard](https://dashboard.render.com)
   - Click "New +" → "Web Service"
   - Connect your GitHub repository

2. **Configure Service**:
   - **Name**: `utils-bot-plus`
   - **Environment**: `Docker`
   - **Dockerfile Path**: `./Dockerfile.prod`
   - **Build Command**: `./docker-setup.sh`

#### 3. Environment Variables

Set these in Render dashboard:

```bash
# Required
DISCORD_TOKEN=your_bot_token_here

# Auto-generated by build script
SECRET_KEY=auto_generated_during_build
DATABASE_URL=sqlite:///data/bot.db

# Render-specific
PORT=10000
RENDER=true
```

#### 4. Advanced Settings

```yaml
# render.yaml (auto-detected)
services:
  - type: web
    name: utils-bot-plus
    env: docker
    dockerfilePath: ./Dockerfile.prod
    buildCommand: "./docker-setup.sh"
    startCommand: "python main_hosted.py"
    healthCheckPath: /health
    envVars:
      - key: DISCORD_TOKEN
        sync: false
      - key: PORT
        value: 10000
      - key: RENDER
        value: true
    disk:
      name: bot-data
      mountPath: /app/data
      sizeGB: 1
```

#### 5. Deploy

1. Click "Create Web Service"
2. Monitor build logs for any issues
3. Wait for health check to pass
4. Verify bot is online in Discord

### Render-Specific Features

#### Persistent Storage

```yaml
# In render.yaml
disk:
  name: bot-data
  mountPath: /app/data
  sizeGB: 1
```

#### Custom Domains

```yaml
# Add custom domain
customDomains:
  - name: bot.yourdomain.com
```

#### Auto-Deploy

Render automatically deploys on git pushes to main branch.

## Railway Deployment

Railway offers simple deployment with excellent developer experience.

### Prerequisites

1. [Railway account](https://railway.app)
2. GitHub repository
3. Discord bot token

### Step-by-Step Deployment

#### 1. Create Project

```bash
# Option A: Railway CLI
npm install -g @railway/cli
railway login
railway new

# Option B: Web Interface
# Visit https://railway.app/new
```

#### 2. Deploy from GitHub

1. **Connect Repository**:
   - Click "Deploy from GitHub"
   - Select your repository
   - Choose main branch

2. **Configuration**:
   - Railway auto-detects `railway.json`
   - Dockerfile automatically selected

#### 3. Environment Variables

Set in Railway dashboard:

```bash
# Required
DISCORD_TOKEN=your_bot_token_here

# Railway-specific
RAILWAY_ENVIRONMENT=production
PORT=${{RAILWAY_PORT}}
```

#### 4. Railway Configuration

```json
{
  "build": {
    "builder": "dockerfile",
    "dockerfilePath": "Dockerfile.prod"
  },
  "deploy": {
    "healthcheckPath": "/ready",
    "healthcheckTimeout": 30,
    "restartPolicyType": "on_failure",
    "restartPolicyMaxRetries": 3
  }
}
```

#### 5. Volume Configuration

```bash
# Add persistent volume
railway add postgresql  # Optional: PostgreSQL addon
railway volume create bot-data /app/data
```

### Railway-Specific Features

#### Add-ons

```bash
# Add database
railway add postgresql
railway add redis

# Environment variables auto-configured
```

#### Custom Domains

```bash
# Custom domain setup
railway domain add bot.yourdomain.com
```

#### Monitoring

Railway provides built-in monitoring:
- CPU and memory usage
- Request logs
- Error tracking
- Deployment history

## Heroku Deployment

Heroku is a mature platform with extensive add-on ecosystem.

### Prerequisites

1. [Heroku account](https://heroku.com)
2. [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli)
3. Git repository

### Step-by-Step Deployment

#### 1. Create Heroku App

```bash
# Login and create app
heroku login
heroku create utils-bot-plus

# Set stack to container
heroku stack:set container -a utils-bot-plus
```

#### 2. Configure Environment

```bash
# Set environment variables
heroku config:set DISCORD_TOKEN=your_bot_token_here
heroku config:set SECRET_KEY=$(openssl rand -hex 16)
heroku config:set DATABASE_URL=sqlite:///data/bot.db

# Heroku-specific
heroku config:set DYNO=web.1
```

#### 3. Heroku Configuration Files

**Procfile**:
```
web: python main_hosted.py
```

**app.json**:
```json
{
  "name": "Utils Bot Plus",
  "description": "Advanced Discord utility bot",
  "repository": "https://github.com/yourusername/utils-bot-plus",
  "keywords": ["discord", "bot", "python"],
  "stack": "container",
  "env": {
    "DISCORD_TOKEN": {
      "description": "Discord bot token",
      "required": true
    },
    "SECRET_KEY": {
      "description": "Secret key for encryption",
      "generator": "secret"
    }
  },
  "addons": [
    {
      "plan": "heroku-postgresql:hobby-dev"
    }
  ],
  "buildpacks": [],
  "formation": {
    "web": {
      "quantity": 1,
      "size": "basic"
    }
  }
}
```

#### 4. Deploy

```bash
# Deploy via Git
git add .
git commit -m "Deploy to Heroku"
git push heroku main

# Or use container registry
heroku container:login
heroku container:push web
heroku container:release web
```

### Heroku-Specific Features

#### Add-ons

```bash
# Database
heroku addons:create heroku-postgresql:hobby-dev

# Redis
heroku addons:create heroku-redis:hobby-dev

# Logging
heroku addons:create papertrail:choklad

# Monitoring
heroku addons:create newrelic:wayne
```

#### Dyno Management

```bash
# Scale dynos
heroku ps:scale web=1

# View dyno status
heroku ps

# Restart application
heroku restart
```

## Platform Comparison

### Feature Matrix

| Feature | Render | Railway | Heroku |
|---------|--------|---------|--------|
| **Docker Support** | ✅ Native | ✅ Native | ✅ Container Stack |
| **Auto Deployment** | ✅ Git hooks | ✅ Git hooks | ✅ Git hooks |
| **Custom Domains** | ✅ Free SSL | ✅ Free SSL | ✅ Paid SSL |
| **Persistent Storage** | ✅ Disks | ✅ Volumes | ❌ Ephemeral |
| **Database Add-ons** | ✅ PostgreSQL | ✅ Multiple | ✅ Extensive |
| **Free Tier** | 750 hrs/month | $5 credit | Limited |
| **Health Checks** | ✅ Built-in | ✅ Built-in | ✅ Built-in |
| **Logs** | ✅ Real-time | ✅ Real-time | ✅ Real-time |
| **CLI Tools** | ✅ | ✅ Excellent | ✅ Mature |

### Performance Comparison

| Metric | Render | Railway | Heroku |
|--------|--------|---------|--------|
| **Cold Start** | ~5s | ~3s | ~10s |
| **Build Time** | 2-4 min | 1-3 min | 3-5 min |
| **Memory** | 512MB+ | 1GB+ | 512MB+ |
| **CPU** | Shared | Shared | Shared |
| **Network** | Global CDN | Global | Global |

### Cost Analysis

| Tier | Render | Railway | Heroku |
|------|--------|---------|--------|
| **Free** | 750 hrs | $5 credit | Limited hours |
| **Starter** | $7/month | $5/month | $25/month |
| **Production** | $25+/month | $20+/month | $25+/month |

## Environment Configuration

### Platform Detection

The bot automatically detects the hosting platform:

```python
def detect_hosting_service():
    """Detect the current hosting service."""
    if os.getenv('RENDER'):
        return 'render'
    elif os.getenv('RAILWAY_ENVIRONMENT'):
        return 'railway'
    elif os.getenv('DYNO'):
        return 'heroku'
    else:
        return 'docker'

def get_platform_config(service):
    """Get platform-specific configuration."""
    configs = {
        'render': {
            'port': int(os.getenv('PORT', 10000)),
            'health_path': '/health',
            'workers': 2
        },
        'railway': {
            'port': int(os.getenv('PORT', 8080)),
            'health_path': '/ready',
            'workers': 1
        },
        'heroku': {
            'port': int(os.getenv('PORT', 5000)),
            'health_path': '/',
            'workers': 1
        }
    }
    return configs.get(service, configs['render'])
```

### Universal Environment Variables

These work across all platforms:

```bash
# Core Configuration
DISCORD_TOKEN=your_bot_token
SECRET_KEY=auto_generated_key
DATABASE_URL=sqlite:///data/bot.db

# Feature Toggles
ENABLE_WEB_SERVER=true
ENABLE_HEALTH_CHECKS=true
LOG_LEVEL=INFO

# Performance Tuning
MAX_WORKERS=2
REQUEST_TIMEOUT=30
CONNECTION_POOL_SIZE=10
```

## Monitoring and Maintenance

### Health Check Endpoints

All platforms support these endpoints:

```python
# Health check routes
@app.route('/health')
async def health_check():
    return {
        "status": "healthy",
        "platform": detect_hosting_service(),
        "bot_status": "ready" if bot.is_ready() else "starting",
        "uptime": time.time() - start_time
    }

@app.route('/ready')
async def readiness_check():
    if bot.is_ready():
        return {"status": "ready"}
    return {"status": "not_ready"}, 503

@app.route('/')
async def status_page():
    return {
        "service": "Utils Bot Plus",
        "version": "1.0.0",
        "platform": detect_hosting_service(),
        "healthy": True
    }
```

### Logging Configuration

```python
import logging

def setup_logging(service):
    """Configure logging for hosting service."""
    level = os.getenv('LOG_LEVEL', 'INFO')
    
    if service == 'heroku':
        # Heroku prefers structured logging
        logging.basicConfig(
            format='%(asctime)s %(levelname)s %(message)s',
            level=getattr(logging, level)
        )
    else:
        # Render/Railway support JSON logging
        logging.basicConfig(
            format='{"time":"%(asctime)s","level":"%(levelname)s","message":"%(message)s"}',
            level=getattr(logging, level)
        )
```

### Metrics Collection

```python
import time
from collections import defaultdict

class MetricsCollector:
    def __init__(self):
        self.metrics = defaultdict(int)
        self.start_time = time.time()
    
    def record_command(self, command_name):
        self.metrics[f'command_{command_name}'] += 1
    
    def get_metrics(self):
        return {
            "uptime": time.time() - self.start_time,
            "commands_executed": dict(self.metrics),
            "memory_usage": self.get_memory_usage(),
            "platform": detect_hosting_service()
        }
```

## Cost Optimization

### Resource Management

```python
# Dynamic worker scaling
def get_optimal_workers():
    platform = detect_hosting_service()
    
    if platform == 'heroku':
        # Heroku dynos have limited memory
        return 1
    elif platform == 'railway':
        # Railway has generous memory limits
        return min(2, os.cpu_count())
    else:  # Render
        # Render scales well
        return min(4, os.cpu_count())
```

### Database Optimization

```python
# Connection pooling
import sqlite3
from threading import local

class DatabasePool:
    def __init__(self, max_connections=5):
        self.max_connections = max_connections
        self.local = local()
    
    def get_connection(self):
        if not hasattr(self.local, 'connection'):
            self.local.connection = sqlite3.connect(
                DATABASE_URL,
                check_same_thread=False,
                timeout=30
            )
        return self.local.connection
```

### Caching Strategy

```python
import functools
import time

def cache_with_ttl(ttl_seconds=300):
    def decorator(func):
        cache = {}
        
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            key = str(args) + str(kwargs)
            now = time.time()
            
            if key in cache:
                result, timestamp = cache[key]
                if now - timestamp < ttl_seconds:
                    return result
            
            result = func(*args, **kwargs)
            cache[key] = (result, now)
            return result
        
        return wrapper
    return decorator
```

## Migration Between Services

### Data Export

```python
async def export_bot_data():
    """Export bot data for migration."""
    data = {
        "guilds": await get_all_guild_configs(),
        "users": await get_all_user_data(),
        "logs": await get_recent_logs(),
        "timestamp": datetime.utcnow().isoformat()
    }
    
    with open('bot_data_export.json', 'w') as f:
        json.dump(data, f, indent=2)
    
    return "bot_data_export.json"
```

### Migration Checklist

- [ ] Export current database
- [ ] Note environment variables
- [ ] Save configuration files
- [ ] Test new deployment
- [ ] Update DNS (if using custom domain)
- [ ] Monitor for issues
- [ ] Clean up old deployment

## Troubleshooting by Platform

### Render Issues

#### Build Failures
```bash
# Check build logs
curl -H "Authorization: Bearer $RENDER_API_KEY" \
  https://api.render.com/v1/services/$SERVICE_ID/builds

# Common fixes
# 1. Increase build timeout
# 2. Check Dockerfile.prod syntax
# 3. Verify environment variables
```

#### Health Check Failures
```bash
# Test health endpoint locally
docker build -f Dockerfile.prod -t test-bot .
docker run -p 8080:8080 test-bot
curl http://localhost:8080/health
```

### Railway Issues

#### Deployment Fails
```bash
# Check Railway logs
railway logs

# Common fixes
# 1. Verify railway.json syntax
# 2. Check Docker build context
# 3. Increase deployment timeout
```

#### Memory Issues
```bash
# Monitor resource usage
railway metrics

# Optimize memory usage
export MAX_WORKERS=1
export ENABLE_CACHING=false
```

### Heroku Issues

#### Container Build Errors
```bash
# Check container logs
heroku logs --tail

# Debug container locally
heroku container:run web bash

# Common fixes
# 1. Verify Procfile syntax
# 2. Check port binding
# 3. Validate environment variables
```

#### Dyno Sleeping
```bash
# Keep dyno awake (hobby tier)
# Use external monitoring service
# Or upgrade to professional tier
heroku ps:scale web=1:professional-1x
```

## Best Practices

### Security

1. **Environment Variables**: Never commit secrets
2. **HTTPS Only**: Use SSL/TLS for all connections
3. **Access Control**: Limit admin permissions
4. **Regular Updates**: Keep dependencies current

### Performance

1. **Resource Monitoring**: Track CPU and memory usage
2. **Connection Pooling**: Optimize database connections
3. **Caching**: Implement appropriate caching strategies
4. **Graceful Scaling**: Handle load increases smoothly

### Reliability

1. **Health Checks**: Implement comprehensive monitoring
2. **Graceful Shutdown**: Handle termination signals properly
3. **Error Handling**: Comprehensive error management
4. **Backup Strategy**: Regular data backups

## Next Steps

After successful deployment:

1. **Monitor Performance**: Set up monitoring and alerts
2. **Configure Backups**: Implement data backup strategy
3. **Set Up CI/CD**: Automate testing and deployment
4. **Scale Resources**: Adjust based on usage patterns
5. **Security Audit**: Regular security reviews

## Related Documentation

- [Docker Automated Setup Guide](16.%20Docker-Automated-Setup-Guide.md)
- [Configuration Guide](05.%20Configuration-Guide.md)
- [Security Guide](11.%20Security-Guide.md)
- [Troubleshooting](12.%20Troubleshooting.md)
- [Architecture Overview](08.%20Architecture-Overview.md)