Untis Notify

This project has two parts:

• A Bun background service that checks WebUntis and sends Firebase Cloud Messaging messages.
• A small Android APK named untis-notify with application ID foo.alois.untisnotify that subscribes to FCM and shows notifications.

The default FCM topic is untis-cancellations. Keep this value the same on the server and in the Android app unless you rebuild both sides.

Firebase Project

1. Open the Firebase Console.
2. Create a project or select an existing project.
3. Add an Android app.
4. Use this Android package name:

foo.alois.untisnotify

5. Download google-services.json.
6. Put it here:

android/app/google-services.json

7. In Firebase Console, go to Project settings, Service accounts.
8. Generate a new private key JSON file for Firebase Admin SDK.
9. Store that JSON file somewhere readable by the server service, but do not commit it.

Server Environment

Create an environment file for the background service, for example /var/lib/untis-notify/env:

GOOGLE_APPLICATION_CREDENTIALS=/var/lib/untis-notify/firebase-service-account.json
FCM_TOPIC=untis-cancellations
POLL_INTERVAL_SECONDS=60
WEBUNTIS_KEY=your-untis-qr-key
WEBUNTIS_USER=your-untis-user
WEBUNTIS_URL=albert-einstein-gym.webuntis.com
WEBUNTIS_SCHOOL=albert-einstein-gym
WEBUNTIS_SCHOOL_NUMBER=2313700

Alternatively, instead of GOOGLE_APPLICATION_CREDENTIALS, you can provide the full service account JSON as one environment variable:

FIREBASE_SERVICE_ACCOUNT_JSON={"type":"service_account",...}

GOOGLE_APPLICATION_CREDENTIALS is recommended because it keeps the JSON out of systemd environment output.

The WebUntis values come from the QR login data. Bun loads .env files automatically when running the service manually from the project directory.

Android APK

Build the APK:

nix develop
cp /path/to/google-services.json android/app/google-services.json
cd android
gradle assembleDebug

Install it on the phone:

adb install -r app/build/outputs/apk/debug/app-debug.apk

The Nix dev shell provides Bun, JDK 17, Gradle, adb, and the Android SDK components required by this project. Gradle must not auto-install SDK components into the Nix store because the SDK path is read-only.

Open untis-notify once after installing it.

On Android 13 or newer, Android will ask for notification permission. Allow it. The app subscribes to the untis-cancellations FCM topic and then closes itself.

After setup:

• The current cancelled lessons notification uses a low-importance silent notification channel.
• New cancelled lessons use a normal notification channel.
• You can change notification channel behavior in Android system notification settings.

Bun Service

Install dependencies:

bun install

Run manually:

GOOGLE_APPLICATION_CREDENTIALS=/path/to/firebase-service-account.json bun index.ts

The service checks the current week and the next week, writes data-YYYY-MM-DD.json, deletes reports older than two days, and sends FCM updates.

NixOS Module

Example flake input:

{
  inputs.untis-notify.url = "path:/path/to/untis-notify";

  outputs = { nixpkgs, untis-notify, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        untis-notify.nixosModules.default
        {
          services.untis-notify = {
            enable = true;
            credentialsFile = "/var/lib/untis-notify/firebase-service-account.json";
            environmentFile = "/var/lib/untis-notify/env";
            workingDirectory = "/var/lib/untis-notify";
          };
        }
      ];
    };
  };
}

Prepare the state directory and credentials:

sudo mkdir -p /var/lib/untis-notify
sudo cp firebase-service-account.json /var/lib/untis-notify/firebase-service-account.json

The NixOS module defaults to FCM_TOPIC=untis-cancellations and POLL_INTERVAL_SECONDS=60. Put the WEBUNTIS_* values in the configured environmentFile.

Then rebuild NixOS and start the service:

sudo nixos-rebuild switch
sudo systemctl status untis-notify.service