stefankoelle/calender_sync
1
0
Fork 0
mirror of https://github.com/skoelle/calender_sync.git synced 2026-09-17 18:20:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

README.md

Browse Source
This commit is contained in:
stefankoelle
2026-08-14 23:43:40 +02:00
parent 0f16aa45dc
commit 3fccf6df67
2 changed files with 86 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.moonweb.yml
+6
View File
@@ -0,0 +1,6 @@
title: "Google Calender Sync"
emoji: "📅"
category: code
subcategory: "Smart Home Apps"
status: active
stack: [Python, FastAPI, Uvicorn, Jinja2]
README.md
+80 -80
View File
@@ -1,32 +1,32 @@
# calender_sync # 📅 calender_sync
Google Calendar (ICS-Feed) → MariaDB Sync fürs Homelab. > Google Calendar (ICS-Feed) → MariaDB Sync fürs Homelab.
Läuft als Docker Container, pollt periodisch einen privaten Google Calendar ICS-Feed, expandiert RRULE/EXDATE/RECURRENCE-ID und schreibt einzelne Instanzen in eine MariaDB-Datenbank. Läuft als Docker Container, pollt periodisch einen privaten Google Calendar ICS-Feed, expandiert RRULE/EXDATE/RECURRENCE-ID und schreibt einzelne Instanzen in eine MariaDB-Datenbank.
## Features ## ✨ Features
- Automatische Synchronisation alle 15 Minuten (konfigurierbar) - 🔄 Automatische Synchronisation alle 15 Minuten (konfigurierbar)
- Expandiert wiederkehrende Events (RRULE) und Serien-Exceptions (EXDATE, RECURRENCE-ID) - 📆 Expandiert wiederkehrende Events (RRULE) und Serien-Exceptions (EXDATE, RECURRENCE-ID)
- Soft-Delete: Entfernte Events werden als `deleted=1` markiert, nicht gelöscht - 🗑️ Soft-Delete: Entfernte Events werden als `deleted=1` markiert, nicht gelöscht
- Optionales Database-Bootstrap: Erstellt DB und User automatisch bei `DB_BOOTSTRAP=true` - 🛠️ Optionales Database-Bootstrap: Erstellt DB und User automatisch bei `DB_BOOTSTRAP=true`
- Zeitfenster-konfiguration für Vergangenheit/Future (standardmäßig -90 Tage / +365 Tage) - ⏰ Zeitfenster-konfiguration für Vergangenheit/Future (standardmäßig -90 Tage / +365 Tage)
- Web-UI zur Anzeige anstehender Termine mit Suchfunktion - 🌐 Web-UI zur Anzeige anstehender Termine mit Suchfunktion
- REST API für programmsprachigen Zugriff auf Kalenderdaten - 🔌 REST API für programmsprachigen Zugriff auf Kalenderdaten
- Optionale tägliche E-Mail-Benachrichtigung um konfigurierte Uhrzeit - 📧 Optionale tägliche E-Mail-Benachrichtigung um konfigurierte Uhrzeit
- Optionale wöchentliche Vorab-Info (z.B. freitags) mit Termine nach Suchbegriffen - 📬 Optionale wöchentliche Vorab-Info (z.B. freitags) mit Termine nach Suchbegriffen
[![UI](docs/screenshot_thumbnail.png)](docs/screenshot.png) [![UI](docs/screenshot_thumbnail.png)](docs/screenshot.png)
## Voraussetzungen ## 📋 Voraussetzungen
- Docker & Docker Compose - 🐳 Docker & Docker Compose
- MariaDB Instanz (z.B. als Proxmox LXC) - 🗃️ MariaDB Instanz (z.B. als Proxmox LXC)
- Google Calendar mit privatem ICS-Feed - 📱 Google Calendar mit privatem ICS-Feed
## Quick Start ## 🚀 Quick Start
1. **MariaDB Setup** 1. **🔧 MariaDB Setup**
Entweder manuell ausführen: Entweder manuell ausführen:
```bash ```bash
@@ -40,7 +40,7 @@ Läuft als Docker Container, pollt periodisch einen privaten Google Calendar ICS
DB_ROOT_PASSWORD=dein_root_passwort DB_ROOT_PASSWORD=dein_root_passwort
``` ```
2. **.env anlegen** 2. **📄 .env anlegen**
```bash ```bash
cp .env.example .env cp .env.example .env
@@ -50,13 +50,13 @@ Läuft als Docker Container, pollt periodisch einen privaten Google Calendar ICS
- `ICS_URL`: Privater ICS-Link aus den Google Calendar Einstellungen - `ICS_URL`: Privater ICS-Link aus den Google Calendar Einstellungen
- `DB_PASSWORD`: Sicheres Passwort für den calendar_sync User - `DB_PASSWORD`: Sicheres Passwort für den calendar_sync User
3. **Starten** 3. **▶️ Starten**
```bash ```bash
docker compose up -d docker compose up -d
``` ```
## Demo / Lokaler Test (ohne Docker) ## 🎮 Demo / Lokaler Test (ohne Docker)
Schneller Weg um Web-UI und API lokal zu testen, ohne MariaDB oder Docker: Schneller Weg um Web-UI und API lokal zu testen, ohne MariaDB oder Docker:
@@ -66,22 +66,22 @@ Schneller Weg um Web-UI und API lokal zu testen, ohne MariaDB oder Docker:
Das Script erstellt eine virtuelle Python-Umgebung, installiert Dependencies, legt eine SQLite Demo-Datenbank mit 4 Beispiel-Terminen an und startet die API auf Port 8000. Das Script erstellt eine virtuelle Python-Umgebung, installiert Dependencies, legt eine SQLite Demo-Datenbank mit 4 Beispiel-Terminen an und startet die API auf Port 8000.
**Endpoints:** **🔗 Endpoints:**
- Web-UI: http://localhost:8000/ - 🌐 Web-UI: http://localhost:8000/
- API JSON: http://localhost:8000/api/events - 📊 API JSON: http://localhost:8000/api/events
- Health: http://localhost:8000/api/health - ❤️ Health: http://localhost:8000/api/health
**Demo-Events (4 Stück):** **🎯 Demo-Events (4 Stück):**
| Termin | Zeit | Status | | Termin | Zeit | Status |
|--------|------|--------| |--------|------|--------|
| Team Daily | heute 14:00–15:00 | CONFIRMED | | 📅 Team Daily | heute 14:00–15:00 | ✅ CONFIRMED |
| Yoga Kurs | heute 18:30–20:00 | CONFIRMED | | 🧘 Yoga Kurs | heute 18:30–20:00 | ✅ CONFIRMED |
| Projekt-Deadline | morgen Ganztag | TENTATIVE | | ⚠️ Projekt-Deadline | morgen Ganztag | 🟡 TENTATIVE |
| Arzttermin | übermorgen 10:00–11:30 | CONFIRMED | | 👨‍⚕️ Arzttermin | übermorgen 10:00–11:30 | ✅ CONFIRMED |
Die Demo verwendet SQLite (`DB_BACKEND=sqlite`) statt MariaDB. Die Events werden relativ zum heutigen Datum erstellt. Die Demo verwendet SQLite (`DB_BACKEND=sqlite`) statt MariaDB. Die Events werden relativ zum heutigen Datum erstellt.
## Konfiguration ## ⚙️ Konfiguration
| Variable | Default | Beschreibung | | Variable | Default | Beschreibung |
|----------|---------|--------------| |----------|---------|--------------|
@@ -102,7 +102,7 @@ Die Demo verwendet SQLite (`DB_BACKEND=sqlite`) statt MariaDB. Die Events werden
| `API_PORT` | `8000` | Port für den API/Web-UI Container | | `API_PORT` | `8000` | Port für den API/Web-UI Container |
| `TIMEZONE` | `UTC` | Zeitzone für API/Web-UI Anzeige (z.B. `Europe/Berlin`) | | `TIMEZONE` | `UTC` | Zeitzone für API/Web-UI Anzeige (z.B. `Europe/Berlin`) |
### Optionale E-Mail-Benachrichtigung ### 📧 Optionale E-Mail-Benachrichtigung
Sendet täglich eine HTML-Email mit den anstehenden Terminen. Wird aktiviert wenn `SMTP_HOST` und `NOTIFY_EMAIL` gesetzt sind. Sendet täglich eine HTML-Email mit den anstehenden Terminen. Wird aktiviert wenn `SMTP_HOST` und `NOTIFY_EMAIL` gesetzt sind.
@@ -118,13 +118,13 @@ Sendet täglich eine HTML-Email mit den anstehenden Terminen. Wird aktiviert wen
| `NOTIFY_TIME` | `6` | Uhrzeit für Benachrichtigung (Stunde, 0-23) | | `NOTIFY_TIME` | `6` | Uhrzeit für Benachrichtigung (Stunde, 0-23) |
| `NOTIFY_TIMEZONE` | `Europe/Berlin` | Zeitzone für die Benachrichtigung | | `NOTIFY_TIMEZONE` | `Europe/Berlin` | Zeitzone für die Benachrichtigung |
**Subject-Logik:** **📬 Subject-Logik:**
- 1 Termin: `Kalender heute: 09:00 - Meeting mit Team` - 📌 1 Termin: `Kalender heute: 09:00 - Meeting mit Team`
- 2+ Termine: `Kalender heute: 3 Termine` - 📌 2+ Termine: `Kalender heute: 3 Termine`
**Hinweis:** Ganztagstermine werden nicht in der Benachrichtigung berücksichtigt. **⚠️ Hinweis:** Ganztagstermine werden nicht in der Benachrichtigung berücksichtigt.
### Optionale wöchentliche Vorab-Info ### 📬 Optionale wöchentliche Vorab-Info
Sendet wöchentlich (standardmäßig freitags) eine HTML-Email mit Terminen, die auf konfigurierte Suchbegriffe passen. Zeitraum ist immer Samstag bis Freitag der nächsten Woche. Wird aktiviert wenn `WEEKLY_NOTIFY_ENABLED=true` und mindestens ein Suchbegriff gesetzt ist. Sendet wöchentlich (standardmäßig freitags) eine HTML-Email mit Terminen, die auf konfigurierte Suchbegriffe passen. Zeitraum ist immer Samstag bis Freitag der nächsten Woche. Wird aktiviert wenn `WEEKLY_NOTIFY_ENABLED=true` und mindestens ein Suchbegriff gesetzt ist.
@@ -137,11 +137,11 @@ Sendet wöchentlich (standardmäßig freitags) eine HTML-Email mit Terminen, die
| `WEEKLY_NOTIFY_EMAIL` | - | Empfänger (Fallback: `NOTIFY_EMAIL`) | | `WEEKLY_NOTIFY_EMAIL` | - | Empfänger (Fallback: `NOTIFY_EMAIL`) |
| `WEEKLY_SEARCHWORDS` | - | Komma-separierte Suchbegriffe | | `WEEKLY_SEARCHWORDS` | - | Komma-separierte Suchbegriffe |
**Subject-Logik:** **📬 Subject-Logik:**
- 1 Termin: `Vorab-Info: Termin am Fr, 15.08.` - 📌 1 Termin: `Vorab-Info: Termin am Fr, 15.08.`
- 2+ Termine: `Vorab-Info: 3 Termine naechste Woche` - 📌 2+ Termine: `Vorab-Info: 3 Termine naechste Woche`
**Beispiel:** **💡 Beispiel:**
```bash ```bash
WEEKLY_NOTIFY_ENABLED=true WEEKLY_NOTIFY_ENABLED=true
WEEKLY_NOTIFY_DAY=5 WEEKLY_NOTIFY_DAY=5
@@ -149,63 +149,63 @@ WEEKLY_NOTIFY_TIME=16
WEEKLY_SEARCHWORDS=Fussball,Arzttermine WEEKLY_SEARCHWORDS=Fussball,Arzttermine
``` ```
**Hinweis:** Keine Email wenn keine Treffer für die Suchbegriffe im Zeitraum. **⚠️ Hinweis:** Keine Email wenn keine Treffer für die Suchbegriffe im Zeitraum.
## Datenbank-Schema ## 🗃️ Datenbank-Schema
Tabelle `calendar_events`: **Tabelle `calendar_events`:**
| Spalte | Typ | Beschreibung | | Spalte | Typ | Beschreibung |
|--------|-----|--------------| |--------|-----|--------------|
| `id` | BIGINT PK | Auto-Increment | | `id` | 🆔 BIGINT PK | Auto-Increment |
| `calendar_label` | VARCHAR(64) | Kalender-Label | | `calendar_label` | 🏷️ VARCHAR(64) | Kalender-Label |
| `instance_key` | VARCHAR(255) | SHA1-basierte eindeutige Instanz-ID | | `instance_key` | 🔑 VARCHAR(255) | SHA1-basierte eindeutige Instanz-ID |
| `uid` | VARCHAR(255) | ICS UID | | `uid` | 📌 VARCHAR(255) | ICS UID |
| `recurrence_id` | VARCHAR(64) | RECURRENCE-ID bei Serien-Exceptions | | `recurrence_id` | 🔄 VARCHAR(64) | RECURRENCE-ID bei Serien-Exceptions |
| `summary` | VARCHAR(512) | Titel | | `summary` | 📝 VARCHAR(512) | Titel |
| `description` | TEXT | Beschreibung | | `description` | 📄 TEXT | Beschreibung |
| `location` | VARCHAR(512) | Ort | | `location` | 📍 VARCHAR(512) | Ort |
| `start_at` | DATETIME | Startzeit (UTC) | | `start_at` | 🚀 DATETIME | Startzeit (UTC) |
| `end_at` | DATETIME | Endzeit (UTC) | | `end_at` | 🏁 DATETIME | Endzeit (UTC) |
| `all_day` | TINYINT(1) | Ganz-tagig Flag | | `all_day` | ☀️ TINYINT(1) | Ganz-tagig Flag |
| `status` | VARCHAR(32) | Event-Status | | `status` | 📊 VARCHAR(32) | Event-Status |
| `deleted` | TINYINT(1) | Soft-Delete Flag | | `deleted` | 🗑️ TINYINT(1) | Soft-Delete Flag |
| `last_seen_at` | DATETIME | Letzte Synchronisation | | `last_seen_at` | 👁️ DATETIME | Letzte Synchronisation |
| `created_at` | DATETIME | Erstellungszeitpunkt | | `created_at` | 🎨 DATETIME | Erstellungszeitpunkt |
| `updated_at` | DATETIME | Letzte Änderung | | `updated_at` | 🔄 DATETIME | Letzte Änderung |
Tabelle `daily_notification_log` (optional, für E-Mail-Benachrichtigung): **Tabelle `daily_notification_log` (optional, für E-Mail-Benachrichtigung):**
| Spalte | Typ | Beschreibung | | Spalte | Typ | Beschreibung |
|--------|-----|--------------| |--------|-----|--------------|
| `id` | INT PK | Auto-Increment | | `id` | 🆔 INT PK | Auto-Increment |
| `notify_date` | DATE | Datum der Benachrichtigung | | `notify_date` | 📅 DATE | Datum der Benachrichtigung |
| `sent_at` | DATETIME | Zeitpunkt des Versands | | `sent_at` | ⏰ DATETIME | Zeitpunkt des Versands |
| `event_count` | INT | Anzahl Termine in der Email | | `event_count` | 🔢 INT | Anzahl Termine in der Email |
Tabelle `weekly_notification_log` (optional, für wöchentliche Vorab-Info): **Tabelle `weekly_notification_log` (optional, für wöchentliche Vorab-Info):**
| Spalte | Typ | Beschreibung | | Spalte | Typ | Beschreibung |
|--------|-----|--------------| |--------|-----|--------------|
| `id` | INT PK | Auto-Increment | | `id` | 🆔 INT PK | Auto-Increment |
| `notify_date` | DATE | Datum der Benachrichtigung | | `notify_date` | 📅 DATE | Datum der Benachrichtigung |
| `sent_at` | DATETIME | Zeitpunkt des Versands | | `sent_at` | ⏰ DATETIME | Zeitpunkt des Versands |
| `event_count` | INT | Anzahl Termine in der Email | | `event_count` | 🔢 INT | Anzahl Termine in der Email |
## Web-UI & API ## 🌐 Web-UI & API
Das Projekt enthält eine FastAPI-basierte Webanwendung die als separater Container (`calendar-api`) läuft und auf Port `8000` erreichbar ist. Das Projekt enthält eine FastAPI-basierte Webanwendung die als separater Container (`calendar-api`) läuft und auf Port `8000` erreichbar ist.
### Endpoints ### 🔗 Endpoints
| Endpoint | Beschreibung | | Endpoint | Beschreibung |
|----------|--------------| |----------|--------------|
| `GET /` | HTML-Seite mit anstehenden Terminen und Suchfunktion | | `GET /` | 🌐 HTML-Seite mit anstehenden Terminen und Suchfunktion |
| `GET /api/health` | Health Check (gibt `{"status": "ok"}` zurück) | | `GET /api/health` | ❤️ Health Check (gibt `{"status": "ok"}` zurück) |
| `GET /api/events?limit=10&search=...` | JSON-Liste zukünftiger Events (nicht gelöscht) | | `GET /api/events?limit=10&search=...` | 📊 JSON-Liste zukünftiger Events (nicht gelöscht) |
| `GET /api/events/{event_id}` | Einzelnes Event als JSON | | `GET /api/events/{event_id}` | 🔍 Einzelnes Event als JSON |
### API Beispiel ### 💡 API Beispiel
```bash ```bash
# Alle anstehenden Events (max. 10) # Alle anstehenden Events (max. 10)
@@ -218,7 +218,7 @@ curl "http://localhost:8000/api/events?search=Meeting&limit=5"
curl http://localhost:8000/api/events/42 curl http://localhost:8000/api/events/42
``` ```
### JSON Response Format ### 📋 JSON Response Format
```json ```json
{ {
@@ -241,7 +241,7 @@ curl http://localhost:8000/api/events/42
} }
``` ```
## CI/CD ## 🔄 CI/CD
GitHub Actions Workflow (`docker-publish.yml`) baut und published das Docker Image automatisch nach GitHub Container Registry: GitHub Actions Workflow (`docker-publish.yml`) baut und published das Docker Image automatisch nach GitHub Container Registry:
@@ -249,6 +249,6 @@ GitHub Actions Workflow (`docker-publish.yml`) baut und published das Docker Ima
ghcr.io/skoelle/calender_sync:latest ghcr.io/skoelle/calender_sync:latest
``` ```
## Lizenz ## 📜 Lizenz
Lizenziert unter der [MIT License](LICENSE) - Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de) Lizenziert unter der [MIT License](LICENSE) - Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)