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
- 4GB+ RAM recommended
- 50GB+ disk space for storage

## Quick Deployment

1. **Build and start services:**
   ```bash
   ./scripts/deploy.sh production v1.0.0
   ```

2. **Verify deployment:**
   ```bash
   ./scripts/health_check.sh
   ```

## Manual Deployment Steps

### 1. Environment Setup

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

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

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

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

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

### Resource Limits

Update `docker-compose.prod.yml`:
```yaml
services:
  gateway:
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '1.0'
```

## SSL/TLS Setup

1. **Obtain certificates:**
   ```bash
   # Using Let's Encrypt
   certbot certonly --standalone -d yourdomain.com
   ```

2. **Update compose file:**
   ```yaml
   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:**
   ```bash
   ufw allow 9876/tcp  # Gateway API
   ufw allow 22/tcp    # SSH
   ufw enable
   ```
3. **Regular updates:**
   ```bash
   # 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