From 16f693fff01a658e70636f82b753a012b86c4213 Mon Sep 17 00:00:00 2001
From: minie4 <minie4@gmx.de>
Date: Sat, 3 Jun 2023 14:51:09 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Improve=20documentation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md          | 69 ++++++++++++++++++++++++++++++++++++++++++----
 server/.env.sample | 17 ++++++++++++
 2 files changed, 80 insertions(+), 6 deletions(-)
 create mode 100644 server/.env.sample

diff --git a/README.md b/README.md
index f141f01..ef2b9f5 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,82 @@
 # Timetable V2
 
-## Project Setup
+<div align="center">
+<img src="public/favicon.svg" width="100" height="100">
+</div>
+
+Timetable V2 is a **substitution plan and timetable viewer** that is meant to be a placement for the HTML files that my school provides via [~~DSB Mobile~~](https://dsbmobile.de/) [BOLLE](https://bolle-software.de/).
+
+This Project fetches the latest substitution plan files from the specified source and parses them, which converts the HTML files exported by [Untis](https://www.untis.at/) to a JSON format. The Programm then compares the new substitution plan to the previous one and finds changed, deleted and newly added substitutions and adds them to the database.
+
+The substitutions in the database and their history can then be viewed in the web browser, where they are also being filtered by class and linked with the students timetable.
+
+## Setup with Docker
+
+To setup Timetable V2 in a docker container, you firstly have to build the docker image:
+
+```sh
+docker-compose build
+```
+
+Next you will need to set your environment variables. For that rename `.env.sample` in the server directory to `.env` and change the variables as described in the file.
+
+Then you can run the app
+
+```sh
+docker-compose up -d
+```
+
+And check its logs
+
+```sh
+docker-compose logs -f
+```
+
+If everything is working, you should be able to connect to the app at http://localhost:3000 (or the IP address of your docker host)
+
+## Setup for Development
+
+To setup a development environment for Timetable V2, you will need to have NodeJS and Docker installed. (If you don't want to install Docker, you can also install PostgreSQL natively on your computer)
+
+### Build the frontend
+
+To build the Vue.js based frontend, you will need to be in the root folder of the project and run
 
 ```sh
 npm install
+npm run build
 ```
 
-### Compile and Hot-Reload for Development
+Or if you want to work on the frontend you can run
 
 ```sh
 npm run dev
 ```
 
-### Compile and Minify for Production
+This creates a development server with live reload on port 3001. This also proxies all API routes to the backend running on port 3000.
+
+### Run the backend
+
+First you will need to install a PostgreSQL instance. This can be simply done by launching a PostgreSQL docker container:
 
 ```sh
-npm run build
+docker run --name timetable-postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres
+
 ```
 
-### Lint with [ESLint](https://eslint.org/)
+The backend can be found at `./server`, so all upcomming commands need to be run in that directory.
+
+For the app to be able to fetch substitution plan files, you need to create a `.env` file (you can use the `.env.sample` as a template) and set the values correctly. You don't need to change the database url used in `.env.sample` for development.
+
+To apply the database schema to the newly created database, you need to run:
 
 ```sh
-npm run lint
+npx prisma db push
+```
+
+Now you just need to install the dependencies and are ready to run the app:
+
+```sh
+npm install
+node index.js
 ```
diff --git a/server/.env.sample b/server/.env.sample
new file mode 100644
index 0000000..bd3bd1a
--- /dev/null
+++ b/server/.env.sample
@@ -0,0 +1,17 @@
+# For production, the database credentials should be changed
+# here and in the docker-compose file for the postgres container, 
+# but they will work for testing or development
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres?schema=public
+
+# These credentials are required for fetching substitution plan
+# files from BOLLE. More information on how to get them can be found
+# in the BOLLE parser (./server/parser/bolle.js)
+# (If you are using a different file provider than bolle, you can
+# remove these and add the ones required by your file provider)
+BOLLE_URL=
+BOLLE_USER=
+BOLLE_KEY=
+
+# This password is required for logging into your timetable v2
+# instance. You can leave it empty to disable authentication.
+AUTH_PASSWORD=
\ No newline at end of file