ebook-extension/NAVOD_SLOVENSKY.md

# 📚 Ebook Translation System - Slovenský Návod

## 🎯 Čo je tento projekt?

Komplexný **systém na správu prekladov e-kníh** pozostávajúci z 3 častí:

1. **Backend API** (FastAPI) - Správa kupónových kódov a prekladových súborov
2. **Admin Dashboard** (Webové rozhranie) - Správa kupónov a nahrávanie prekladov
3. **Chrome Extension** - Automatická aplikácia prekladov na stránky e-kníh

---

## 🐳 Docker Deployment (Coolify)

### Čo budete potrebovať:

- ✅ Server s nainštalovaným Coolify
- ✅ Docker a Docker Compose (už je v Coolify)
- ✅ Prístup k serveru cez SSH
- ✅ Doména alebo subdoména (voliteľné, ale odporúčané)

---

## 📦 Štruktúra Docker stacku

```
┌─────────────────────────────────────────┐
│         Coolify Deployment              │
├─────────────────────────────────────────┤
│                                         │
│  ┌──────────────────────────────────┐   │
│  │   Nginx Reverse Proxy            │   │
│  │   (Port 80/443)                  │   │
│  └──────────────┬───────────────────┘   │
│                 │                       │
│  ┌──────────────▼───────────────────┐   │
│  │   Backend + Frontend             │   │
│  │   (FastAPI + Static Files)       │   │
│  │   Port: 8000                     │   │
│  └──────────────┬───────────────────┘   │
│                 │                       │
│  ┌──────────────▼───────────────────┐   │
│  │   PostgreSQL Database            │   │
│  │   Port: 5432 (internal)          │   │
│  └──────────────────────────────────┘   │
│                                         │
└─────────────────────────────────────────┘
```

---

## 🚀 Krok za krokom - Nasadenie na Coolify

### **KROK 1: Príprava súborov**

Všetky potrebné súbory sú už pripravené v projekte:
- `Dockerfile` - Definícia Docker obrazu pre backend
- `docker-compose.yml` - Orchestrácia všetkých služieb
- `.env.production` - Produkčná konfigurácia
- `.dockerignore` - Čo vylúčiť z Docker obrazu

### **KROK 2: Nastavenie premenných prostredia**

V Coolify nastavte tieto environment variables:

```bash
# Database
DATABASE_URL=postgresql://ebook_user:SILNE_HESLO_123@postgres:5432/ebook_prod

# Security
SECRET_KEY=vygenerovany-tajny-kluc-min-32-znakov-ZMENTE-TO
DEBUG=false
ENVIRONMENT=production

# Admin prístup (ZMEŇTE!)
ADMIN_USERNAME=admin
ADMIN_PASSWORD=VaseSilneHeslo123!

# CORS - Vaša doména
CORS_ORIGINS=https://vasa-domena.sk,https://www.vasa-domena.sk
TRUSTED_HOSTS=vasa-domena.sk,www.vasa-domena.sk

# Aplikácia
APP_NAME=Ebook Translation System
APP_VERSION=1.0.0
LOG_LEVEL=WARNING

# Server
HOST=0.0.0.0
PORT=8000

# PostgreSQL (pre databázový kontajner)
POSTGRES_USER=ebook_user
POSTGRES_PASSWORD=SILNE_HESLO_123
POSTGRES_DB=ebook_prod
```

### **KROK 3: Nasadenie v Coolify**

#### Možnosť A: Git Repository (Odporúčané)

1. **Nahrajte projekt na Git** (GitHub, GitLab, atď.)
2. **V Coolify:**
   - Kliknite na "New Resource"
   - Vyberte "Docker Compose"
   - Pripojte váš Git repozitár
   - Nastavte branch (napr. `main`)
   - Coolify automaticky detekuje `docker-compose.yml`

3. **Nastavte Environment Variables:**
   - V Coolify prejdite na Environment
   - Pridajte všetky premenné vyššie
   - Uložte

4. **Nastavte Domain:**
   - V Coolify prejdite na Domains
   - Pridajte vašu doménu (napr. `ebook.vasa-domena.sk`)
   - Povoľte SSL (Let's Encrypt)

5. **Deploy:**
   - Kliknite "Deploy"
   - Coolify stiahne kód, buildne Docker obrazy a spustí kontajnery

#### Možnosť B: Manuálne cez SSH

```bash
# 1. Pripojte sa na server
ssh user@vas-server.sk

# 2. Vytvorte adresár pre projekt
mkdir -p /srv/ebook-system
cd /srv/ebook-system

# 3. Skopírujte súbory (použite scp alebo git clone)
git clone https://github.com/vase-repo/ebook-system.git .

# 4. Vytvorte .env súbor
nano .env.production
# Vložte konfiguráciu z KROK 2

# 5. Spustite Docker Compose
docker-compose up -d

# 6. Skontrolujte stav
docker-compose ps
docker-compose logs -f
```

### **KROK 4: Overenie nasadenia**

```bash
# Skontrolujte health endpoint
curl https://vasa-domena.sk/health

# Očakávaná odpoveď:
# {
#   "status": "healthy",
#   "database_status": "connected",
#   "version": "1.0.0",
#   "environment": "production"
# }
```

### **KROK 5: Prvé prihlásenie**

1. Otvorte prehliadač: `https://vasa-domena.sk/login`
2. Prihláste sa s credentials z `.env`:
   - Username: `admin` (alebo čo ste nastavili)
   - Password: Vaše heslo z `ADMIN_PASSWORD`
3. **DÔLEŽITÉ:** Po prvom prihlásení zmeňte heslo!

---

## 🔧 Konfigurácia Chrome Extension

### **KROK 1: Upravte API URL v Extension**

```bash
# Otvorte súbor config.js v extension adresári
nano ebook_extension/config.js
```

Zmeňte API URL na vašu produkčnú doménu:

```javascript
export const CONFIG = {
  API_BASE: "https://vasa-domena.sk",  // ← Zmeňte toto!
  VERIFY_ENDPOINT: "/verify",
  TRANSLATIONS_ENDPOINT: "/translations/latest",
  // ... zvyšok ostáva
};
```

### **KROK 2: Načítanie Extension do Chrome**

1. Otvorte Chrome: `chrome://extensions/`
2. Zapnite **"Developer mode"** (prepínač vpravo hore)
3. Kliknite **"Load unpacked"**
4. Vyberte priečinok: `/home/richardtekula/Documents/WORK/extension/Ebook_System/ebook_extension/`
5. Extension je nainštalovaný! 🎉

### **KROK 3: Testovanie Extension**

1. Kliknite na ikonu extension v Chrome
2. Zadajte kupónový kód (vygenerovaný v admin paneli)
3. Kliknite "Verify"
4. Ak je kód platný, vyberte jazyk
5. Spustite preklad

---

## 📊 Pracovný tok používania

### **Pre Administrátora:**

1. **Prihlásenie:**
   - Otvorte `https://vasa-domena.sk/login`
   - Prihláste sa admin účtom

2. **Generovanie kupónov:**
   - Prejdite na záložku "Generate"
   - Vyberte Single (1 kód) alebo Bulk (viacero)
   - Kliknite "Generate Codes"
   - Kódy sa automaticky uložia do databázy

3. **Nahranie prekladového súboru:**
   - Prejdite na záložku "Translation Upload"
   - Vyberte Excel súbor (.xlsx)
   - Súbor musí obsahovať stĺpce: `Original`, `Slovak`, `Czech`, atď.
   - Kliknite "Upload"

4. **Správa kupónov:**
   - Prezrite zoznam všetkých kupónov
   - Vyhľadávajte podľa kódu
   - Vidíte stav použitia (použité/nepoužité)
   - Môžete mazať kupóny

### **Pre koncového používateľa:**

1. **Inštalácia Extension** (raz)
   - Nainštalujte Chrome extension
   - Extension je pripravený na použitie

2. **Verifikácia kupónu:**
   - Otvorte extension (klik na ikonu)
   - Zadajte kupónový kód od admina
   - Kliknite "Verify"
   - Systém overí kód proti databáze

3. **Výber jazyka:**
   - Po úspešnej verifikácii vyberte cieľový jazyk
   - Kliknite "Start Translation"

4. **Automatický preklad:**
   - Extension stiahne prekladový súbor
   - Automaticky identifikuje sekcie na stránke
   - Aplikuje preklady
   - Zvýrazní preložené sekcie
   - Pridá poznámky s prekladmi
   - Automaticky prejde na ďalšiu stránku

---

## 🔐 Bezpečnosť a Best Practices

### **Pred spusteným v produkcii:**

- [ ] Zmeňte `ADMIN_PASSWORD` na silné heslo (min. 16 znakov)
- [ ] Vygenerujte nový `SECRET_KEY` (použite: `openssl rand -base64 32`)
- [ ] Nastavte `DEBUG=false`
- [ ] Nastavte `ENVIRONMENT=production`
- [ ] Aktualizujte `CORS_ORIGINS` na vašu konkrétnu doménu
- [ ] Povoľte SSL/HTTPS (Coolify to robí automaticky cez Let's Encrypt)
- [ ] Nastavte firewall pravidlá
- [ ] Zálohujte databázu (nastavte automatické zálohy)

### **Generovanie bezpečných kľúčov:**

```bash
# SECRET_KEY generovanie
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

# Alebo pomocou openssl
openssl rand -base64 32
```

---

## 🛠️ Údržba a Monitoring

### **Docker príkazy:**

```bash
# Zobraziť stav kontajnerov
docker-compose ps

# Zobraziť logy
docker-compose logs -f

# Zobraziť logy len backend
docker-compose logs -f backend

# Zobraziť logy len databáza
docker-compose logs -f postgres

# Reštartovať všetky služby
docker-compose restart

# Reštartovať len backend
docker-compose restart backend

# Zastaviť všetko
docker-compose down

# Zastaviť a zmazať volumes (POZOR: zmaže databázu!)
docker-compose down -v

# Znovu buildiť a spustiť
docker-compose up -d --build
```

### **Zálohovanie databázy:**

```bash
# Vytvoriť zálohu
docker-compose exec postgres pg_dump -U ebook_user ebook_prod > backup_$(date +%Y%m%d).sql

# Obnoviť zo zálohy
docker-compose exec -T postgres psql -U ebook_user ebook_prod < backup_20250111.sql
```

### **Sledovanie logov aplikácie:**

```bash
# Real-time logy
docker-compose logs -f backend

# Posledných 100 riadkov
docker-compose logs --tail=100 backend

# Logy s časovými pečiatkami
docker-compose logs -f -t backend

# Hľadať chyby v logoch
docker-compose logs backend | grep -i error
```

---

## 🐛 Riešenie problémov

### **Backend sa nespustí:**

```bash
# Skontrolujte logy
docker-compose logs backend

# Skontrolujte environment variables
docker-compose config

# Reštartujte kontajner
docker-compose restart backend
```

### **Databáza nie je dostupná:**

```bash
# Skontrolujte či PostgreSQL beží
docker-compose ps postgres

# Skontrolujte logy databázy
docker-compose logs postgres

# Reštartujte databázu
docker-compose restart postgres

# Pripojte sa do databázy
docker-compose exec postgres psql -U ebook_user -d ebook_prod
```

### **Extension nemôže kontaktovať backend:**

1. **Skontrolujte CORS nastavenia** v `.env`:
   ```bash
   CORS_ORIGINS=https://vasa-domena.sk
   ```

2. **Overte že backend beží:**
   ```bash
   curl https://vasa-domena.sk/health
   ```

3. **Skontrolujte config.js v extension:**
   ```javascript
   API_BASE: "https://vasa-domena.sk"  // Správna URL?
   ```

4. **Pozrite Browser Console** (F12):
   - Hľadajte CORS chyby
   - Hľadajte network chyby

### **SSL certifikát nefunguje:**

V Coolify:
1. Prejdite na "Domains"
2. Kliknite "Regenerate Certificate"
3. Počkajte 1-2 minúty
4. Testujte znovu

---

## 📈 Monitoring a Štatistiky

### **Health Check Endpoint:**

```bash
# Základný health check
curl https://vasa-domena.sk/health

# Detailný výstup
curl -s https://vasa-domena.sk/health | jq
```

### **Štatistiky kupónov:**

```bash
# Pripojte sa do databázy
docker-compose exec postgres psql -U ebook_user -d ebook_prod

# SQL dotazy:
-- Celkový počet kupónov
SELECT COUNT(*) FROM coupon_codes;

-- Použité vs nepoužité
SELECT
  COUNT(*) FILTER (WHERE usage_count > 0) as used,
  COUNT(*) FILTER (WHERE usage_count = 0) as unused
FROM coupon_codes;

-- Posledných 10 použitých kupónov
SELECT code, used_at
FROM coupon_codes
WHERE usage_count > 0
ORDER BY used_at DESC
LIMIT 10;
```

---

## 🔄 Update a Upgrade

### **Aktualizácia kódu:**

```bash
# Ak používate Git
cd /srv/ebook-system
git pull origin main

# Rebuild a reštart
docker-compose up -d --build
```

### **Aktualizácia databázovej schémy:**

```bash
# Spustite migračný skript (ak existuje)
docker-compose exec backend python init_db.py
```

---

## 📞 Podpora a Dokumentácia

### **Súbory dokumentácie:**

- `SYSTEM_DOCUMENTATION.md` - Kompletná systémová dokumentácia
- `README.md` - Anglická dokumentácia
- `NAVOD_SLOVENSKY.md` - Tento súbor

### **Logy:**

- Aplikačné logy: `docker-compose logs backend`
- Databázové logy: `docker-compose logs postgres`
- Nginx logy: V Coolify pod "Logs"

### **API Dokumentácia:**

- Swagger UI: `https://vasa-domena.sk/docs`
- ReDoc: `https://vasa-domena.sk/redoc`

---

## ✅ Checklist pre produkčné nasadenie

### **Pred spustením:**

- [ ] PostgreSQL databáza je vytvorená
- [ ] Environment variables sú nastavené
- [ ] `ADMIN_PASSWORD` je zmenený
- [ ] `SECRET_KEY` je vygenerovaný
- [ ] `DEBUG=false`
- [ ] `ENVIRONMENT=production`
- [ ] Doména je nakonfigurovaná
- [ ] SSL certifikát je aktívny
- [ ] CORS je nastavený správne
- [ ] Firewall pravidlá sú nastavené

### **Po spustení:**

- [ ] Health endpoint odpovedá (200 OK)
- [ ] Admin prihlásenie funguje
- [ ] Generovanie kupónov funguje
- [ ] Nahrávanie prekladov funguje
- [ ] Extension sa vie pripojiť k backendu
- [ ] Verifikácia kupónov funguje
- [ ] Preklad funguje
- [ ] Zálohy sú nastavené

---

## 🎓 Užitočné príkazy

```bash
# Zobraziť všetky bežiace kontajnery
docker ps

# Zobraziť použité resources
docker stats

# Vyčistiť nepoužívané obrazy
docker system prune -a

# Export databázy
docker-compose exec postgres pg_dump -U ebook_user ebook_prod > backup.sql

# Import databázy
cat backup.sql | docker-compose exec -T postgres psql -U ebook_user ebook_prod

# Sledovať logy v real-time
docker-compose logs -f --tail=100

# Vstúpiť do backend kontajnera
docker-compose exec backend bash

# Vstúpiť do databázového kontajnera
docker-compose exec postgres psql -U ebook_user ebook_prod
```

---

## 🚀 Hotovo!

Váš Ebook Translation System je teraz nasadený a pripravený na používanie!

**Čo ďalej?**
1. Prihláste sa do admin panelu
2. Vygenerujte prvé kupóny
3. Nahrajte prekladový súbor
4. Otestujte Chrome extension
5. Rozdajte kupóny používateľom

**Tešíme sa na vašu spätnú väzbu!** 🎉