foxerBN/ebook-extension

Fork 0

Files

richardtekula e1b95c613d Initial commit: Ebook Translation System with Docker setup

2025-11-11 16:01:34 +01:00

14 KiB

Raw Permalink Blame History

📚 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í:

Backend API (FastAPI) - Správa kupónových kódov a prekladových súborov
Admin Dashboard (Webové rozhranie) - Správa kupónov a nahrávanie prekladov
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:

# 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é)

Nahrajte projekt na Git (GitHub, GitLab, atď.)
V Coolify:
- Kliknite na "New Resource"
- Vyberte "Docker Compose"
- Pripojte váš Git repozitár
- Nastavte branch (napr. main)
- Coolify automaticky detekuje docker-compose.yml
Nastavte Environment Variables:
- V Coolify prejdite na Environment
- Pridajte všetky premenné vyššie
- Uložte
Nastavte Domain:
- V Coolify prejdite na Domains
- Pridajte vašu doménu (napr. ebook.vasa-domena.sk)
- Povoľte SSL (Let's Encrypt)
Deploy:
- Kliknite "Deploy"
- Coolify stiahne kód, buildne Docker obrazy a spustí kontajnery

Možnosť B: Manuálne cez SSH

# 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

# 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

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

🔧 Konfigurácia Chrome Extension

KROK 1: Upravte API URL v Extension

# 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:

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

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

KROK 3: Testovanie Extension

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

📊 Pracovný tok používania

Pre Administrátora:

Prihlásenie:
- Otvorte https://vasa-domena.sk/login
- Prihláste sa admin účtom
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
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"
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:

Inštalácia Extension (raz)
- Nainštalujte Chrome extension
- Extension je pripravený na použitie
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
Výber jazyka:
- Po úspešnej verifikácii vyberte cieľový jazyk
- Kliknite "Start Translation"
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:

# 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:

# 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:

# 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:

# 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í:

# Skontrolujte logy
docker-compose logs backend

# Skontrolujte environment variables
docker-compose config

# Reštartujte kontajner
docker-compose restart backend

Databáza nie je dostupná:

# 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:

Skontrolujte CORS nastavenia v .env:
```
CORS_ORIGINS=https://vasa-domena.sk
```
Overte že backend beží:
```
curl https://vasa-domena.sk/health
```

Skontrolujte config.js v extension:

API_BASE: "https://vasa-domena.sk"  // Správna URL?

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

SSL certifikát nefunguje:

V Coolify:

Prejdite na "Domains"
Kliknite "Regenerate Certificate"
Počkajte 1-2 minúty
Testujte znovu

📈 Monitoring a Štatistiky

Health Check Endpoint:

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

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

Štatistiky kupónov:

# 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:

# 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:

# 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

# 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?

Prihláste sa do admin panelu
Vygenerujte prvé kupóny
Nahrajte prekladový súbor
Otestujte Chrome extension
Rozdajte kupóny používateľom

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

14 KiB Raw Permalink Blame History