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 +
+ +
+ +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