ICS-WebUntis

ICS-WebUntis is a lightweight service that exports timetables from WebUntis as .ics calendar feeds.
It is designed for reliability, minimal resource usage, and straightforward deployment via Docker.

Features

• Fetch timetables directly from WebUntis
• Expose an .ics calendar endpoint for integration with any calendar client
• Built-in caching to reduce load on WebUntis
• Single-container deployment with Docker
• Strictly validated configuration
• Multiple Users supported
• Fetch timetables for specific classes, rooms, teachers, or subjects by name or numeric ID

Quick Start

Run with Docker Compose

version: "3.3"

services:
    webuntis-timetable:
        image: nlion/ics-webuntis:latest
        container_name: webuntis-timetable
        environment:
            - NODE_ENV=production
            - PORT=7464
            - CONFIG_FILE=/app/config.json
        volumes:
            - ./dev-config.json:/app/config.json:ro
        ports:
            - "7464:7464"
        restart: unless-stopped

Start it with 'docker-compose up'

This will fail without a 'config.json'

Configuration

The service requires a JSON configuration file. config.json example

{
    "daysBefore": 7,
    "daysAfter": 14,
    "cacheDuration": 300,
    "users": [
        {
        "school": "myschool",
        "username": "student1",
        "password": "secret",
        "baseurl": "https://mese.webuntis.com/",
        "friendlyName": "student1"
        }
    ]
}

Usage

Personal timetable

http://<host>:7464/timetable/friendlyName.ics

<friendlyName> is the one specified in the user configuration Returns the personal timetable as an .ics feed

Specific element timetable (class, room, teacher, subject)

<type>: "class", "room", "teacher", or "subject" <id> Either the numeric ID or the name of the element (the service will resolve the name automatically)

Example URLs:

http://localhost:7464/timetable/user/class/10.3 http://localhost:7464/timetable/user/room/24 http://localhost:7464/timetable/user/teacher/MrSmith

If the ID cannot be resolved, the service will attempt to use it as a numeric ID.

Contributing

Feel free to contribute at any time! If so either create an issue to discuss your changes first or just open a Pull Request if you prefer.

Development Setup

1. Clone the repository:

git clone https://github.com/NLion74/ics-webuntis
cd ics-webuntis

2. Install dependencies:

npm install

1. Run the project locally:

npm run dev