feat: Add complete production deployment infrastructure
- Docker configuration: - Multi-stage Dockerfiles for backend (Python 3.11) and frontend (Node 20) - Production docker-compose.yml with all services - Development docker-compose.dev.yml with hot-reload - Nginx reverse proxy: - SSL/TLS termination with modern cipher suites - Rate limiting and security headers - Caching and compression - Load balancing ready - Kubernetes manifests: - Deployment, Service, Ingress configurations - ConfigMap and Secrets - HPA for auto-scaling - PersistentVolumeClaims - Deployment scripts: - deploy.sh: Automated deployment with health checks - backup.sh: Automated backup with retention - health-check.sh: Service health monitoring - setup-ssl.sh: Let's Encrypt SSL automation - Monitoring: - Prometheus configuration - Grafana dashboards (optional) - Structured logging - Documentation: - DEPLOYMENT_GUIDE.md: Complete deployment instructions - Environment templates (.env.production) Ready for commercial deployment!
This commit is contained in:
455
DEPLOYMENT_GUIDE.md
Normal file
455
DEPLOYMENT_GUIDE.md
Normal file
@@ -0,0 +1,455 @@
|
||||
# 🚀 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
|
||||
|
||||
### 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
|
||||
|
||||
### 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
|
||||
|
||||
```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
|
||||
Reference in New Issue
Block a user