Skip to content

Commit eb1491a

Browse files
tomaskebrletomaskebrle
authored
Merge pull request #2 from Student-Cyber-Games/update-readme-instructions
Update README instructions
2 parents 0190f45 + aabb7aa commit eb1491a

1 file changed

Lines changed: 149 additions & 17 deletions

File tree

‎README.md‎

Lines changed: 149 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,151 @@
1-
# Tour de App - Vue + Express boiler plate
1+
# Tour de App - Vue + Express Boilerplate
2+
3+
> **Note:** Czech version is available below / Česká verze je k dispozici níže
4+
5+
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/).
6+
7+
## Initial Setup
8+
9+
In the backend directory, there is a `.env.example` file that needs to be renamed to `.env` and the values adjusted as needed.
10+
11+
> [!WARNING]
12+
> 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.
13+
14+
## Local Development
15+
16+
For local development, you need to run three services: the database, backend, and frontend. Below you'll find detailed step-by-step instructions.
17+
18+
### Step 1: Setting up environment variables
19+
20+
First, you need to set up environment variables:
21+
22+
1. **Backend**: In the `apps/server` directory, rename the `.env.example` file to `.env`:
23+
```bash
24+
cd apps/server
25+
cp .env.example .env
26+
```
27+
28+
### Step 2: Installing dependencies
29+
30+
Install dependencies for both parts of the application:
31+
32+
1. **Backend dependencies**:
33+
```bash
34+
cd apps/server
35+
npm install
36+
```
37+
38+
2. **Frontend dependencies**:
39+
```bash
40+
cd ../web
41+
npm install
42+
```
43+
44+
### Step 3: Starting the MySQL database
45+
46+
Start the database using a Docker container:
47+
48+
```bash
49+
cd apps/server
50+
npm run db
51+
```
52+
53+
The database will run on port **3306**. Wait a few seconds for the database to fully initialize (usually 10-20 seconds).
54+
55+
> [!WARNING]
56+
> The database is not persistent, data will be lost after shutting down the Docker container.
57+
58+
> [!TIP]
59+
> If you need to stop the database, use `docker ps` to view running containers and `docker stop <container-id>` to stop the database container.
60+
61+
### Step 4: Starting the backend server
62+
63+
In a new terminal, start the backend:
64+
65+
```bash
66+
cd apps/server
67+
npm run dev
68+
```
69+
70+
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.
71+
72+
### Step 5: Starting the frontend application
73+
74+
In another terminal, start the frontend:
75+
76+
```bash
77+
cd apps/web
78+
npm run dev
79+
```
80+
81+
The frontend will run on [http://localhost:3001](http://localhost:3001). Open this address in your browser.
82+
83+
### Verifying everything works
84+
85+
1. **Frontend**: Open [http://localhost:3001](http://localhost:3001) - your application should be displayed
86+
2. **Backend API**: Open [http://localhost:3000/api](http://localhost:3000/api) - you should see a response from the API
87+
3. **Database**: You can connect using a MySQL client to `localhost:3306` with username `root` and password `password`
88+
89+
### Troubleshooting
90+
91+
- **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
92+
- **Database won't start**: Check that you have Docker installed and running
93+
- **Backend can't connect to database**: Wait for the database to fully initialize (usually takes 10-20 seconds after starting)
94+
- **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))
95+
96+
## Production Setup (how does it run on our servers?)
97+
98+
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:
99+
```
100+
- 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)
101+
- web (frontend application)
102+
- server (backend application)
103+
- mysql (MySQL database)
104+
```
105+
106+
> [!WARNING]
107+
> The database is not persistent, data will be lost after uploading a new version of the application.
108+
109+
> [!NOTE]
110+
> 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.
111+
112+
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).
113+
114+
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**:
115+
- Settings -> (Security) Secrets and variables -> Actions -> New repository secret.
116+
- Name: `TDC_TOKEN` Secret: [your secret generated in [tourde.cloud](https://tourde.cloud/)]
117+
118+
119+
### Prerequisites
120+
121+
#### Windows
122+
123+
- Installed [WSL2 (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install)
124+
- Installed and running [Docker](https://www.docker.com/)
125+
- Installed [Node.js](https://nodejs.org/en/download/)
126+
- Installed [npm](https://www.npmjs.com/get-npm) (usually included with Node.js)
127+
128+
#### Linux / MacOS
129+
130+
- Installed and running [Docker](https://www.docker.com/)
131+
- Installed [Node.js](https://nodejs.org/en/download/)
132+
- Installed [npm](https://www.npmjs.com/get-npm) (usually included with Node.js)
133+
134+
## Submission
135+
136+
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)
137+
138+
---
139+
140+
# Tour de App - Vue + Express Boilerplate
141+
142+
**Česká verze / Czech Version**
2143

3144
Š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/).
4145

5146
## Prvotní nastavení
6147

7-
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.
8-
9-
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/).
148+
V složce pro backend je `.env.example` soubor, který je potřeba přejmenovat na `.env` a upravit hodnoty dle potřeby.
10149

11150
> [!WARNING]
12151
> 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`.
@@ -25,12 +164,6 @@ Nejprve je potřeba nastavit environmentální proměnné:
25164
cp .env.example .env
26165
```
27166

28-
2. **Frontend**: V adresáři `apps/web` přejmenujte soubor `.env.example` na `.env`:
29-
```bash
30-
cd ../web
31-
cp .env.example .env
32-
```
33-
34167
### Krok 2: Instalace závislostí
35168

36169
Nainstalujte závislosti pro obě části aplikace:
@@ -101,9 +234,9 @@ Frontend poběží na [http://localhost:3001](http://localhost:3001). Otevřete
101234

102235
## Produkční setup (jak se to spouští na našich serverech?)
103236

104-
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:
237+
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:
105238
```
106-
- 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)
239+
- 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)
107240
- web (frontend aplikace)
108241
- server (backend aplikace)
109242
- mysql (MySQL databáze)
@@ -113,11 +246,11 @@ Jak se aplikace spustí na [tourde.cloud](https://tourde.cloud/) je definováno
113246
> Databáze není perzistentní, data se z ní po nahrání nové verze aplikace ztratí.
114247
115248
> [!NOTE]
116-
> 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`.
249+
> 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`.
117250
118-
Co může `tourdeapp.yaml` obsahovat je napsáno v [kde??]().
251+
Co může `tourdeapp.yaml` obsahovat je napsáno v [Jak nasadit aplikaci na Tour de Cloud](https://tourdeapp.cz/vzdelavaci-materialy/jak-deploy).
119252

120-
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**:
253+
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**:
121254
- Settings -> (Security) Secrets and variables -> Actions -> New repository secret.
122255
- Name: `TDC_TOKEN` Secret: [váš secret vygenerovaný v [tourde.cloud](https://tourde.cloud/)]
123256

@@ -139,5 +272,4 @@ Do Tour de Cloud se aplikace nahrávají přes [GitHub action](https://github.co
139272

140273
## Odevzdání
141274

142-
Jak odevzdat svojí aplikaci můžete najít v našich [kde??]()
143-
275+
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)

0 commit comments

Comments
 (0)