Initial commit: Ebook Translation System with Docker setup
This commit is contained in:
richardtekula
562
NAVOD_SLOVENSKY.md
Normal file
562
NAVOD_SLOVENSKY.md
Normal file
@@ -0,0 +1,562 @@
|
||||
# 📚 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!** 🎉
|
||||
Reference in New Issue
Block a user