torrent-gateway/docs/deployment.md

Deployment Guide

Overview

This guide covers deploying the Torrent Gateway in production using Docker Compose with comprehensive monitoring.

Prerequisites

• Docker and Docker Compose installed
• SQLite3 for database operations
• FFmpeg for video transcoding (optional but recommended)
• 4GB+ RAM recommended (8GB+ for transcoding)
• 50GB+ disk space for storage

Quick Deployment

1. Build and start services:

   ./scripts/deploy.sh production v1.0.0
   

2. Verify deployment:

   ./scripts/health_check.sh
   

Manual Deployment Steps

1. Environment Setup

# Set environment variables
export DEPLOY_ENV=production
export VERSION=v1.0.0

# Create required directories
mkdir -p data/{blobs,chunks} logs backups

2. Database Initialization

# Start services to initialize database
docker-compose -f docker-compose.prod.yml up -d gateway redis

# Wait for gateway to initialize database
./scripts/health_check.sh

3. Configuration Review

Review and update configurations:

• configs/prometheus.yml - Metrics collection
• configs/grafana/ - Dashboard settings
• configs/loki.yml - Log aggregation
• docker-compose.prod.yml - Service configuration

4. Start Full Stack

# Start all services including monitoring
docker-compose -f docker-compose.prod.yml up -d

# Wait for all services to be healthy
timeout 120 bash -c 'until curl -sf http://localhost:9876/api/health; do sleep 5; done'

5. Verify Deployment

# Run comprehensive health checks
./scripts/health_check.sh

# Check service logs
docker-compose -f docker-compose.prod.yml logs

Service URLs

• Gateway API: http://localhost:9876
• Admin Panel: http://localhost:9876/admin
• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000 (admin/admin)
• AlertManager: http://localhost:9093

Production Checklist

• SSL/TLS certificates configured
• Firewall rules configured
• Backup strategy tested
• Monitoring alerts configured
• Log rotation configured
• Storage limits set
• Resource limits configured
• Security headers enabled

Scaling

Horizontal Scaling

# Scale gateway instances
docker-compose -f docker-compose.prod.yml up -d --scale gateway=3

Resource Limits

Update docker-compose.prod.yml:

services:
  gateway:
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '1.0'

SSL/TLS Setup

1. Obtain certificates:

   # Using Let's Encrypt
   certbot certonly --standalone -d yourdomain.com
   

2. Update compose file:

   gateway:
     volumes:
       - /etc/letsencrypt/live/yourdomain.com:/certs:ro
   

3. Configure reverse proxy: Add nginx or traefik for SSL termination.

Backup Strategy

• Automated backups: Cron job runs ./scripts/backup.sh daily
• Manual backup: ./scripts/backup.sh
• Retention: Keep 30 daily, 12 monthly backups
• Storage: Offsite backup recommended

Monitoring Setup

Grafana Dashboards

1. Login to Grafana (admin/admin)
2. Change default password
3. Import provided dashboards from configs/grafana/dashboards/

Alert Configuration

1. Review configs/alertmanager.yml
2. Configure notification channels (Slack, email, etc.)
3. Test alert routing

Security Hardening

1. Change default passwords
2. Enable firewall:

   ufw allow 9876/tcp  # Gateway API
   ufw allow 22/tcp    # SSH
   ufw enable
   

3. Regular updates:

   # Update system packages
   apt update && apt upgrade -y
   
   # Update Docker images
   docker-compose -f docker-compose.prod.yml pull
   

Common Issues

Gateway Won't Start

• Check disk space: df -h
• Check database permissions: ls -la data/
• Review logs: docker-compose logs gateway

Database Corruption

• Run integrity check: sqlite3 data/metadata.db "PRAGMA integrity_check;"
• Restore from backup: ./scripts/restore.sh <timestamp>

High Memory Usage

• Check for memory leaks in logs
• Restart services: docker-compose restart
• Scale down if necessary