foxerBN/ebook-extension

Fork 0

Files

richardtekula e1b95c613d Initial commit: Ebook Translation System with Docker setup

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

15 KiB

Raw Permalink Blame History

🚀 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

# 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

Prihláste sa do Coolify webového rozhrania
Kliknite na "+ New" alebo "New Resource"
Vyberte "Docker Compose"

KROK 2: Konfigurácia Git repozitára

Source: Vyberte váš Git provider (GitHub, GitLab, atď.)

Repository: Zadajte URL vašeho repozitára

https://github.com/vase-meno/ebook-system.git

Branch: main (alebo master, podľa vášho nastavenia)
Auto Deploy: Zapnite (automatický deployment pri každom push)

KROK 3: Nastavenie Build Configuration

Build Pack: Docker Compose
Docker Compose Location: docker-compose.yml (v root adresári)
Base Directory: / (root projektu)

KROK 4: Environment Variables

V Coolify prejdite na "Environment" sekciu a pridajte tieto premenné:

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

Prejdite na "Domains" sekciu
Kliknite "Add Domain"
Zadajte vašu doménu:
```
ebook.vasa-domena.sk
```
Zapnite "Enable SSL/TLS" (Let's Encrypt)
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:

# SSH do servera
ssh user@vas-server.sk

# Zoznam volumes
docker volume ls | grep ebook

KROK 7: Deploy!

Skontrolujte všetky nastavenia
Kliknite "Deploy" alebo "Start"
Sledujte deployment logy v reálnom čase

Coolify vykoná:

Clone Git repozitára
Build Docker images (podľa Dockerfile)
Vytvorenie volumes
Spustenie PostgreSQL kontajnera
Spustenie Backend kontajnera
Nastavenie Traefik reverse proxy
Vygenerovanie SSL certifikátu (Let's Encrypt)

✅ Overenie Deploymentu

1. Skontrolujte Health Endpoint

curl https://ebook.vasa-domena.sk/health

Očakávaný výstup:

{
  "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ť

Vygenerujte kupón:
- V admin paneli prejdite na "Generate"
- Vygenerujte testovací kupón
- Skontrolujte či sa uložil do databázy
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

V Coolify dashboarde kliknite na váš projekt
Prejdite na "Logs"
Vyberte kontajner:
- backend - Aplikačné logy
- postgres - Databázové logy

Real-time logs:

# 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

# 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

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

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

Prejdite na váš projekt
Kliknite "Redeploy" alebo "Restart"
Sledujte logy

Rebuild from Scratch

Ak potrebujete celkom nový build (napr. po zmene Dockerfile):

V Coolify:

Zastavte aplikáciu: "Stop"
Vymažte staré images (voliteľné)
Kliknite "Deploy" znovu

SSH metóda:

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

Skontrolujte logy:
```
docker logs <backend-container-name>
```

Skontrolujte environment variables:

docker exec <backend-container-name> env | grep DATABASE_URL

Overte databázové pripojenie:

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:

Skontrolujte či PostgreSQL beží:
```
docker ps | grep postgres
```
Skontrolujte logy:
```
docker logs <postgres-container-name>
```

Reštartujte PostgreSQL:

docker restart <postgres-container-name>

Overte že databáza existuje:

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:

Prejdite na "Domains"
Kliknite "Regenerate Certificate"
Počkajte 1-2 minúty
Skontrolujte či sa certifikát vygeneroval

DNS check:

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:

Skontrolujte CORS_ORIGINS v .env:

CORS_ORIGINS=https://ebook.vasa-domena.sk

Overte že extension používa správnu URL:
- Otvorte ebook_extension/config.js
- Skontrolujte API_BASE: "https://ebook.vasa-domena.sk"

Reštartujte backend:

docker restart <backend-container-name>

📊 Performance Tuning

Optimalizácia Pre Production

Zvýšte počet workers:

# V .env
WORKERS=4  # 2-4x počet CPU cores

Použite Gunicorn namiesto Uvicorn:

Upravte Dockerfile:

CMD ["gunicorn", "main:app", \
     "-w", "4", \
     "-k", "uvicorn.workers.UvicornWorker", \
     "--bind", "0.0.0.0:8000", \
     "--access-logfile", "-", \
     "--error-logfile", "-"]

Povoľte PostgreSQL connection pooling:

V backend kóde (SQLAlchemy):

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:

# 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

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

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

Chrome: chrome://extensions/
Zapnite "Developer mode"
"Load unpacked"
Vyberte ebook_extension/ priečinok
Hotovo! 🎉

3. Testovanie

Kliknite na extension icon
Zadajte testovací kupón
Verify
Vyberte jazyk
Test translation

🎉 Hotovo!

Váš Ebook Translation System je úspešne nasadený na Coolify!

Ďalšie kroky:

✅ Vytvorte prvých admin používateľov
✅ Vygenerujte kupóny pre používateľov
✅ Nahrajte prekladové súbory
✅ Distribuujte Chrome extension
✅ Nastavte monitoring a alerting
✅ 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 }}

15 KiB Raw Permalink Blame History

🚀 Coolify Deployment Guide - Ebook Translation System

📋 Predpoklady

Čo potrebujete:

🎯 Architektúra Deploymentu

🔧 Príprava projektu

KROK 1: Nahrajte projekt do Git repozitára

🚀 Nasadenie v Coolify

KROK 1: Vytvorenie nového projektu v Coolify

KROK 2: Konfigurácia Git repozitára

KROK 3: Nastavenie Build Configuration

KROK 4: Environment Variables

KROK 5: Domain Configuration

KROK 6: Storage/Volumes Configuration

KROK 7: Deploy!

✅ Overenie Deploymentu

1. Skontrolujte Health Endpoint

2. Otvorte Admin Panel

3. Skontrolujte Logy v Coolify

4. Testujte funkčnosť

🔍 Monitoring a Debugging

Sledovanie Logov v Coolify

Databázové operácie

Backup Databázy

🔄 Update a Redeploy

Automatický Update (Git Push)

Manuálny Redeploy

Rebuild from Scratch

🛠️ Riešenie Problémov

Problem: Backend sa nespustí

Problem: Databáza nie je dostupná

Problem: SSL certifikát nefunguje

Problem: CORS chyby v Extension

📊 Performance Tuning

Optimalizácia Pre Production

🔒 Bezpečnosť

Checklist pred produkciou:

Pravidelná údržba:

📱 Chrome Extension Setup

1. Aktualizujte Extension Config

2. Načítanie do Chrome

3. Testovanie

🎉 Hotovo!

Ďalšie kroky:

📞 Užitočné Odkazy

15 KiB

Raw Permalink Blame History