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..71ad00b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # 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. ## Use case @@ -8,24 +10,55 @@ Some schools, universities, or workspaces do not enable the iCalendar API that U ## 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. |