Merge pull request #1 from Student-Cyber-Games/update-readme-instructions

docs: Add detailed run instructions to README

Author: tomaskebrle

README.md

@@ -1,102 +1,109 @@
-# Tour de App - Vue + Express Boilerplate
+# Tour de App - Vue + Express boiler plate
 
-> **Note:** Czech version is available below / Česká verze je k dispozici níže
+Šablona pro vývoj aplikace v soutěži Tour de App společně s frontendovou částí ve frameworku [Vue](https://vuejs.org/), a backendovou částí v [Express](https://expressjs.com/).
 
-A template for developing applications for the Tour de App competition with a frontend in [Vue](https://vuejs.org/) and a backend in [Express](https://expressjs.com/).
-
-## Initial Setup
+## Prvotní nastavení
 
-In the frontend and backend directories, there are `.env.example` files that need to be renamed to `.env` and the values adjusted as needed.
+V složkách pro frontend a backend jsou `.env.example` soubory, které je potřeba přejmenovat na `.env` a upravit hodnoty dle potřeby.
 
-For production development, you need to set `VITE_API_URL` to the API server URL in the `tourdeapp.yaml` file to the URL you find on the main page of your project on [tourde.cloud](https://tourde.cloud/).
+Pro produkční vývoj je potřeba nastavit `VITE_API_URL` na URL API serveru v souboru `tourdeapp.yaml` na URL kterou najdete na hlavní stránce Vašeho projektu na [tourde.cloud](https://tourde.cloud/).
 
 > [!WARNING]
-> If you want to change the database password, you need to change it in the `tourdeapp.yaml` file, `apps/server/.env`, and for local development in the `apps/server/package.json` file.
+> Pokud chcete měnit heslo od databáze, je potřeba ho změnit v souboru `tourdeapp.yaml`, `apps/server/.env` a pro lokální vývoj v souboru `apps/server/package.json`.
 
-## Local Development
+## Lokální vývoj
 
-For local development, you need to run:
-- **frontend** (`apps/web`), using `npm run dev` (in the correct directory - `apps/web`), it will start at [http://localhost:3001](http://localhost:3001)
-- **backend** (`apps/server`), using `npm run dev` (in the correct directory - `apps/server`), it will start at [http://localhost:3000](http://localhost:3000)
-- **MySQL** database, which is defined in `docker-compose.yaml`, using `npm run db` (in the `apps/server` directory), the database will run on port 3306
+Pro lokální vývoj je potřeba spustit tři služby: databázi, backend a frontend. Níže najdete podrobné instrukce krok za krokem.
 
-> [!WARNING]
-> The database is not persistent, data will be lost after shutting down the Docker container.
+### Krok 1: Nastavení environmentálních proměnných
 
-## Production Setup (how does it run on our servers?)
+Nejprve je potřeba nastavit environmentální proměnné:
 
-How the application runs on [tourde.cloud](https://tourde.cloud/) is defined in the `tourdeapp.yaml` file in the root directory of this repository. This boilerplate includes pre-configured services:
-```
-- caddy (reverse proxy for frontend and backend) - handles routing requests to your application to the correct place (i.e., /* to frontend and /api/* to backend)
-- web (frontend application)
-- server (backend application)
-- mysql (MySQL database)
-```
+1. **Backend**: V adresáři `apps/server` přejmenujte soubor `.env.example` na `.env`:
+   ```bash
+   cd apps/server
+   cp .env.example .env
+   ```
 
-> [!WARNING]
-> The database is not persistent, data will be lost after uploading a new version of the application.
+2. **Frontend**: V adresáři `apps/web` přejmenujte soubor `.env.example` na `.env`:
+   ```bash
+   cd ../web
+   cp .env.example .env
+   ```
 
-> [!NOTE]
-> The reverse proxy is set by default so that requests to `/*` go to the frontend and `/api/*` to the backend. If you want to have the API on different addresses, you need to change the `Caddyfile` file in the `apps/caddy` directory.
+### Krok 2: Instalace závislostí
 
-What `tourdeapp.yaml` can contain is described in [How to deploy an app to Tour de Cloud](https://tourdeapp.com/study-materials/how-to-deploy).
+Nainstalujte závislosti pro obě části aplikace:
 
-Applications are uploaded to Tour de Cloud via [GitHub action](https://github.com/Student-Cyber-Games/upload-app?tab=readme-ov-file). For uploading, you need to set **TDC_TOKEN**:
-- Settings -> (Security) Secrets and variables -> Actions -> New repository secret.
-- Name: `TDC_TOKEN` Secret: [your secret generated in [tourde.cloud](https://tourde.cloud/)]
+1. **Backend závislosti**:
+   ```bash
+   cd apps/server
+   npm install
+   ```
 
+2. **Frontend závislosti**:
+   ```bash
+   cd ../web
+   npm install
+   ```
 
-### Prerequisites
+### Krok 3: Spuštění MySQL databáze
 
-#### Windows
+Databázi spustíte pomocí Docker kontejneru:
 
-- Installed [WSL2 (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install)
-- Installed and running [Docker](https://www.docker.com/)
-- Installed [Node.js](https://nodejs.org/en/download/)
-- Installed [npm](https://www.npmjs.com/get-npm) (usually included with Node.js)
+```bash
+cd apps/server
+npm run db
+```
 
-#### Linux / MacOS
+Databáze poběží na portu **3306**. Počkejte několik sekund, než se databáze plně inicializuje (obvykle 10-20 sekund).
 
-- Installed and running [Docker](https://www.docker.com/)
-- Installed [Node.js](https://nodejs.org/en/download/)
-- Installed [npm](https://www.npmjs.com/get-npm) (usually included with Node.js)
+> [!WARNING]
+> Databáze není perzistentní, data se z ní po vypnutí Docker kontejneru ztratí.
 
-## Submission
+> [!TIP]
+> Pokud potřebujete databázi zastavit, použijte příkaz `docker ps` pro zobrazení běžících kontejnerů a `docker stop <container-id>` pro zastavení kontejneru s databází.
 
-How to submit your application can be found in our [How to deploy an app to Tour de Cloud](https://tourdeapp.com/study-materials/how-to-deploy)
+### Krok 4: Spuštění backend serveru
 
----
+V novém terminálu spusťte backend:
 
-# Tour de App - Vue + Express Boilerplate
+```bash
+cd apps/server
+npm run dev
+```
 
-**Česká verze / Czech Version**
+Backend poběží na [http://localhost:3000](http://localhost:3000). Měli byste vidět zprávu, že server běží a je připojen k databázi.
 
-Šablona pro vývoj aplikace v soutěži Tour de App společně s frontendovou částí ve frameworku [Vue](https://vuejs.org/) a backendovou částí v [Express](https://expressjs.com/).
+### Krok 5: Spuštění frontend aplikace
 
-## Prvotní nastavení
+V dalším terminálu spusťte frontend:
 
-V složkách pro frontend a backend jsou `.env.example` soubory, které je potřeba přejmenovat na `.env` a upravit hodnoty dle potřeby.
+```bash
+cd apps/web
+npm run dev
+```
 
-Pro produkční vývoj je potřeba nastavit `VITE_API_URL` na URL API serveru v souboru `tourdeapp.yaml` na URL, kterou najdete na hlavní stránce Vašeho projektu na [tourde.cloud](https://tourde.cloud/).
+Frontend poběží na [http://localhost:3001](http://localhost:3001). Otevřete tuto adresu v prohlížeči.
 
-> [!WARNING]
-> Pokud chcete měnit heslo od databáze, je potřeba ho změnit v souboru `tourdeapp.yaml`, `apps/server/.env` a pro lokální vývoj v souboru `apps/server/package.json`.
+### Ověření, že vše funguje
 
-## Lokální vývoj
+1. **Frontend**: Otevřete [http://localhost:3001](http://localhost:3001) - měla by se zobrazit vaše aplikace
+2. **Backend API**: Otevřete [http://localhost:3000/api](http://localhost:3000/api) - měli byste vidět odpověď z API
+3. **Databáze**: Můžete se připojit pomocí MySQL klienta na `localhost:3306` s uživatelským jménem `root` a heslem `password`
 
-Pro lokální vývoj je potřeba pustit:
-- **frontend** (`apps/web`), pomocí `npm run dev` (ve správném adresáři - `apps/web`), pustí se na [http://localhost:3001](http://localhost:3001)
-- **backend** (`apps/server`), pomocí `npm run dev` (ve správném adresáři - `apps/server`), pustí se na [http://localhost:3000](http://localhost:3000)
-- **MySQL** databázi, která je definována v `docker-compose.yaml`, pomocí `npm run db` (v adresáři `apps/server`), databáze poběží na portu 3306
+### Řešení problémů
 
-> [!WARNING]
-> Databáze není perzistentní, data se z ní po vypnutí Docker kontejneru ztratí.
+- **Port již používán**: Pokud některý z portů (3000, 3001, 3306) je již používán, ukončete proces, který ho používá, nebo změňte port v konfiguračních souborech
+- **Databáze se nespustí**: Zkontrolujte, zda máte nainstalovaný a spuštěný Docker
+- **Backend se nemůže připojit k databázi**: Počkejte, až se databáze plně inicializuje (obvykle trvá 10-20 sekund po spuštění)
+- **Node.js není nainstalován**: Nainstalujte Node.js z [nodejs.org](https://nodejs.org/) nebo použijte správce verzí jako `nvm` (Linux/MacOS: `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash`, Windows: stáhněte z [nvm-windows](https://github.com/coreybutler/nvm-windows))
 
 ## Produkční setup (jak se to spouští na našich serverech?)
 
-Jak se aplikace spustí na [tourde.cloud](https://tourde.cloud/) je definováno v souboru `tourdeapp.yaml` v kořenovém adresáři tohoto repozitáře. V tomto boilerplate jsou předpřipravené služby:
+Jak se aplikace spustí na [tourde.cloud](https://tourde.cloud/) je definováno v souboru `tourdeapp.yaml` v kořenovém adresáři tohoto repozitáře. V tomto boiler plate jsou předpřipravené služby:
 ```
-- caddy (reverse proxy pro frontend a backend) - stará se o to, aby dotazy na Vaší aplikaci byly směrovány na správné místo (tj. /* na frontend a /api/* na backend)
+- caddy (reverse proxy pro frontend a backend) - stará se o to aby dotazy na Vaší aplikaci byly směrovány na správné místo (tj. /* na frontend a /api/* na backend)
 - web (frontend aplikace)
 - server (backend aplikace)
 - mysql (MySQL databáze)
@@ -106,11 +113,11 @@ Jak se aplikace spustí na [tourde.cloud](https://tourde.cloud/) je definováno
 > Databáze není perzistentní, data se z ní po nahrání nové verze aplikace ztratí.
 
 > [!NOTE]
-> Reverse proxy je defaultně nastaven tak, že dotazy na `/*` jdou na frontend a `/api/*` na backend. Pokud byste chtěli API mít na jiných adresách, je nutné změnit soubor `Caddyfile` v adresáři `apps/caddy`.
+> Reverse proxy je defaultně nastaven tak, že dotazy na `/*` jdou na frontend a `/api/*` pokud by jste chtěli api mít na jiné adresy je nutné změnit soubor `Caddyfile` v adresáři `apps/caddy`.
 
-Co může `tourdeapp.yaml` obsahovat je napsáno v [Jak nasadit aplikaci na Tour de Cloud](https://tourdeapp.cz/vzdelavaci-materialy/jak-deploy).
+Co může `tourdeapp.yaml` obsahovat je napsáno v [kde??]().
 
-Do Tour de Cloud se aplikace nahrávají přes [GitHub action](https://github.com/Student-Cyber-Games/upload-app?tab=readme-ov-file). Pro nahrání je potřeba zadat **TDC_TOKEN**:
+Do Tour de Cloud se aplikace nahrávají přes [GitHub action](https://github.com/Student-Cyber-Games/upload-app?tab=readme-ov-file), pro nahrání je potřeba zadat **TDC_TOKEN**:
 - Settings -> (Security) Secrets and variables -> Actions -> New repository secret.
 - Name: `TDC_TOKEN` Secret: [váš secret vygenerovaný v [tourde.cloud](https://tourde.cloud/)]
 
@@ -132,4 +139,5 @@ Do Tour de Cloud se aplikace nahrávají přes [GitHub action](https://github.co
 
 ## Odevzdání
 
-Jak odevzdat svoji aplikaci můžete najít v našich [Jak nasadit aplikaci na Tour de Cloud](https://tourdeapp.cz/vzdelavaci-materialy/jak-deploy)
+Jak odevzdat svojí aplikaci můžete najít v našich [kde??]()
+