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

docs: Add detailed run instructions to README

Author: tomaskebrle

README.md

@@ -6,23 +6,93 @@ A template for developing applications for the Tour de App competition with a fr
 
 ## Initial Setup
 
-In the frontend and backend directories, there are `.env.example` files that need to be renamed to `.env` and the values adjusted as needed.
-
-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/).
+In the backend directory, there is a `.env.example` file that needs to be renamed to `.env` and the values adjusted as needed.
 
 > [!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.
 
 ## Local Development
 
-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
+For local development, you need to run three services: the database, backend, and frontend. Below you'll find detailed step-by-step instructions.
+
+### Step 1: Setting up environment variables
+
+First, you need to set up environment variables:
+
+1. **Backend**: In the `apps/server` directory, rename the `.env.example` file to `.env`:
+   ```bash
+   cd apps/server
+   cp .env.example .env
+   ```
+
+### Step 2: Installing dependencies
+
+Install dependencies for both parts of the application:
+
+1. **Backend dependencies**:
+   ```bash
+   cd apps/server
+   npm install
+   ```
+
+2. **Frontend dependencies**:
+   ```bash
+   cd ../web
+   npm install
+   ```
+
+### Step 3: Starting the MySQL database
+
+Start the database using a Docker container:
+
+```bash
+cd apps/server
+npm run db
+```
+
+The database will run on port **3306**. Wait a few seconds for the database to fully initialize (usually 10-20 seconds).
 
 > [!WARNING]
 > The database is not persistent, data will be lost after shutting down the Docker container.
 
+> [!TIP]
+> If you need to stop the database, use `docker ps` to view running containers and `docker stop <container-id>` to stop the database container.
+
+### Step 4: Starting the backend server
+
+In a new terminal, start the backend:
+
+```bash
+cd apps/server
+npm run dev
+```
+
+The backend will run on [http://localhost:3000](http://localhost:3000). You should see a message that the server is running and connected to the database.
+
+### Step 5: Starting the frontend application
+
+In another terminal, start the frontend:
+
+```bash
+cd apps/web
+npm run dev
+```
+
+The frontend will run on [http://localhost:3001](http://localhost:3001). Open this address in your browser.
+
+### Verifying everything works
+
+1. **Frontend**: Open [http://localhost:3001](http://localhost:3001) - your application should be displayed
+2. **Backend API**: Open [http://localhost:3000/api](http://localhost:3000/api) - you should see a response from the API
+3. **Database**: You can connect using a MySQL client to `localhost:3306` with username `root` and password `password`
+
+### Troubleshooting
+
+- **Port already in use**: If any of the ports (3000, 3001, 3306) are already in use, terminate the process using it or change the port in the configuration files
+- **Database won't start**: Check that you have Docker installed and running
+- **Backend can't connect to database**: Wait for the database to fully initialize (usually takes 10-20 seconds after starting)
+- **Node.js is not installed**: Install Node.js from [nodejs.org](https://nodejs.org/) or use a version manager like `nvm` (Linux/MacOS: `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash`, Windows: download from [nvm-windows](https://github.com/coreybutler/nvm-windows))
+
 ## Production Setup (how does it run on our servers?)
 
 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:
@@ -75,23 +145,93 @@ How to submit your application can be found in our [How to deploy an app to Tour
 
 ## Prvotní nastavení
 
-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.
-
-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/).
+V složce pro backend je `.env.example` soubor, který je potřeba přejmenovat na `.env` a upravit hodnoty dle potřeby.
 
 > [!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`.
 
 ## Lokální vývoj
 
-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
+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.
+
+### Krok 1: Nastavení environmentálních proměnných
+
+Nejprve je potřeba nastavit environmentální proměnné:
+
+1. **Backend**: V adresáři `apps/server` přejmenujte soubor `.env.example` na `.env`:
+   ```bash
+   cd apps/server
+   cp .env.example .env
+   ```
+
+### Krok 2: Instalace závislostí
+
+Nainstalujte závislosti pro obě části aplikace:
+
+1. **Backend závislosti**:
+   ```bash
+   cd apps/server
+   npm install
+   ```
+
+2. **Frontend závislosti**:
+   ```bash
+   cd ../web
+   npm install
+   ```
+
+### Krok 3: Spuštění MySQL databáze
+
+Databázi spustíte pomocí Docker kontejneru:
+
+```bash
+cd apps/server
+npm run db
+```
+
+Databáze poběží na portu **3306**. Počkejte několik sekund, než se databáze plně inicializuje (obvykle 10-20 sekund).
 
 > [!WARNING]
 > Databáze není perzistentní, data se z ní po vypnutí Docker kontejneru ztratí.
 
+> [!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í.
+
+### Krok 4: Spuštění backend serveru
+
+V novém terminálu spusťte backend:
+
+```bash
+cd apps/server
+npm run dev
+```
+
+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.
+
+### Krok 5: Spuštění frontend aplikace
+
+V dalším terminálu spusťte frontend:
+
+```bash
+cd apps/web
+npm run dev
+```
+
+Frontend poběží na [http://localhost:3001](http://localhost:3001). Otevřete tuto adresu v prohlížeči.
+
+### Ověření, že vše funguje
+
+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`
+
+### Řešení problémů
+
+- **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: