Initial commit: Ebook Translation System with Docker setup
This commit is contained in:
richardtekula
647
COOLIFY_DEPLOYMENT.md
Normal file
647
COOLIFY_DEPLOYMENT.md
Normal file
@@ -0,0 +1,647 @@
|
||||
# 🚀 Coolify Deployment Guide - Ebook Translation System
|
||||
|
||||
Kompletný návod na nasadenie Ebook Translation System do Coolify.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Predpoklady
|
||||
|
||||
### Čo potrebujete:
|
||||
|
||||
- ✅ **Coolify inštalovaný** na vašom serveri
|
||||
- ✅ **Git repozitár** (GitHub, GitLab, Gitea, atď.)
|
||||
- ✅ **Doména alebo subdoména** (odporúčané)
|
||||
- ✅ **SSH prístup** k serveru (voliteľné, ale užitočné)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Architektúra Deploymentu
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ Coolify Server │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────┐ │
|
||||
│ │ Traefik Reverse Proxy │ │
|
||||
│ │ (automaticky od Coolify) │ │
|
||||
│ │ - SSL/TLS (Let's Encrypt) │ │
|
||||
│ │ - Domain routing │ │
|
||||
│ └──────────────────┬─────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────────────▼─────────────────────────┐ │
|
||||
│ │ Backend Container (FastAPI) │ │
|
||||
│ │ - Port: 8000 │ │
|
||||
│ │ - Volumes: logs, translations │ │
|
||||
│ └──────────────────┬─────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────────────▼─────────────────────────┐ │
|
||||
│ │ PostgreSQL Container │ │
|
||||
│ │ - Port: 5432 (internal) │ │
|
||||
│ │ - Volume: postgres_data │ │
|
||||
│ └────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Príprava projektu
|
||||
|
||||
### **KROK 1: Nahrajte projekt do Git repozitára**
|
||||
|
||||
```bash
|
||||
# Ak ešte nemáte Git repozitár
|
||||
|
||||
# 1. Inicializujte Git v projekte
|
||||
cd /home/richardtekula/Documents/WORK/extension/Ebook_System
|
||||
git init
|
||||
|
||||
# 2. Pridajte .gitignore
|
||||
cat > .gitignore << 'EOF'
|
||||
# Environment variables
|
||||
.env
|
||||
.env.local
|
||||
.env.production
|
||||
*.env
|
||||
|
||||
# Python
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
.venv/
|
||||
venv/
|
||||
*.so
|
||||
|
||||
# Logs
|
||||
*.log
|
||||
logs/
|
||||
|
||||
# Database
|
||||
*.db
|
||||
*.sqlite
|
||||
|
||||
# IDE
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Temporary
|
||||
*.tmp
|
||||
*.bak
|
||||
EOF
|
||||
|
||||
# 3. Commitnite súbory
|
||||
git add .
|
||||
git commit -m "Initial commit: Ebook Translation System"
|
||||
|
||||
# 4. Pridajte remote repozitár (GitHub/GitLab/atď.)
|
||||
git remote add origin https://github.com/vase-meno/ebook-system.git
|
||||
git branch -M main
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Nasadenie v Coolify
|
||||
|
||||
### **KROK 1: Vytvorenie nového projektu v Coolify**
|
||||
|
||||
1. **Prihláste sa do Coolify** webového rozhrania
|
||||
2. Kliknite na **"+ New"** alebo **"New Resource"**
|
||||
3. Vyberte **"Docker Compose"**
|
||||
|
||||
### **KROK 2: Konfigurácia Git repozitára**
|
||||
|
||||
1. **Source:** Vyberte váš Git provider (GitHub, GitLab, atď.)
|
||||
2. **Repository:** Zadajte URL vašeho repozitára
|
||||
```
|
||||
https://github.com/vase-meno/ebook-system.git
|
||||
```
|
||||
3. **Branch:** `main` (alebo master, podľa vášho nastavenia)
|
||||
4. **Auto Deploy:** Zapnite (automatický deployment pri každom push)
|
||||
|
||||
### **KROK 3: Nastavenie Build Configuration**
|
||||
|
||||
1. **Build Pack:** `Docker Compose`
|
||||
2. **Docker Compose Location:** `docker-compose.yml` (v root adresári)
|
||||
3. **Base Directory:** `/` (root projektu)
|
||||
|
||||
### **KROK 4: Environment Variables**
|
||||
|
||||
V Coolify prejdite na **"Environment"** sekciu a pridajte tieto premenné:
|
||||
|
||||
```bash
|
||||
# ==========================================
|
||||
# DATABASE
|
||||
# ==========================================
|
||||
POSTGRES_DB=ebook_prod
|
||||
POSTGRES_USER=ebook_user
|
||||
POSTGRES_PASSWORD=VaseSilneHeslo123!@#
|
||||
|
||||
DATABASE_URL=postgresql://ebook_user:VaseSilneHeslo123!@#@postgres:5432/ebook_prod
|
||||
|
||||
# ==========================================
|
||||
# SECURITY
|
||||
# ==========================================
|
||||
# Vygenerujte: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
|
||||
SECRET_KEY=vygenerovany-32-znakovy-tajny-kluc-pouzite-prikaz-vyssie
|
||||
|
||||
DEBUG=false
|
||||
ENVIRONMENT=production
|
||||
|
||||
# ==========================================
|
||||
# ADMIN
|
||||
# ==========================================
|
||||
ADMIN_USERNAME=admin
|
||||
ADMIN_PASSWORD=VaseAdminHeslo123!@#
|
||||
|
||||
# ==========================================
|
||||
# CORS & DOMAINS
|
||||
# ==========================================
|
||||
# Nastavte na vašu skutočnú doménu!
|
||||
CORS_ORIGINS=https://ebook.vasa-domena.sk,https://www.ebook.vasa-domena.sk
|
||||
TRUSTED_HOSTS=ebook.vasa-domena.sk,www.ebook.vasa-domena.sk
|
||||
|
||||
# ==========================================
|
||||
# APPLICATION
|
||||
# ==========================================
|
||||
APP_NAME=Ebook Translation System
|
||||
APP_VERSION=1.0.0
|
||||
LOG_LEVEL=WARNING
|
||||
|
||||
HOST=0.0.0.0
|
||||
PORT=8000
|
||||
WORKERS=4
|
||||
|
||||
# ==========================================
|
||||
# TIMEZONE
|
||||
# ==========================================
|
||||
TZ=Europe/Bratislava
|
||||
```
|
||||
|
||||
**DÔLEŽITÉ:**
|
||||
- Kliknite na **"🔒"** ikonu pri citlivých premenných (heslá, SECRET_KEY) aby boli skryté
|
||||
- Použite **silné heslá** - min. 16 znakov
|
||||
- Vygenerujte **nový SECRET_KEY** - nikdy nepoužívajte default hodnoty
|
||||
|
||||
### **KROK 5: Domain Configuration**
|
||||
|
||||
1. Prejdite na **"Domains"** sekciu
|
||||
2. Kliknite **"Add Domain"**
|
||||
3. Zadajte vašu doménu:
|
||||
```
|
||||
ebook.vasa-domena.sk
|
||||
```
|
||||
4. Zapnite **"Enable SSL/TLS"** (Let's Encrypt)
|
||||
5. Uložte
|
||||
|
||||
**DNS Konfigurácia:**
|
||||
V DNS nastaveniach vašej domény vytvorte A record:
|
||||
```
|
||||
Type: A
|
||||
Name: ebook (alebo @ pre root doménu)
|
||||
Value: IP_ADRESA_VASHO_SERVERA
|
||||
TTL: 3600
|
||||
```
|
||||
|
||||
### **KROK 6: Storage/Volumes Configuration**
|
||||
|
||||
Coolify automaticky vytvorí volumes definované v `docker-compose.yml`:
|
||||
- `ebook_postgres_data` - PostgreSQL databáza
|
||||
- `ebook_backend_logs` - Aplikačné logy
|
||||
- `ebook_translation_files` - Nahrané prekladové súbory
|
||||
|
||||
**Overenie volumes:**
|
||||
```bash
|
||||
# SSH do servera
|
||||
ssh user@vas-server.sk
|
||||
|
||||
# Zoznam volumes
|
||||
docker volume ls | grep ebook
|
||||
```
|
||||
|
||||
### **KROK 7: Deploy!**
|
||||
|
||||
1. Skontrolujte všetky nastavenia
|
||||
2. Kliknite **"Deploy"** alebo **"Start"**
|
||||
3. Sledujte deployment logy v reálnom čase
|
||||
|
||||
**Coolify vykoná:**
|
||||
1. Clone Git repozitára
|
||||
2. Build Docker images (podľa Dockerfile)
|
||||
3. Vytvorenie volumes
|
||||
4. Spustenie PostgreSQL kontajnera
|
||||
5. Spustenie Backend kontajnera
|
||||
6. Nastavenie Traefik reverse proxy
|
||||
7. Vygenerovanie SSL certifikátu (Let's Encrypt)
|
||||
|
||||
---
|
||||
|
||||
## ✅ Overenie Deploymentu
|
||||
|
||||
### **1. Skontrolujte Health Endpoint**
|
||||
|
||||
```bash
|
||||
curl https://ebook.vasa-domena.sk/health
|
||||
```
|
||||
|
||||
**Očakávaný výstup:**
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"timestamp": 1736612345.67,
|
||||
"version": "1.0.0",
|
||||
"environment": "production",
|
||||
"database_status": "connected"
|
||||
}
|
||||
```
|
||||
|
||||
### **2. Otvorte Admin Panel**
|
||||
|
||||
Otvorte prehliadač a choďte na:
|
||||
```
|
||||
https://ebook.vasa-domena.sk/login
|
||||
```
|
||||
|
||||
Prihláste sa s credentials z environment variables:
|
||||
- **Username:** `admin`
|
||||
- **Password:** Vaše `ADMIN_PASSWORD`
|
||||
|
||||
### **3. Skontrolujte Logy v Coolify**
|
||||
|
||||
V Coolify prejdite na:
|
||||
- **"Logs"** → Sledujte deployment a runtime logy
|
||||
- Hľadajte chyby alebo varovania
|
||||
|
||||
### **4. Testujte funkčnosť**
|
||||
|
||||
1. **Vygenerujte kupón:**
|
||||
- V admin paneli prejdite na "Generate"
|
||||
- Vygenerujte testovací kupón
|
||||
- Skontrolujte či sa uložil do databázy
|
||||
|
||||
2. **Nahrajte translation file:**
|
||||
- Prejdite na "Translation Upload"
|
||||
- Nahrajte testovací Excel súbor
|
||||
- Overte či sa nahralo úspešne
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Monitoring a Debugging
|
||||
|
||||
### **Sledovanie Logov v Coolify**
|
||||
|
||||
1. V Coolify dashboarde kliknite na váš projekt
|
||||
2. Prejdite na **"Logs"**
|
||||
3. Vyberte kontajner:
|
||||
- `backend` - Aplikačné logy
|
||||
- `postgres` - Databázové logy
|
||||
|
||||
**Real-time logs:**
|
||||
```bash
|
||||
# SSH do servera
|
||||
ssh user@vas-server.sk
|
||||
|
||||
# Nájdite názov vášho projektu v Coolify
|
||||
docker ps | grep ebook
|
||||
|
||||
# Sledujte logy
|
||||
docker logs -f <container-name>
|
||||
|
||||
# Alebo použite docker-compose (ak máte prístup k docker-compose.yml)
|
||||
docker-compose logs -f backend
|
||||
```
|
||||
|
||||
### **Databázové operácie**
|
||||
|
||||
```bash
|
||||
# SSH do servera
|
||||
ssh user@vas-server.sk
|
||||
|
||||
# Pripojte sa do PostgreSQL kontajnera
|
||||
docker exec -it <postgres-container-name> psql -U ebook_user -d ebook_prod
|
||||
|
||||
# SQL príkazy:
|
||||
# Zobraziť všetky kupóny
|
||||
SELECT * FROM coupon_codes LIMIT 10;
|
||||
|
||||
# Počet kupónov
|
||||
SELECT COUNT(*) FROM coupon_codes;
|
||||
|
||||
# Použité kupóny
|
||||
SELECT code, used_at FROM coupon_codes WHERE usage_count > 0;
|
||||
|
||||
# Ukončite psql
|
||||
\q
|
||||
```
|
||||
|
||||
### **Backup Databázy**
|
||||
|
||||
```bash
|
||||
# SSH do servera
|
||||
ssh user@vas-server.sk
|
||||
|
||||
# Vytvorte backup
|
||||
docker exec <postgres-container-name> pg_dump -U ebook_user ebook_prod > backup_$(date +%Y%m%d_%H%M%S).sql
|
||||
|
||||
# Alebo pomocou docker-compose
|
||||
docker-compose exec postgres pg_dump -U ebook_user ebook_prod > backup.sql
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Update a Redeploy
|
||||
|
||||
### **Automatický Update (Git Push)**
|
||||
|
||||
Ak máte zapnuté **Auto Deploy** v Coolify:
|
||||
|
||||
```bash
|
||||
# Lokálne na vašom počítači
|
||||
cd /home/richardtekula/Documents/WORK/extension/Ebook_System
|
||||
|
||||
# Urobte zmeny v kóde
|
||||
# ...
|
||||
|
||||
# Commitnite zmeny
|
||||
git add .
|
||||
git commit -m "Update: pridaná nová funkcia"
|
||||
git push origin main
|
||||
|
||||
# Coolify automaticky detekuje push a spustí redeploy
|
||||
```
|
||||
|
||||
### **Manuálny Redeploy**
|
||||
|
||||
V Coolify:
|
||||
1. Prejdite na váš projekt
|
||||
2. Kliknite **"Redeploy"** alebo **"Restart"**
|
||||
3. Sledujte logy
|
||||
|
||||
### **Rebuild from Scratch**
|
||||
|
||||
Ak potrebujete celkom nový build (napr. po zmene Dockerfile):
|
||||
|
||||
V Coolify:
|
||||
1. Zastavte aplikáciu: **"Stop"**
|
||||
2. Vymažte staré images (voliteľné)
|
||||
3. Kliknite **"Deploy"** znovu
|
||||
|
||||
SSH metóda:
|
||||
```bash
|
||||
# Zastavte všetko
|
||||
docker-compose down
|
||||
|
||||
# Vymažte volumes (POZOR: stratíte dáta!)
|
||||
docker-compose down -v
|
||||
|
||||
# Rebuild a spustite
|
||||
docker-compose up -d --build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Riešenie Problémov
|
||||
|
||||
### **Problem: Backend sa nespustí**
|
||||
|
||||
**Symptómy:**
|
||||
- Container sa crashuje
|
||||
- Health check failuje
|
||||
- 502 Bad Gateway error
|
||||
|
||||
**Riešenie:**
|
||||
|
||||
1. **Skontrolujte logy:**
|
||||
```bash
|
||||
docker logs <backend-container-name>
|
||||
```
|
||||
|
||||
2. **Skontrolujte environment variables:**
|
||||
```bash
|
||||
docker exec <backend-container-name> env | grep DATABASE_URL
|
||||
```
|
||||
|
||||
3. **Overte databázové pripojenie:**
|
||||
```bash
|
||||
docker exec <backend-container-name> python -c "
|
||||
from sqlalchemy import create_engine
|
||||
import os
|
||||
engine = create_engine(os.getenv('DATABASE_URL'))
|
||||
conn = engine.connect()
|
||||
print('Database connection OK!')
|
||||
"
|
||||
```
|
||||
|
||||
### **Problem: Databáza nie je dostupná**
|
||||
|
||||
**Symptómy:**
|
||||
- `could not connect to server: Connection refused`
|
||||
- `database "ebook_prod" does not exist`
|
||||
|
||||
**Riešenie:**
|
||||
|
||||
1. **Skontrolujte či PostgreSQL beží:**
|
||||
```bash
|
||||
docker ps | grep postgres
|
||||
```
|
||||
|
||||
2. **Skontrolujte logy:**
|
||||
```bash
|
||||
docker logs <postgres-container-name>
|
||||
```
|
||||
|
||||
3. **Reštartujte PostgreSQL:**
|
||||
```bash
|
||||
docker restart <postgres-container-name>
|
||||
```
|
||||
|
||||
4. **Overte že databáza existuje:**
|
||||
```bash
|
||||
docker exec <postgres-container-name> psql -U ebook_user -l
|
||||
```
|
||||
|
||||
### **Problem: SSL certifikát nefunguje**
|
||||
|
||||
**Symptómy:**
|
||||
- SSL certificate errors
|
||||
- "Not secure" v prehliadači
|
||||
|
||||
**Riešenie:**
|
||||
|
||||
V Coolify:
|
||||
1. Prejdite na **"Domains"**
|
||||
2. Kliknite **"Regenerate Certificate"**
|
||||
3. Počkajte 1-2 minúty
|
||||
4. Skontrolujte či sa certifikát vygeneroval
|
||||
|
||||
DNS check:
|
||||
```bash
|
||||
nslookup ebook.vasa-domena.sk
|
||||
# Overte že IP adresa sedí
|
||||
```
|
||||
|
||||
### **Problem: CORS chyby v Extension**
|
||||
|
||||
**Symptómy:**
|
||||
- Extension nedokáže kontaktovať backend
|
||||
- Console chyby: `CORS policy: No 'Access-Control-Allow-Origin'`
|
||||
|
||||
**Riešenie:**
|
||||
|
||||
1. **Skontrolujte CORS_ORIGINS v .env:**
|
||||
```bash
|
||||
CORS_ORIGINS=https://ebook.vasa-domena.sk
|
||||
```
|
||||
|
||||
2. **Overte že extension používa správnu URL:**
|
||||
- Otvorte `ebook_extension/config.js`
|
||||
- Skontrolujte `API_BASE: "https://ebook.vasa-domena.sk"`
|
||||
|
||||
3. **Reštartujte backend:**
|
||||
```bash
|
||||
docker restart <backend-container-name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Performance Tuning
|
||||
|
||||
### **Optimalizácia Pre Production**
|
||||
|
||||
1. **Zvýšte počet workers:**
|
||||
```bash
|
||||
# V .env
|
||||
WORKERS=4 # 2-4x počet CPU cores
|
||||
```
|
||||
|
||||
2. **Použite Gunicorn namiesto Uvicorn:**
|
||||
|
||||
Upravte `Dockerfile`:
|
||||
```dockerfile
|
||||
CMD ["gunicorn", "main:app", \
|
||||
"-w", "4", \
|
||||
"-k", "uvicorn.workers.UvicornWorker", \
|
||||
"--bind", "0.0.0.0:8000", \
|
||||
"--access-logfile", "-", \
|
||||
"--error-logfile", "-"]
|
||||
```
|
||||
|
||||
3. **Povoľte PostgreSQL connection pooling:**
|
||||
|
||||
V backend kóde (SQLAlchemy):
|
||||
```python
|
||||
engine = create_engine(
|
||||
DATABASE_URL,
|
||||
pool_size=20,
|
||||
max_overflow=40,
|
||||
pool_pre_ping=True
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Bezpečnosť
|
||||
|
||||
### **Checklist pred produkciou:**
|
||||
|
||||
- [ ] `DEBUG=false`
|
||||
- [ ] Silné `ADMIN_PASSWORD` (min 16 znakov)
|
||||
- [ ] Unikátny `SECRET_KEY` (32+ znakov)
|
||||
- [ ] `ENVIRONMENT=production`
|
||||
- [ ] Špecifické `CORS_ORIGINS` (nie wildcard)
|
||||
- [ ] SSL/HTTPS enabled
|
||||
- [ ] Firewall nakonfigurovaný
|
||||
- [ ] Pravidelné zálohy nastavené
|
||||
- [ ] Log monitoring aktívny
|
||||
- [ ] Environment variables sú označené ako secret v Coolify
|
||||
|
||||
### **Pravidelná údržba:**
|
||||
|
||||
```bash
|
||||
# Rotácia logov (každý mesiac)
|
||||
docker exec <backend-container-name> find /app/admin-backend/logs -name "*.log" -mtime +30 -delete
|
||||
|
||||
# Záloha databázy (každý týždeň)
|
||||
docker exec <postgres-container-name> pg_dump -U ebook_user ebook_prod > backup_weekly.sql
|
||||
|
||||
# Docker cleanup (každý mesiac)
|
||||
docker system prune -af --volumes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📱 Chrome Extension Setup
|
||||
|
||||
Po úspešnom deployi backendu:
|
||||
|
||||
### **1. Aktualizujte Extension Config**
|
||||
|
||||
```bash
|
||||
# Lokálne na vašom počítači
|
||||
cd /home/richardtekula/Documents/WORK/extension/Ebook_System/ebook_extension
|
||||
|
||||
# Otvorte config.js
|
||||
nano config.js
|
||||
```
|
||||
|
||||
Zmeňte:
|
||||
```javascript
|
||||
export const CONFIG = {
|
||||
API_BASE: "https://ebook.vasa-domena.sk", // ← VAŠA DOMÉNA!
|
||||
VERIFY_ENDPOINT: "/verify",
|
||||
TRANSLATIONS_ENDPOINT: "/translations/latest",
|
||||
// ... zvyšok
|
||||
};
|
||||
```
|
||||
|
||||
### **2. Načítanie do Chrome**
|
||||
|
||||
1. Chrome: `chrome://extensions/`
|
||||
2. Zapnite "Developer mode"
|
||||
3. "Load unpacked"
|
||||
4. Vyberte `ebook_extension/` priečinok
|
||||
5. Hotovo! 🎉
|
||||
|
||||
### **3. Testovanie**
|
||||
|
||||
1. Kliknite na extension icon
|
||||
2. Zadajte testovací kupón
|
||||
3. Verify
|
||||
4. Vyberte jazyk
|
||||
5. Test translation
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Hotovo!
|
||||
|
||||
Váš Ebook Translation System je úspešne nasadený na Coolify!
|
||||
|
||||
### **Ďalšie kroky:**
|
||||
|
||||
1. ✅ Vytvorte prvých admin používateľov
|
||||
2. ✅ Vygenerujte kupóny pre používateľov
|
||||
3. ✅ Nahrajte prekladové súbory
|
||||
4. ✅ Distribuujte Chrome extension
|
||||
5. ✅ Nastavte monitoring a alerting
|
||||
6. ✅ Pravidelné zálohy
|
||||
|
||||
**Potrebujete pomoc?** Skontrolujte logy alebo kontaktujte podporu.
|
||||
|
||||
---
|
||||
|
||||
## 📞 Užitočné Odkazy
|
||||
|
||||
- **Coolify Dokumentácia:** https://coolify.io/docs
|
||||
- **Docker Compose Docs:** https://docs.docker.com/compose/
|
||||
- **FastAPI Docs:** https://fastapi.tiangolo.com/
|
||||
- **PostgreSQL Docs:** https://www.postgresql.org/docs/
|
||||
|
||||
---
|
||||
|
||||
**Autor:** Ebook Translation System Team
|
||||
**Verzia:** 1.0.0
|
||||
**Posledná aktualizácia:** {{ current_date }}
|
||||
Reference in New Issue
Block a user