office_translator/DEPLOYMENT_GUIDE.md

# 🚀 Document Translation API - Production Deployment Guide

Complete guide for deploying the Document Translation API in production environments.

## 📋 Table of Contents

1. [Quick Start](#quick-start)
2. [Architecture Overview](#architecture-overview)
3. [Docker Deployment](#docker-deployment)
4. [Kubernetes Deployment](#kubernetes-deployment)
5. [SSL/TLS Configuration](#ssltls-configuration)
6. [Environment Configuration](#environment-configuration)
7. [Monitoring & Logging](#monitoring--logging)
8. [Scaling & Performance](#scaling--performance)
9. [Backup & Recovery](#backup--recovery)
10. [Troubleshooting](#troubleshooting)

---

## 🚀 Quick Start

### Prerequisites

- Docker & Docker Compose v2.0+
- Domain name (for production)
- SSL certificate (or use Let's Encrypt)

### One-Command Deployment

```bash
# Clone and deploy
git clone https://github.com/your-repo/translate-api.git
cd translate-api
git checkout production-deployment

# Configure environment
cp .env.example .env.production
# Edit .env.production with your settings

# Deploy!
./scripts/deploy.sh production
```

Your application will be available at `https://your-domain.com`

---

## 🏗️ Architecture Overview

```
                                    ┌─────────────────┐
                                    │   Internet      │
                                    └────────┬────────┘
                                             │
                                    ┌────────▼────────┐
                                    │     Nginx       │
                                    │  (Reverse Proxy)│
                                    │  - SSL/TLS      │
                                    │  - Rate Limit   │
                                    │  - Caching      │
                                    └────────┬────────┘
                              ┌──────────────┼──────────────┐
                              │              │              │
                     ┌────────▼────┐  ┌──────▼─────┐  ┌─────▼─────┐
                     │  Frontend   │  │  Backend   │  │   Admin   │
                     │  (Next.js)  │  │  (FastAPI) │  │  Dashboard│
                     │  Port 3000  │  │  Port 8000 │  │           │
                     └─────────────┘  └──────┬─────┘  └───────────┘
                                             │
                    ┌────────────────────────┼────────────────────────┐
                    │                        │                        │
           ┌────────▼────────┐    ┌──────────▼──────────┐    ┌───────▼───────┐
           │     Ollama      │    │   Google/DeepL/     │    │    Redis      │
           │  (Local LLM)    │    │   OpenAI APIs       │    │   (Cache)     │
           └─────────────────┘    └─────────────────────┘    └───────────────┘
```

---

## 🐳 Docker Deployment

### Directory Structure

```
translate-api/
├── docker/
│   ├── backend/
│   │   └── Dockerfile
│   ├── frontend/
│   │   └── Dockerfile
│   ├── nginx/
│   │   ├── nginx.conf
│   │   ├── conf.d/
│   │   │   └── default.conf
│   │   └── ssl/
│   │       ├── fullchain.pem
│   │       └── privkey.pem
│   └── prometheus/
│       └── prometheus.yml
├── scripts/
│   ├── deploy.sh
│   ├── backup.sh
│   ├── health-check.sh
│   └── setup-ssl.sh
├── docker-compose.yml
├── docker-compose.dev.yml
├── .env.production
└── .env.example
```

### Basic Deployment

```bash
# Production (with nginx, SSL)
docker compose --env-file .env.production up -d

# View logs
docker compose logs -f

# Check status
docker compose ps
```

### With Optional Services

```bash
# With local Ollama LLM
docker compose --profile with-ollama up -d

# With Redis caching
docker compose --profile with-cache up -d

# With monitoring (Prometheus + Grafana)
docker compose --profile with-monitoring up -d

# All services
docker compose --profile with-ollama --profile with-cache --profile with-monitoring up -d
```

### Service Endpoints

| Service | Internal Port | External Access |
|---------|--------------|-----------------|
| Frontend | 3000 | https://domain.com/ |
| Backend API | 8000 | https://domain.com/api/ |
| Admin Dashboard | 8000 | https://domain.com/admin |
| Health Check | 8000 | https://domain.com/health |
| Prometheus | 9090 | Internal only |
| Grafana | 3001 | https://domain.com:3001 |

---

## ☸️ Kubernetes Deployment

### Prerequisites

- Kubernetes cluster (1.25+)
- kubectl configured
- Ingress controller (nginx-ingress)
- cert-manager (for SSL)

### Deploy to Kubernetes

```bash
# Create namespace and deploy
kubectl apply -f k8s/deployment.yaml

# Check status
kubectl get pods -n translate-api
kubectl get services -n translate-api
kubectl get ingress -n translate-api

# View logs
kubectl logs -f deployment/backend -n translate-api
```

### Scaling

```bash
# Manual scaling
kubectl scale deployment/backend --replicas=5 -n translate-api

# Auto-scaling is configured via HPA
kubectl get hpa -n translate-api
```

---

## 🔒 SSL/TLS Configuration

### Reverse proxy (Nginx – Story 6.5)

En production, le reverse proxy Nginx fournit :

- **HTTP → HTTPS** : redirection 301 (sauf `/health` et `/.well-known/acme-challenge/` pour Let's Encrypt).
- **TLS 1.2+** : `ssl_protocols TLSv1.2 TLSv1.3` (SSLv3 et TLS 1.0/1.1 désactivés).
- **HSTS** : en-tête `Strict-Transport-Security` avec `max-age=31536000; includeSubDomains`.
- **Routage** : `/api/` et `/api/*` → backend (FastAPI, port 8000) ; `/*` → frontend (Next.js, port 3000). Les en-têtes `X-Forwarded-For` et `X-Forwarded-Proto` sont transmis. Une route alternative `location /translate` est configurée pour compatibilité (proxy vers `backend/translate`) ; l’API versionnée reste `POST /api/v1/translate`.
- **Health check** : `GET https://domain/health` est proxyfié vers le backend (pour orchestrateurs et monitoring). Le healthcheck Docker du conteneur nginx ne fait que `nginx -t` (syntaxe) ; pour vérifier la disponibilité via le proxy, exécuter depuis l’hôte : `curl -f https://your-domain/health`.

Configuration : `docker/nginx/nginx.conf` et `docker/nginx/conf.d/default.conf`. Certificats dans `docker/nginx/ssl/` (voir options ci-dessous).

### Option 1: Let's Encrypt (Recommended)

```bash
# Automated setup
./scripts/setup-ssl.sh translate.yourdomain.com admin@yourdomain.com
```

### Option 2: Custom Certificate

```bash
# Place your certificates in:
docker/nginx/ssl/fullchain.pem    # Full certificate chain
docker/nginx/ssl/privkey.pem      # Private key
docker/nginx/ssl/chain.pem        # CA chain (optional)
```

### Option 3: Self-Signed (Development Only)

```bash
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout docker/nginx/ssl/privkey.pem \
    -out docker/nginx/ssl/fullchain.pem \
    -subj "/CN=localhost"
```

---

## ⚙️ Environment Configuration

### Configuration procedure (Story 6.6 – NFR10)

1. Copy the example file: `cp .env.example .env` (or `.env.production` for production).
2. Fill all **required** variables (see `.env.example` comments: "Required" vs "Optional").
3. In production, the app **fails at startup** with a clear message if any required variable is missing (e.g. `JWT_SECRET_KEY`, `ADMIN_USERNAME`, `ADMIN_PASSWORD` or `ADMIN_PASSWORD_HASH`, `ADMIN_TOKEN_SECRET`, `DATABASE_URL`, `REDIS_URL` when rate limiting is enabled). No secrets in code; see `.env.example` for the full list.

### Required Variables (production)

When `ENV=production`, the app fails at startup if any of these are missing. See `.env.example` for the full list and Optional vs Required.

| Variable | Description | Default |
|----------|-------------|---------|
| `JWT_SECRET_KEY` | JWT signing key | - |
| `ADMIN_USERNAME` | Admin login | admin |
| `ADMIN_PASSWORD` or `ADMIN_PASSWORD_HASH` | Admin auth | - |
| `ADMIN_TOKEN_SECRET` | Admin session tokens | - |
| `DATABASE_URL` | PostgreSQL connection string (or use `POSTGRES_*`) | - |
| `REDIS_URL` | Redis URL (when `RATE_LIMIT_ENABLED=true`) | - |
| `DOMAIN` | Your domain (for proxy/SSL) | - |
| `TRANSLATION_SERVICE` | Default provider | ollama |

### Translation Providers

```bash
# Ollama (Local LLM)
TRANSLATION_SERVICE=ollama
OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_MODEL=llama3

# Google Translate (Free)
TRANSLATION_SERVICE=google

# DeepL (Requires API key)
TRANSLATION_SERVICE=deepl
DEEPL_API_KEY=your-api-key

# OpenAI (Requires API key)
TRANSLATION_SERVICE=openai
OPENAI_API_KEY=your-api-key
OPENAI_MODEL=gpt-4o-mini
```

### Rate Limiting

```bash
RATE_LIMIT_REQUESTS_PER_MINUTE=60
RATE_LIMIT_TRANSLATIONS_PER_MINUTE=10
RATE_LIMIT_TRANSLATIONS_PER_HOUR=100
RATE_LIMIT_TRANSLATIONS_PER_DAY=500
```

---

## 📊 Monitoring & Logging

### Enable Monitoring

```bash
docker compose --profile with-monitoring up -d
```

### Access Dashboards

- **Prometheus**: http://localhost:9090
- **Grafana**: http://localhost:3001 (admin/admin)

### Log Locations

```bash
# Docker logs
docker compose logs backend
docker compose logs frontend
docker compose logs nginx

# Application logs (inside container)
docker exec translate-backend cat /app/logs/app.log
```

### Health Checks

```bash
# Manual check
./scripts/health-check.sh --verbose

# API health endpoint
curl https://your-domain.com/health
```

---

## 📈 Scaling & Performance

### Horizontal Scaling

```yaml
# docker-compose.yml
services:
  backend:
    deploy:
      replicas: 4
```

### Performance Tuning

```bash
# Backend workers (in Dockerfile CMD)
CMD ["uvicorn", "main:app", "--workers", "4"]

# Nginx connections
worker_connections 2048;

# File upload limits
client_max_body_size 100M;
```

### Resource Limits

```yaml
# docker-compose.yml
deploy:
  resources:
    limits:
      memory: 2G
      cpus: '1'
    reservations:
      memory: 512M
```

---

## 💾 Backup & Recovery

### Automated Backup

```bash
# Run backup
./scripts/backup.sh /path/to/backups

# Add to crontab (daily at 2 AM)
0 2 * * * /path/to/scripts/backup.sh /backups
```

### Restore from Backup

```bash
# Extract backup
tar xzf translate_backup_20241130.tar.gz

# Restore files
docker cp translate_backup/uploads translate-backend:/app/
docker cp translate_backup/outputs translate-backend:/app/

# Restart services
docker compose restart
```

---

## 🔧 Troubleshooting

### Common Issues

#### Port Already in Use
```bash
# Find process
netstat -tulpn | grep :8000
# Kill process
kill -9 <PID>
```

#### Container Won't Start
```bash
# Check logs
docker compose logs backend --tail 100

# Check resources
docker stats
```

#### SSL Certificate Issues
```bash
# Test certificate
openssl s_client -connect your-domain.com:443

# Renew Let's Encrypt
./scripts/renew-ssl.sh
```

#### Memory Issues
```bash
# Increase limits in docker-compose.yml
deploy:
  resources:
    limits:
      memory: 4G
```

### Getting Help

1. Check logs: `docker compose logs -f`
2. Run health check: `./scripts/health-check.sh`
3. Review configuration: `.env.production`
4. Check container status: `docker compose ps`

---

## 📝 Maintenance Commands

```bash
# Update application
git pull origin production-deployment
docker compose build
docker compose up -d

# Prune unused resources
docker system prune -a

# View resource usage
docker stats

# Enter container shell
docker exec -it translate-backend /bin/bash

# Database backup (if using)
docker exec translate-db pg_dump -U user database > backup.sql
```

---

## 🔐 Security Checklist

- [ ] Change default admin password
- [ ] Configure SSL/TLS
- [ ] Set up firewall rules
- [ ] Enable rate limiting
- [ ] Configure CORS properly
- [ ] Regular security updates
- [ ] Backup encryption
- [ ] Monitor access logs

---

## 📞 Support

For issues and feature requests, please open a GitHub issue or contact support.

**Version**: 2.0.0  
**Last Updated**: November 2025