From d4de016bef6506aa5d0728bf6537b233dd20fc99 Mon Sep 17 00:00:00 2001 From: oleh Date: Wed, 9 Apr 2025 10:43:14 +0200 Subject: [PATCH] upd readme --- z2/README.md | 138 +++++++++++++++++++++++++++++---------------------- 1 file changed, 78 insertions(+), 60 deletions(-) diff --git a/z2/README.md b/z2/README.md index 0e19ecf..5d32038 100644 --- a/z2/README.md +++ b/z2/README.md @@ -1,86 +1,99 @@ + # Battleship Web Application -## 1. Podmienky na nasadenie a spustenie +## 1. Opis aplikácie +**Battleship Web Application** je interaktívna hra „Battleship“, v ktorej hráči zadávajú svoje mená, umiestňujú lode a súperia proti sebe. Aplikácia je rozdelená do troch hlavných služieb: +- **Frontend:** Poskytuje moderné webové rozhranie (na React-e), cez ktoré hráči vykonávajú svoje akcie. +- **Backend:** Slúži ako serverová logika, ktorá spracováva požiadavky, komunikuje s databázou a riadi hernú logiku. +- **Databáza (MySQL):** Ukladá trvalé dáta – informácie o hrách, výsledkoch a nastaveniach – s využitím persistent volume pre zabezpečenie dát aj po reštarte. -Na spustenie tejto aplikácie je potrebný nasledujúci softvér: -- **Docker** (nainštalovaný a správne nakonfigurovaný) -- **Docker Compose** (verzia 3.8 a vyššia) -- **Bash** (pre spúšťanie skriptov) +--- -Odporúčané prostredie: Linux alebo Windows s nainštalovaným WSL2. +## 2. Zoznam použitých kontajnerov a ich stručný opis +- **battleship_mysql:** + Používa oficiálny Docker image `mysql:8.0.30`. Tento kontajner spúšťa MySQL databázu so základným nastavením (heslo, názov databázy) a využíva pripojený persistent volume pre trvalé ukladanie dát. -## 2. Opis aplikácie +- **battleship_backend:** + Node.js aplikácia, ktorá poskytuje API pre hru, spracováva logiku aplikácie a komunikuje s databázou. Builduje sa z Dockerfile umiestneného v priečinku `./backend`. -Táto webová aplikácia predstavuje jednoduchú hru Battleship. Aplikácia je rozdelená na tri hlavné služby: -- **Frontend:** Webové rozhranie, kde hráči zadávajú svoje mená, umiestňujú svoje lode a hrajú hru. -- **Backend:** Serverová logika, ktorá spracováva požiadavky od frontendu, komunikuje s databázou a ukladá výsledky hier. -- **Databáza (MySQL):** Ukladá trvalé dáta – informácie o hrách, výsledkoch a nastaveniach. Dáta sú uchovávané v persistent volume, aby prežili reštarty kontajnerov. +- **battleship_frontend:** + Webová aplikácia postavená na React-e, ktorá umožňuje interakciu hráčov s hrou. Builduje sa z Dockerfile umiestneného v priečinku `./frontend`. -## 3. Opis virtuálnych sietí a pomenovaných zväzkov +--- -### Virtuálna sieť -- **app-net:** - Všetky kontajnery (frontend, backend, MySQL) bežia v rámci jednej Docker siete s názvom `app-net`. - - Ak sieť nie je vytvorená, skripty ju vytvoria. - - Sieť umožňuje vzájomnú komunikáciu kontajnerov pomocou mien služieb (napr. backend pristupuje k databáze pomocou mena `mysql`). +## 3. Zoznam Kubernetes objektov a ich stručný opis +- **Namespace (battleship-app):** + Poskytuje izolované prostredie pre všetky vytvorené objekty súvisiace s aplikáciou. -### Pomenované zväzky -- **db_data:** - Tento persistent volume je pripojený k službe MySQL a ukladá dáta (obsah databázy) na ceste `/var/lib/mysql`. - - Zabezpečuje, že aj pri reštarte alebo odstránení kontajnera sa dáta nevymažú, pokiaľ ich zámselne neodstránite. +- **Deployment:** + - *battleship-backend:* Deployment pre backend službu s 1 replikou, ktorý zabezpečuje prevádzku Node.js aplikácie. + - *battleship-frontend:* Deployment pre frontend službu s 1 replikou, ktorý zabezpečuje dostupnosť webového rozhrania. -## 4. Opis konfigurácie kontajnerov +- **StatefulSet (battleship-mysql):** + Riadi nasadenie MySQL databázy s 1 replikou a využíva PersistentVolumeClaim na trvalé ukladanie dát. -### MySQL +- **PersistentVolume (PV):** + Definovaný zdroj pre uloženie dát databázy, typicky využívajúci `hostPath` alebo iný storage provisioner. + +- **PersistentVolumeClaim (PVC):** + Požaduje úložný priestor pre MySQL databázu (1Gi), ktorý sa následne pripojí k objektu StatefulSet. + +- **Service:** + - *mysql:* ClusterIP služba pre internú komunikáciu s databázou. + - *backend:* NodePort služba pre prístup ku backend aplikácii. + - *frontend:* NodePort služba pre prístup k webovému rozhraniu frontend aplikácie. + +--- + +## 4. Opis virtuálnych sietí a pomenovaných zväzkov +- **Virtuálna sieť (app-net):** + V prostredí Docker (a Docker Compose) kontajnery bežia vo vymedzenej sieti `app-net`, čo umožňuje vzájomnú komunikáciu pomocou mien služieb. Ak sieť ešte neexistuje, príslušné skripty ju vytvoria. + +- **Pomenovaný zväzok (db_data):** + Tento zväzok slúži pre uchovávanie dát databázy MySQL. Je pripojený do kontajnera na ceste `/var/lib/mysql` a zabezpečuje, že dáta pretrvávajú aj po reštarte alebo odstránení kontajnera. + +--- + +## 5. Opis konfigurácie kontajnerov +### **MySQL** - **Image:** `mysql:8.0.30` - **Premenné prostredia:** - `MYSQL_ROOT_PASSWORD=somepassword` - `MYSQL_DATABASE=battleship` -- **Port:** 3306 (mapovaný na localhost:3306) -- **Persistent Volume:** `db_data` pripojený na `/var/lib/mysql` -- **Sieť:** `app-net` +- **Port:** 3306 (mapovaný na localhost:3306 v Docker prostredí) +- **Persistent Volume:** Pripojený pomenovaný zväzok (db_data) k `/var/lib/mysql` +- **Sieť:** Všetky kontajnery komunikujú cez sieť `app-net` - **Reštart:** `unless-stopped` -### Backend -- **Build:** Dockerfile v priečinku `./backend` +### **Backend** +- **Build:** Docker image sa vytvára pomocou Dockerfile umiestneného v priečinku `./backend`. - **Port:** 4000 (mapovaný na localhost:4000) -- **Environment Variables:** - - `DB_HOST=mysql` (meno služby MySQL v rámci docker-compose) - - `DB_PORT=3306` - - `DB_USER=root` - - `DB_PASSWORD=somepassword` +- **Environment Variables:** + - `DB_HOST=mysql` + - `DB_PORT=3306` + - `DB_USER=root` + - `DB_PASSWORD=somepassword` - `DB_NAME=battleship` -- **Závislosť:** Závisí od služby MySQL (nastavené v `depends_on`) +- **Závislosť:** Nastavená závislosť na MySQL službe (v docker-compose) cez `depends_on` - **Sieť:** `app-net` - **Reštart:** `unless-stopped` -### Frontend -- **Build:** Dockerfile v priečinku `./frontend` +### **Frontend** +- **Build:** Docker image sa vytvára pomocou Dockerfile umiestneného v priečinku `./frontend`. - **Port:** 80 (mapovaný na localhost:3001) -- **Závislosť:** Závisí od backendu (nastavené v `depends_on`) +- **Závislosť:** Nastavená závislosť na backend službe (v docker-compose) cez `depends_on` - **Sieť:** `app-net` - **Reštart:** `unless-stopped` -## 5. Zoznam použitých kontajnerov a ich stručný opis - -- **battleship_mysql:** - Beží MySQL databáza, ktorá ukladá trvalé dáta aplikácie. Používa persistent volume `db_data`. - -- **battleship_backend:** - Node.js aplikácia, ktorá poskytuje API pre hru, komunikuje s databázou a spracováva hernú logiku. - -- **battleship_frontend:** - Webové rozhranie aplikácie (React), prostredníctvom ktorého hráči interagujú s hrou. +--- ## 6. Návod ako pripraviť, spustiť, pozastaviť a vymazať aplikáciu -Súčasťou projektu sú štyri skripty: - ### Príprava aplikácie **prepare-app.sh** Tento skript: -- Vytvorí externú sieť `app-net` (ak ešte neexistuje). -- Zostaví Docker obrazy pre MySQL, backend a frontend prostredníctvom docker-compose. +- Vytvorí externú Docker sieť `app-net` (ak ešte neexistuje). +- Zostaví Docker obrazy pre MySQL (ak je potrebný custom image), backend a frontend (na základe Dockerfile v príslušných adresároch). Spustenie: ```bash @@ -90,7 +103,7 @@ Spustenie: ### Spustenie aplikácie **start-app.sh** Tento skript: -- Spustí všetky kontajnery (MySQL, backend, frontend) pomocou `docker-compose up -d`. +- Spustí všetky kontajnery (MySQL, backend, frontend) pomocou príkazu `docker-compose up -d` (alebo príkazov pre Kubernetes, ak sa používa K8s). - Vypíše informácie o dostupnosti aplikácie. Spustenie: @@ -101,7 +114,7 @@ Spustenie: ### Pozastavenie aplikácie **stop-app.sh** Tento skript: -- Pozastaví všetky služby, pričom dáta v databáze ostanú zachované (persistent volume). +- Pozastaví všetky služby, pričom dáta v databáze (persistent volume) zostanú zachované. Spustenie: ```bash @@ -111,21 +124,26 @@ Spustenie: ### Odstránenie aplikácie **remove-app.sh** Tento skript: -- Odstráni všetky vytvorené kontajnery, obrazy a persistent volume (ak sa použije parameter `-v`). +- Odstráni všetky vytvorené kontajnery, obrazy a (ak je použitý parameter `-v`) aj persistent volume. Spustenie: ```bash ./remove-app.sh ``` +--- + ## 7. Návod ako si pozrieť aplikáciu na webovom prehliadači -### Frontend: -Otvorte webový prehliadač a zadajte: [http://localhost:3001](http://localhost:3001) +- **Frontend:** + Otvorte webový prehliadač a zadajte adresu: + [http://localhost:3001](http://localhost:3001) -### Backend API: -API je dostupné na: [http://localhost:4000](http://localhost:4000) +- **Backend API:** + API je dostupné na: + [http://localhost:4000](http://localhost:4000) -### MySQL: -Pripojte sa k databáze na `localhost:3306` pomocou MySQL klienta. +- **MySQL:** + Pre pripojenie k databáze použite MySQL klienta a pripojte sa na: + `localhost:3306`