diff --git a/.github/assets/banner.jpg b/.github/assets/banner.jpg new file mode 100644 index 0000000..492a0ee Binary files /dev/null and b/.github/assets/banner.jpg differ diff --git a/README.md b/README.md index 53aca94..8fd893d 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,67 @@ # untis-ics-sync +[![Node CI](https://github.com/bddvlpr/untis-ics-sync/actions/workflows/node-ci.yaml/badge.svg)](https://github.com/bddvlpr/untis-ics-sync/actions/workflows/node-ci.yaml) [![Docker CD](https://github.com/bddvlpr/untis-ics-sync/actions/workflows/docker-cd.yaml/badge.svg)](https://github.com/bddvlpr/untis-ics-sync/actions/workflows/docker-cd.yaml) + Serves a calendar API (ICS) for events provided from Untis. +![Banner](.github/assets/banner.jpg) + + ## Use case Some schools, universities, or workspaces do not enable the iCalendar API that Untis provides by default. Due to this limitation, I've written my implementation to dynamically sync class schedules to my agenda. ## Installation -Simply clone the repository and cd into it using `git clone https://github.com/bddvlpr/untis-ics-sync && cd untis-ics-sync`. -If you're planning on using Docker, you could use the [bddvlpr/untis-ics-sync](https://hub.docker.com/r/bddvlpr/untis-ics-sync/) image from Docker Hub instead of the git repository. - -### Redis - -Version 0.7.0 and above require a redis server to be supplied in environment variables for queue processing. Either externally provide one, or define one in a Docker compose environment. +### Using Docker -### Setup SSL +To deploy a quick Docker environment, fill in the target school credentials in `docker-compose.yml` and start the service by running `docker compose up -d`. Do note that if you'd like to use SSL, add any reverse proxy such as Nginx, Caddy or Traefik. View the table below for all possible environment variables. -From version 0.2.6 and forward, SSL will not be natively supported anymore. Please use a reverse proxy instead of supplying the docker container with an SSL certificate. +### Using NixOS -### Using Docker +Firstly add this repository to your flake's inputs. +```nix +{ + inputs = { + # ... + untis-ics-sync.url = "github:bddvlpr/untis-ics-sync/"; + untis-ics-sync.inputs.nixpkgs.follows = "nixpkgs"; + }; -To run the app using Docker, copy over the `.env.example` to `.env` and fill in the parameters to get the app to work. -Deploy the app (in a test environment) using `docker run -d --env-list .env -p 3000:3000 bddvlpr/untis-ics-sync`. + # ... +} +``` -### Using Yarn +Secondly, enable the service. Please **DO NOT** use a writeText derivative as this will add your credentials to the Nix store. Use agenix or nix-sops. A local Redis service will automatically be started. +```nix +{ + inputs, + ... +}: { + imports = [ + inputs.untis-ics-sync.nixosModules.default + ]; -To run the app using Yarn, copy over the `.env.example` to `.env` and fill in the parameters to get the app to work. -Hot run the app using `yarn start:dev`, or build it using `yarn build`. + services.untis-ics-sync = { + enable = true; + envFile = ./; # Path to your credentials. + }; +} +``` +## Environment +| Name | Type | Default | Description | +| - | - | - | - | +| UNTIS_SCHOOLNAME | string | `null` | The school's (Untis) service name. | +| UNTIS_USERNAME | string | `null` | The school's user name. | +| UNTIS_PASSWORD | string | `null` | The school's password. | +| UNTIS_BASEURL | string | `null` | The school's (Untis) base-url. | +| BULL_REDIS_HOST | string | `null` | The Redis service hostname or address. | +| BULL_REDIS_PORT | number | `null` | The Redis service port. | +| BULL_REDIS_PATH | string | `null` | The Redis service path for Unix socket connection. | +| CORS_ORIGIN | string | http://localhost:5173 | CORS Origin header to be sent for untis-ics-sync-ui. | +| MAINTENANCE_TITLE | string | `null` | Maintenance notification title. | +| MAINTENANCE_DESCRIPTION | string | `null` | Maintenance notification description. | +| MAINTENANCE_LOCATION | string | `null` | Maintenance notification location. | +| LESSONS_TIMETABLE_BEFORE | number | 7 | The amount of days to fetch before today. | +| LESSONS_TIMETABLE_AFTER | number | 14 | The amount of days to fetch after today. | diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..22ea9ff --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,27 @@ +version: "3.9" + +services: + server: + image: bddvlpr/untis-ics-sync:latest + restart: unless-stopped + environment: + UNTIS_SCHOOLNAME: + UNTIS_USERNAME: + UNTIS_PASSWORD: + UNTIS_BASEURL: + + BULL_REDIS_HOST: redis + BULL_REDIS_PORT: 6379 + ports: + - 3000:3000 + depends_on: + - redis + redis: + image: redis:7 + restart: unless-stopped + command: redis-server + volumes: + - redis-data:/data + +volumes: + redis-data: