ebook-extension/COOLIFY_DEPLOYMENT.md

# 🚀 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 }}