Initial commit: kantine2ical CLI, Flask-Server, Docker

README.md

@@ -0,0 +1,98 @@
+# Kantine BHZ Kiel-Wik – Speiseplan zu iCal
+
+Liest die PDF-Speisepläne von [kantine-bhz.de](http://kantine-bhz.de) aus und erzeugt eine iCal-Datei (`.ics`) für den Import in Google Kalender. Jeder Termin enthält alle Tagesgerichte (I. bis V.) und ist auf 12:00 Uhr mittags gesetzt.
+
+## Voraussetzungen
+
+- Python 3.9+ (für `zoneinfo`)
+- Bestehendes venv unter `.venv`
+
+## Installation
+
+1. Virtuelle Umgebung aktivieren:
+
+   **Windows (PowerShell):**
+   ```powershell
+   .venv\Scripts\Activate.ps1
+   ```
+
+   **Windows (CMD):**
+   ```cmd
+   .venv\Scripts\activate.bat
+   ```
+
+2. Abhängigkeiten installieren:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+## Nutzung
+
+```bash
+python kantine2ical.py
+```
+
+Erzeugt standardmäßig die Datei `kantine_speiseplan.ics` im aktuellen Verzeichnis.
+
+**Optionen:**
+
+- `-o DATEI` / `--output DATEI` – Ausgabedatei (Standard: `kantine_speiseplan.ics`)
+- `--url URL` – Basis-URL der Kantine (Standard: `http://kantine-bhz.de`)
+
+Beispiel:
+```bash
+python kantine2ical.py -o mein_speiseplan.ics
+```
+
+## Google Kalender Import
+
+1. [Google Kalender](https://calendar.google.com) öffnen
+2. Neben „Meine Kalender“ auf das Drei-Punkte-Menü klicken → **Import**
+3. Die erzeugte `.ics`-Datei auswählen und dem gewünschten Kalender zuordnen
+
+Die Termine erscheinen mit der Zeitzone Europe/Berlin um 12:00 Uhr mit allen fünf Tagesgerichten in der Beschreibung.
+
+---
+
+## Server-Modus (abonnierbare URL)
+
+Der Speiseplan kann als **externer Kalender** per URL angeboten werden. Ein Flask-Server liefert die iCal-Daten; Google Kalender und andere Clients können die URL direkt abonnieren. Im Hintergrund wird täglich nach neuen Speiseplan-PDFs gesucht und der Kalender aktualisiert.
+
+**Voraussetzung:** Für „Von URL hinzufügen“ in Google Kalender muss die Server-URL von außen erreichbar sein (öffentliche IP, Reverse-Proxy oder z. B. ngrok für Tests).
+
+1. Abhängigkeiten installieren (inkl. Flask): `pip install -r requirements.txt`
+2. Server starten:
+   ```bash
+   python app.py
+   ```
+   Oder mit Flask-CLI: `flask --app app run --host 0.0.0.0 --port 5000`
+3. Abo-URL für Google Kalender: `http://<host>:5000/calendar.ics` (bzw. Port 5000 durch Ihren Host/Port ersetzen).
+4. In Google Kalender: „Andere Kalender hinzufügen“ → „Von URL“ → obige URL eintragen.
+
+**Konfiguration (optional, Umgebungsvariablen):**
+
+- `KANTINE_BASE_URL` – Basis-URL der Kantine (Standard: `http://kantine-bhz.de`)
+- `REFRESH_INTERVAL_SECONDS` – Sekunden zwischen Aktualisierungen (Standard: 86400 = 24 h)
+
+---
+
+## Docker (Production)
+
+Für den Betrieb als Container (z. B. auf einem Server):
+
+**Build und Run:**
+```bash
+docker build -t kantine2ical .
+docker run -p 8000:8000 kantine2ical
+```
+
+Abo-URL: `http://<host>:8000/calendar.ics`
+
+**Mit Docker Compose:**
+```bash
+docker compose up -d
+```
+
+Der Container läuft auf Port 8000 und startet bei Bedarf neu (`restart: unless-stopped`).
+
+**Hinweis:** Für den Einsatz in Production wird ein **Reverse-Proxy mit HTTPS** (z. B. Traefik, Caddy oder nginx) vor dem Container empfohlen, damit Google die Kalender-URL zuverlässig abrufen kann.