From 883f62b71728e3146747e93f28697464b40d3561 Mon Sep 17 00:00:00 2001 From: root Date: Mon, 11 May 2026 20:58:59 +0200 Subject: [PATCH] first commit --- README.md | 241 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..bb224b0 --- /dev/null +++ b/README.md @@ -0,0 +1,241 @@ + +## 1. Opis aplikácie + +Riešenie nasadzuje jednoduchú webovú aplikáciu typu guestbook. Používateľ cez webové rozhranie vie zobraziť uložené odkazy a pridať nový odkaz. Frontend komunikuje s backendom cez REST API a backend ukladá dáta do PostgreSQL databázy. + +Aplikácia obsahuje aj kontrolný endpoint: + +```text +/api/health +``` + +Ten slúži na overenie, či backend komunikuje s databázou. + +## 2. Použitý verejný cloud a služby + +Riešenie je pripravené pre Microsoft Azure. Použité sú tieto služby: + +1. Azure Container Registry – ukladanie kontajnerových obrazov frontendu a backendu. +2. Azure Container Apps – spustenie kontajnerov bez vlastnej správy virtuálneho servera. +3. Azure Database for PostgreSQL Flexible Server – spravovaná relačná databáza s trvalým úložiskom a automatickými zálohami. +4. Azure Log Analytics / Container Apps logs – zobrazenie aplikačných logov a prístupov. + +## 3. Architektúra riešenia + +Používateľ pristupuje iba na frontend. Frontend je verejne dostupný cez HTTPS URL vytvorenú službou Azure Container Apps. Požiadavky na `/api/*` posiela Nginx interne na backend. + +Backend nie je verejne vystavený do internetu. Má interný ingress a je dostupný iba z prostredia Azure Container Apps. Backend komunikuje s databázou PostgreSQL cez šifrované pripojenie `sslmode=require`. + +Zjednodušená schéma: + +```text +Používateľ + | + | HTTPS + v +Azure Container Apps – frontend (Nginx) + | + | interné HTTP volanie /api + v +Azure Container Apps – backend (Flask) + | + | PostgreSQL + SSL + v +Azure Database for PostgreSQL Flexible Server +``` + +## 5. Opis súborov + +| Súbor/priečinok | Význam | +|---|---| +| `backend/` | Flask backend aplikácie | +| `backend/app.py` | REST API, inicializácia tabuľky a práca s PostgreSQL | +| `backend/Dockerfile` | Docker obraz backendu | +| `frontend/` | Statický frontend a Nginx konfigurácia | +| `frontend/index.html` | Webové používateľské rozhranie | +| `frontend/nginx.conf.template` | Nginx konfigurácia so zástupnou premennou `BACKEND_URL` | +| `frontend/Dockerfile` | Docker obraz frontendu | +| `docker-compose.yaml` | Lokálne spustenie cez Docker Compose | +| `.env.azure.example` | Vzor konfiguračného súboru pre Azure nasadenie | +| `.env.local.example` | Vzor lokálnej Docker Compose konfigurácie | +| `.gitignore` | Zamedzuje odoslaniu `.env.azure`, `.env.local` a záloh do GITu | +| `prepare-app.sh` | Vytvorí Azure zdroje, buildne obrazy a nasadí aplikáciu | +| `remove-app.sh` | Odstráni celú Azure resource group | +| `backup-db.sh` | Vytvorí manuálnu SQL zálohu databázy cez `pg_dump` | +| `show-logs.sh` | Zobrazí logy frontendu a backendu z Azure Container Apps | +| `start-local.sh`, `stop-local.sh` | Lokálne spustenie/zastavenie Docker Compose verzie | + +## 6. Podmienky na spustenie skriptov + +Skripty sú určené pre Bash prostredie, napríklad Ubuntu, WSL alebo Azure Cloud Shell. + +Potrebné nástroje: + +```bash +az --version +bash --version +``` + +Pred nasadením musí byť používateľ prihlásený do Azure CLI: + +```bash +az login +az account show +``` + +Na manuálnu databázovú zálohu je potrebný aj nástroj `pg_dump`: + +```bash +sudo apt install postgresql-client +``` + +## 7. Príprava konfigurácie + +Najprv sa vytvorí lokálny konfiguračný súbor: + +```bash +cp .env.azure.example .env.azure +``` + +V súbore `.env.azure` treba upraviť hlavne tieto hodnoty: + +```bash +ACR_NAME= +PG_SERVER= +PG_PASSWORD= +``` + +## 8. Nasadenie aplikácie do Azure + +Spustenie nasadenia: + +```bash +chmod +x prepare-app.sh remove-app.sh backup-db.sh show-logs.sh +./prepare-app.sh +``` + +Skript vykoná tieto kroky: + +1. skontroluje Azure CLI a prihlásenie, +2. vytvorí resource group, +3. vytvorí Azure Container Registry, +4. zostaví a odošle Docker image backendu, +5. zostaví a odošle Docker image frontendu, +6. vytvorí PostgreSQL Flexible Server, +7. vytvorí Azure Container Apps environment, +8. nasadí interný backend, +9. nasadí verejný frontend, +10. vypíše verejnú HTTPS adresu aplikácie. + +Po dokončení skript vypíše napríklad: + +```text +https://zkt-frontend...azurecontainerapps.io +``` + +## 9. Použitie aplikácie v prehliadači + +Po otvorení verejnej HTTPS adresy sa zobrazí stránka ZKT Guestbook. + +Používateľ môže: + +1. zadať meno, +2. napísať správu, +3. kliknúť na tlačidlo Pridať správu, +4. overiť, že sa správa uložila a po obnovení stránky zostáva v databáze. + +Backend sa dá overiť na adrese: + +```text +https:///api/health +``` + +Očakávaná odpoveď: + +```json +{ + "database": "connected", + "status": "ok" +} +``` + +## 10. Zobrazenie záznamov o prístupoch z internetu + +Prístupové logy z Nginx frontendu sa zobrazia príkazom: + +```bash +./show-logs.sh +``` + +Ručne cez Azure CLI: + +```bash +az containerapp logs show \ + --name zkt-frontend \ + --resource-group zkt-guestbook-rg \ + --tail 100 +``` + +Vo výstupe sú požiadavky na frontend, napríklad otvorenie hlavnej stránky alebo volanie `/api/health`. + +## 11. Zálohovanie dát + +### Manuálna SQL záloha + +Manuálna záloha sa vykoná príkazom: + +```bash +./backup-db.sh +``` + +Výstup sa uloží do priečinka: + +```text +backups/ +``` + +Príklad názvu súboru: + +```text +guestbook_20260510_143000.sql +``` + +## 12. Odstránenie aplikácie + +Celé cloudové riešenie sa odstráni príkazom: + +```bash +./remove-app.sh +``` + +Skript odstráni celú Azure resource group, teda aj: + +- frontend Container App, +- backend Container App, +- Azure Container Registry, +- PostgreSQL server, +- databázu, +- logovacie zdroje. + +Stav odstránenia sa dá overiť: + +```bash +az group exists --name zkt-guestbook-rg +``` + +## 13. Analýza nákladov na jeden rok prevádzky +Predpoklad: + +- 1000 používateľov denne, +- databáza alebo súbory, +- 2 malé kontajnery v Azure Container Apps, +- 1 PostgreSQL Flexible Server, +- Azure Container Registry Basic. + +Ak by tam chodilo okolo 1000 ľudí denne ročne by to vyšlo cca 750 eur. + +## 15. Použitie generatívnej AI + +Použitý nástroj: + +- ChatGPT, Claude, Gemini.