From c7faa060fad7d9115bd31abb557f3c8f0555e8c1 Mon Sep 17 00:00:00 2001
From: Adrian Groh <adrian.groh@t-online.de>
Date: Thu, 26 Jun 2025 19:40:37 +0200
Subject: [PATCH] Add README

---
 README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..315ded8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,49 @@
+# Ausweisstatus
+
+A small application to check the status of IDs like _Personalausweis_ and _Reisepass_ on https://ausweisstatus.regioit.de/aachen automatically and send notifications on changes.
+
+Tested with the status page for Aachen but _should_ work for other cities using _regioit.de_
+
+## Why?
+I wanted to know when my _Personalausweis_ was ready for collection without manually checking the page periodically.
+
+## Usage
+
+### With Docker
+A `Dockerfile` is provided containing everything necessary to send notifications on status changes.
+
+Before building the Docker image, adjust the `WEBHOOK_URL` (see [here](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) for creation instructions), _Passauswahl_ (_P_, _R_, or _ID_, see below), _Seriennummer_ and _Geburtsdatum_ in the `crontab` file.
+
+Then, build and start the container with `docker compose up -d --build` on a machine with high availability.
+You will now be notified when the status of your document is changed.
+
+### Without Docker
+First, install the dependencies, I recommend using [`uv`](https://docs.astral.sh/uv/):
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -r requirements.txt
+```
+The provided script `ausweisstatus.py` can be used to retrieve the current status of your document.
+
+```
+./ausweisstatus.py <P|R|ID> <Seriennummer> <Geburtsdatum>
+```
+
+- _P_ for _Personalausweis_
+- _R_ for _Reisepass_
+- _ID_ for eID-Karte
+
+Example:
+```bash
+$ ./ausweisstatus.py P L712345678 01.01.1970
+bei Bundesdruckerei erfasst
+```
+
+To automatically receive notifications on status changes, you can periodically run the `notify.sh` script (requires _curl_) with the same arguments and a `WEBHOOK_URL` env var containing a Discord webhook URL.
+You can modify the `notify()` function in it to use other notification services.
+
+To run the script periodically, you can use [_systemd/Timers_](https://wiki.archlinux.org/title/Systemd/Timers) or [_cron_](https://wiki.archlinux.org/title/Cron).
+
+## Note for other Cities
+The URL https://ausweisstatus.regioit.de/aachen is hard-coded in `ausweisstatus.py`, make sure to change it.
\ No newline at end of file