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
2. Architecture Overview
3. Docker Deployment
4. Kubernetes Deployment
5. SSL/TLS Configuration
6. Environment Configuration
7. Monitoring & Logging
8. Scaling & Performance
9. Backup & Recovery
10. Troubleshooting

---

🚀 Quick Start

Prerequisites

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

One-Command Deployment

# 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

# 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

# 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

# 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

# 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

Option 1: Let's Encrypt (Recommended)

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

Option 2: Custom Certificate

# 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)

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

Required Variables

Variable	Description	Default
DOMAIN	Your domain name	-
ADMIN_USERNAME	Admin login	admin
ADMIN_PASSWORD	Admin password	changeme123
TRANSLATION_SERVICE	Default provider	ollama

Translation Providers

# 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

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

docker compose --profile with-monitoring up -d

Access Dashboards

• Prometheus: http://localhost:9090
• Grafana: http://localhost:3001 (admin/admin)

Log Locations

# 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

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

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

---

📈 Scaling & Performance

Horizontal Scaling

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

Performance Tuning

# 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

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

---

💾 Backup & Recovery

Automated Backup

# 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

# 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

# Find process
netstat -tulpn | grep :8000
# Kill process
kill -9 <PID>

Container Won't Start

# Check logs
docker compose logs backend --tail 100

# Check resources
docker stats

SSL Certificate Issues

# Test certificate
openssl s_client -connect your-domain.com:443

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

Memory Issues

# 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

# 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