diff --git a/README.md b/README.md index 4c1baae..d34c8a1 100644 --- a/README.md +++ b/README.md @@ -1,392 +1,598 @@
-# 🏠 Oikos +
-**Selbstgehosteter Familienplaner — privat, offen, ohne Abonnement** +# Oikos -[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org) -[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white)](https://www.docker.com) -[![SQLite](https://img.shields.io/badge/SQLite-SQLCipher%20verschlĂŒsselt-003B57?logo=sqlite&logoColor=white)](https://www.zetetic.net/sqlcipher/) -[![PWA](https://img.shields.io/badge/PWA-offline--fĂ€hig-5A0FC8?logo=pwa&logoColor=white)](https://web.dev/progressive-web-apps/) -[![Lizenz: MIT](https://img.shields.io/badge/Lizenz-MIT-yellow.svg)](./LICENSE) +### Der Familienplaner, der bei dir zuhause bleibt. -Alle Daten bleiben auf deinem eigenen Server. -Kein Cloud-Zwang. Keine Datenweitergabe. Kein Tracking. +Oikos ist eine selbstgehostete Web-App, die den Alltag deiner Familie organisiert — +vom Einkaufszettel bis zum Kalender, vom Essensplan bis zum Budget. +Alles auf deinem eigenen Server. Ohne Cloud. Ohne Abo. Ohne Tracking. -[Screenshots](#screenshots) · [Module](#module) · [Schnellstart](#schnellstart) · [Konfiguration](#konfiguration) · [Kalender-Sync](#kalender-synchronisation) · [Sicherheit](#sicherheit) +
+ +[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org) +[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com) +[![SQLite](https://img.shields.io/badge/SQLite-verschl%C3%BCsselt-003B57?style=flat-square&logo=sqlite&logoColor=white)](https://www.zetetic.net/sqlcipher/) +[![PWA](https://img.shields.io/badge/PWA-offline--f%C3%A4hig-5A0FC8?style=flat-square)](https://web.dev/progressive-web-apps/) +[![Lizenz](https://img.shields.io/badge/Lizenz-MIT-green?style=flat-square)](./LICENSE) + +
+ +[Funktionen](#-was-kann-oikos) · [Screenshots](#-screenshots) · [Installation](#-installation) · [Konfiguration](#-konfiguration) · [FAQ](#-faq) + +
--- +
+ +## Warum Oikos? + +Die meisten Familienplaner sind Cloud-Dienste: Deine Termine, Einkaufslisten und Finanzdaten liegen auf fremden Servern. Oikos dreht das um. + +| | Cloud-Dienste | Oikos | +|:---|:---|:---| +| **Deine Daten** | Auf fremden Servern | Auf deinem Server, verschlĂŒsselt | +| **Kosten** | Monatliches Abo | Einmal einrichten, dauerhaft kostenlos | +| **Datenschutz** | Tracking, Werbung, Analyse | Kein Tracking. Keine Telemetrie. Nichts. | +| **VerfĂŒgbarkeit** | AbhĂ€ngig vom Anbieter | Du hast die Kontrolle | +| **Zugang** | App Store nötig | Browser reicht (PWA, installierbar) | + +> **Der Name:** *Oikos* (griechisch: *oikos*) bedeutet „Haus" oder „Haushalt" — der Ursprung des Wortes *Ökonomie*. Passend fĂŒr eine App, die deinen Haushalt organisiert. + +
+ +--- + +
+ +## Was kann Oikos? + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
Modul
+ 		Beschreibung
DashboardDein Tagesstart auf einen Blick: Wetter, anstehende Termine, dringende Aufgaben, heutiges Essen und angepinnte Notizen. Alles in einem personalisierten Feed.
AufgabenAufgaben erstellen, priorisieren und Familienmitgliedern zuweisen. Mit Teilaufgaben, Wiederholungen (tÀglich/wöchentlich/monatlich), Statusfiltern und Swipe-Gesten auf dem Handy.
EinkaufMehrere Einkaufslisten parallel fĂŒhren (REWE, dm, Baumarkt ...). Artikel werden automatisch nach Supermarkt-Kategorien gruppiert — wie ein digitaler Einkaufszettel, den die ganze Familie gemeinsam befĂŒllt.
EssensplanWochenplan fĂŒr FrĂŒhstĂŒck, Mittag, Abend und Snacks. Zutaten pro Mahlzeit erfassen und mit einem Klick auf die Einkaufsliste ĂŒbernehmen.
KalenderFamilienkalender mit vier Ansichten (Monat, Woche, Tag, Agenda). Farbcodiert pro Person. Wiederkehrende Termine. Optional mit Google Calendar und Apple iCloud synchronisierbar.
PinnwandFarbige Sticky Notes im Masonry-Grid. FĂŒr schnelle Erinnerungen, Nachrichten an die Familie oder Ideen. Mit Markdown-Light (fett, kursiv, Listen).
KontakteWichtige Kontakte der Familie — Kinderarzt, Schule, Handwerker, Versicherung. Mit Direktanruf per Tap, E-Mail-Links und Kartennavigation.
BudgetEinnahmen und Ausgaben tracken, nach Kategorien auswerten, Monate vergleichen. Mit wiederkehrenden Buchungen (Miete, Gehalt) und CSV-Export.
EinstellungenDark Mode (System / Hell / Dunkel), Passwort Àndern, Kalender-Sync verwalten, Familienmitglieder anlegen.
+ +
+ +--- + +
+ ## Screenshots
-### ☀ Light Mode +### Light Mode + + +
- Dashboard
+ Dashboard
Dashboard
- Wetter · Termine · Aufgaben · Essen + Wetter, Termine, Aufgaben, Essen 		- Aufgaben
+ Aufgaben
Aufgaben
- PrioritÀten · Zuweisung · Filter + PrioritÀten, Zuweisung, Filter 		- Kalender
+ Kalender
Kalender
- Monatsansicht · Google & Apple Sync + Monatsansicht, Tagesdetails
- Einkaufsliste
+ Einkaufsliste
Einkauf
- Mehrere Listen · Kategorien · Fortschritt + Mehrere Listen, Kategorien 		- Essensplan
+ Essensplan
Essensplan
- Wochenplan · Zutaten · → Einkaufsliste + Wochenplan, Zutaten + 		+  
-### 🌙 Dark Mode +
+ +### Dark Mode + + +
- Dashboard Dark
- Dashboard
- Wetter · Termine · Aufgaben · Essen + Dashboard Dark
+ Dashboard 		- Aufgaben Dark
- Aufgaben
- PrioritÀten · Zuweisung · Filter + Aufgaben Dark
+ Aufgaben 		- Kalender Dark
- Kalender
- Monatsansicht · Google & Apple Sync + Kalender Dark
+ Kalender +
+ Einkaufsliste Dark
+ Einkauf 		- Einkaufsliste Dark
- Einkauf
- Mehrere Listen · Kategorien · Fortschritt + Essensplan Dark
+ Essensplan 		- Essensplan Dark
- Essensplan
- Wochenplan · Zutaten · → Einkaufsliste +  
-Dark Mode: Automatisch via Systemeinstellung oder manuell umschaltbar unter Einstellungen → Design. +Dark Mode folgt automatisch deiner Systemeinstellung oder lĂ€sst sich manuell unter Einstellungen umschalten.
---- - -## Module - -| | Modul | Highlights | -|---|---|---| -| 📋 | **Dashboard** | Wetter-Widget, anstehende Termine, dringende Aufgaben, Essen heute, Pinnwand-Vorschau | -| ✅ | **Aufgaben** | Listenansicht + Kanban, Teilaufgaben, Swipe-Gesten, Wiederholungen (tĂ€glich/wöchentlich/monatlich) | -| 🛒 | **Einkauf** | Mehrere Listen, automatische Kategorie-Sortierung, Integration mit Essensplan | -| đŸœïž | **Essensplan** | Wochenansicht, Zutatenverwaltung, Zutaten → Einkaufsliste mit einem Klick | -| 📅 | **Kalender** | 4 Ansichten (Monat/Woche/Tag/Agenda), wiederkehrende Termine, Google & Apple Sync | -| 📌 | **Pinnwand** | Farbige Sticky Notes, Markdown-Light (fett, kursiv, Listen) | -| đŸ‘„ | **Kontakte** | Wichtige Familien-Kontakte, Direktanruf (`tel:`), Maps-Links | -| 💰 | **Budget** | Einnahmen/Ausgaben, Kategorien, Monatsvergleich, CSV-Export | -| ⚙ | **Einstellungen** | Dark Mode (System/Hell/Dunkel), Passwort Ă€ndern, Kalender-Sync, Familienmitglieder | +
--- -## Tech Stack +
-**Backend:** Node.js · Express · SQLite/SQLCipher · express-session · bcrypt +## Technik auf einen Blick -**Frontend:** Vanilla JavaScript (ES-Module) · Kein Framework · Kein Build-Step +Oikos setzt bewusst auf einen minimalen, wartungsarmen Stack — keine 200 npm-Pakete, kein Build-Step, kein Framework-Lock-in. -**Deployment:** Docker · Nginx Reverse Proxy · PWA (Service Worker + Manifest) +| Schicht | Technologie | +|:---|:---| +| **Server** | Node.js + Express.js | +| **Datenbank** | SQLite mit SQLCipher-VerschlĂŒsselung (AES-256) | +| **Frontend** | Vanilla JavaScript (ES-Module), eigenes CSS — kein React, kein Vue, kein Bundler | +| **Auth** | Session-basiert, bcrypt-Passwort-Hashing, CSRF-Schutz | +| **Deployment** | Docker (ein Container, ein Volume) | +| **PWA** | Service Worker + Manifest — installierbar auf Homescreen, offline-fĂ€hig | +| **Kalender-Sync** | Google Calendar API v3 (OAuth) + Apple iCloud CalDAV (optional) | -**Optional:** Google Calendar API v3 (OAuth 2.0) · Apple iCloud CalDAV (tsdav) +
--- +
+ ## Installation +> **Zeitaufwand:** ca. 10–15 Minuten, auch wenn du Docker zum ersten Mal nutzt. + ### Voraussetzungen -- **Docker** und **Docker Compose** (auf dem Server installiert) -- Einen Linux-Server oder eine lokale Linux-Maschine -- FĂŒr den produktiven Betrieb: eine Domain und einen Reverse Proxy mit SSL (empfohlen: [Nginx Proxy Manager](https://nginxproxymanager.com)) +Du brauchst einen Linux-Server (oder eine lokale Linux-Maschine / VM / Raspberry Pi) mit: + +- **Docker** und **Docker Compose** — [Installationsanleitung (offizielle Docs)](https://docs.docker.com/engine/install/) +- **Git** — ist auf den meisten Linux-Distributionen vorinstalliert (`git --version` zum PrĂŒfen) + +> **Noch keinen Server?** Ein gĂŒnstiger VPS (z.B. bei Hetzner, Netcup oder Oracle Cloud Free Tier) reicht völlig aus. Oikos braucht minimal 512 MB RAM und 1 CPU-Kern. --- -### Schritt 1 — Repository klonen +### Schritt 1 — Repository herunterladen + +Öffne ein Terminal auf deinem Server und fĂŒhre aus: ```bash git clone https://github.com/ulsklyc/oikos.git cd oikos ``` +
+Was passiert hier? + +`git clone` lÀdt den gesamten Quellcode von GitHub auf deinen Server herunter. +`cd oikos` wechselt in das heruntergeladene Verzeichnis. + +
+ --- -### Schritt 2 — Umgebungsvariablen konfigurieren +### Schritt 2 — Konfiguration anlegen ```bash cp .env.example .env ``` -Die `.env`-Datei mit einem Texteditor öffnen und mindestens diese Felder ausfĂŒllen: +Jetzt die `.env`-Datei bearbeiten — z.B. mit `nano`: + +```bash +nano .env +``` + +Mindestens diese zwei Felder musst du ausfĂŒllen: ```env -# ZufĂ€lliger String mit mindestens 32 Zeichen — z.B. generieren mit: -# openssl rand -base64 32 +# Ein langer, zufĂ€lliger String. Wird zum Signieren von Sessions verwendet. +# So generierst du einen im Terminal: +# openssl rand -base64 32 SESSION_SECRET=hier_einen_langen_zufaelligen_string_eintragen -# VerschlĂŒsselungsschlĂŒssel fĂŒr die Datenbank (AES-256) -# Leer lassen = keine VerschlĂŒsselung (nicht empfohlen fĂŒr Produktion) +# VerschlĂŒsselungsschlĂŒssel fĂŒr die Datenbank (AES-256). +# Ebenfalls mit openssl generieren. Leer lassen = keine VerschlĂŒsselung. DB_ENCRYPTION_KEY=hier_einen_starken_schluessel_eintragen ``` -> **Tipp:** ZufĂ€llige SchlĂŒssel lassen sich einfach im Terminal generieren: -> ```bash -> openssl rand -base64 32 -> ``` +
+SchlĂŒssel generieren — so geht's -> Alle verfĂŒgbaren Variablen: [Konfigurationsreferenz](#konfiguration) +FĂŒhre diesen Befehl zweimal aus und kopiere die Ausgabe jeweils in die `.env`: + +```bash +openssl rand -base64 32 +``` + +Das erzeugt eine zufĂ€llige Zeichenfolge wie `K7xQ3m+r9Fz1bY4p...` — perfekt als Secret. + +
+ +
+Was bedeuten die anderen Felder in der .env? + +Die `.env.example` enthĂ€lt noch weitere Optionen (Wetter, Kalender-Sync etc.). Diese sind alle **optional** und werden weiter unten im Abschnitt [Konfiguration](#-konfiguration) erklĂ€rt. FĂŒr den Start brauchst du nur die zwei Pflichtfelder. + +
+ +Speichern in nano: `Strg+O`, `Enter`, `Strg+X`. --- -### Schritt 3 — Container bauen und starten +### Schritt 3 — App starten ```bash docker compose up -d --build ``` -> Der erste Build dauert **2–3 Minuten**, da SQLCipher gegen better-sqlite3 kompiliert wird. Folgende Builds sind deutlich schneller (Docker-Layer-Cache). +Der erste Build kompiliert SQLCipher und dauert **2–3 Minuten**. Alle weiteren Starts sind deutlich schneller. -Den Status des Containers prĂŒfen: +PrĂŒfe, ob der Container lĂ€uft: ```bash docker compose ps -docker compose logs oikos --tail=20 ``` -Der Server ist bereit, wenn in den Logs erscheint: +Du solltest sehen, dass der Container `oikos` den Status `Up` hat. Falls etwas nicht stimmt: + +```bash +docker compose logs oikos --tail=30 +``` + +Wenn in den Logs steht: + ``` [Oikos] Server lĂ€uft auf Port 3000 ``` +...ist alles bereit. + --- -### Schritt 4 — Admin-Account anlegen +### Schritt 4 — Ersten Benutzer anlegen ```bash docker compose exec oikos node setup.js ``` -Das interaktive Script fragt nach **Benutzername**, **Anzeigename** und **Passwort**. Dieser erste Account erhĂ€lt Admin-Rechte und kann spĂ€ter weitere Familienmitglieder anlegen. +Das Script fragt dich interaktiv nach: +- **Benutzername** — zum Einloggen (z.B. `mama`, `papa`, `lisa`) +- **Anzeigename** — wird in der App angezeigt (z.B. `Lisa MĂŒller`) +- **Passwort** — mindestens 6 Zeichen + +Dieser erste Account bekommt automatisch **Admin-Rechte** und kann spĂ€ter weitere Familienmitglieder anlegen. --- -### Schritt 5 — App öffnen und einloggen +### Schritt 5 — App öffnen -Ohne Reverse Proxy (lokaler Test): +Im Browser aufrufen: ``` -http://localhost:3000 +http://:3000 ``` -> **Wichtig bei direktem HTTP-Zugriff ohne Reverse Proxy:** -> Da `NODE_ENV=production` gesetzt ist, erwartet der Server standardmĂ€ĂŸig HTTPS fĂŒr Session-Cookies. Beim Zugriff per `http://` muss daher in der `.env` folgende Zeile ergĂ€nzt werden: -> +Logge dich mit dem gerade erstellten Account ein — fertig! + +> **Hinweis fĂŒr lokalen Zugriff ohne HTTPS:** +> Im Produktionsmodus erwartet Oikos standardmĂ€ĂŸig HTTPS fĂŒr sichere Cookies. Wenn du die App zunĂ€chst ohne Reverse Proxy testen möchtest, fĂŒge in der `.env` hinzu: > ```env > SESSION_SECURE=false > ``` +> Dann Container neu starten: `docker compose down && docker compose up -d` > -> Danach Container neu starten: `docker compose down && docker compose up -d` -> Diese Einstellung **unbedingt entfernen**, sobald ein Reverse Proxy mit SSL eingerichtet ist. +> **Entferne diese Zeile wieder**, sobald du HTTPS eingerichtet hast (siehe nĂ€chster Schritt). --- -### Schritt 6 — Reverse Proxy mit SSL einrichten (Produktion) +### Schritt 6 — HTTPS einrichten (empfohlen) -FĂŒr den produktiven Betrieb sollte Oikos hinter einem Nginx Reverse Proxy mit SSL betrieben werden. +FĂŒr den dauerhaften Betrieb sollte Oikos hinter einem Reverse Proxy mit SSL laufen. Das schĂŒtzt Passwörter und Sessions auf dem Transportweg. -**Mit Nginx Proxy Manager:** +
+Variante A: Nginx Proxy Manager (empfohlen fĂŒr Einsteiger) -1. Neuen Proxy Host anlegen: `oikos.deine-domain.de` → `localhost:3000` -2. SSL-Zertifikat via Let's Encrypt ausstellen -3. Im Feld „Advanced" den Inhalt aus [`nginx.conf.example`](./nginx.conf.example) eintragen +[Nginx Proxy Manager](https://nginxproxymanager.com) ist ein benutzerfreundlicher Reverse Proxy mit Web-OberflĂ€che. -**Wichtig:** Der Header `X-Forwarded-Proto` muss gesetzt sein (ist in der Beispielkonfiguration enthalten). Ohne ihn weiß der Server nicht, dass er hinter HTTPS lĂ€uft, und setzt Cookies nicht korrekt. +1. **Nginx Proxy Manager installieren** (falls noch nicht vorhanden) — [Anleitung](https://nginxproxymanager.com/guide/) +2. Neuen **Proxy Host** anlegen: + - Domain: `oikos.deine-domain.de` + - Forward Hostname: `deine-server-ip` (oder `localhost` wenn auf demselben Server) + - Forward Port: `3000` +3. Reiter **SSL**: Let's Encrypt Zertifikat ausstellen lassen (kostenlos, automatisch) +4. Reiter **Advanced**: Den Inhalt von [`nginx.conf.example`](./nginx.conf.example) einfĂŒgen -Sobald SSL aktiv ist: `SESSION_SECURE=false` aus der `.env` entfernen und Container neu starten. +**Wichtig:** Der Header `X-Forwarded-Proto` muss gesetzt sein (ist in der Beispielkonfiguration enthalten). Ohne ihn erkennt Oikos nicht, dass die Verbindung per HTTPS lĂ€uft. + +
+ +
+Variante B: Nginx manuell konfigurieren + +Kopiere die Datei [`nginx.conf.example`](./nginx.conf.example) und passe die Domain an: + +```bash +sudo cp nginx.conf.example /etc/nginx/sites-available/oikos +sudo ln -s /etc/nginx/sites-available/oikos /etc/nginx/sites-enabled/ +# Domain in der Datei anpassen: +sudo nano /etc/nginx/sites-available/oikos +``` + +FĂŒr SSL-Zertifikate mit Let's Encrypt: + +```bash +sudo apt install certbot python3-certbot-nginx +sudo certbot --nginx -d oikos.deine-domain.de +``` + +Nginx neu laden: + +```bash +sudo nginx -t && sudo systemctl reload nginx +``` + +
+ +Sobald HTTPS lÀuft: `SESSION_SECURE=false` aus der `.env` **entfernen** und Container neu starten. + +
--- +
+ ## Konfiguration ### Pflichtfelder -| Variable | Beschreibung | -|---|---| -| `SESSION_SECRET` | ZufĂ€lliger String ≄ 32 Zeichen fĂŒr Session-Signing | -| `DB_ENCRYPTION_KEY` | SQLCipher AES-256-SchlĂŒssel (leer lassen = keine VerschlĂŒsselung) | +| Variable | Beschreibung | Beispiel | +|:---|:---|:---| +| `SESSION_SECRET` | ZufĂ€lliger String (mind. 32 Zeichen) zum Signieren von Sessions | `openssl rand -base64 32` | +| `DB_ENCRYPTION_KEY` | SQLCipher-SchlĂŒssel (AES-256) — leer = keine VerschlĂŒsselung | `openssl rand -base64 32` | + +### Wetter-Widget + +Das Dashboard zeigt ein Wetter-Widget, wenn ein API-Key konfiguriert ist. Kostenlos registrieren bei [openweathermap.org](https://openweathermap.org/api): + +```env +OPENWEATHER_API_KEY=dein_api_key_hier +OPENWEATHER_CITY=Berlin +OPENWEATHER_UNITS=metric # metric = Celsius, imperial = Fahrenheit +OPENWEATHER_LANG=de +``` ### Sicherheit | Variable | Standard | Beschreibung | -|---|---|---| -| `SESSION_SECURE` | *(nicht gesetzt)* | `false` setzen wenn kein HTTPS-Reverse-Proxy vorhanden (direktes HTTP) | -| `RATE_LIMIT_MAX_ATTEMPTS` | `5` | Max. Login-Versuche pro Minute pro IP | - -### Wetter-Widget - -Kostenlosen API-Key bei [openweathermap.org](https://openweathermap.org/api) registrieren: - -```env -OPENWEATHER_API_KEY=dein_api_key -OPENWEATHER_CITY=Berlin -OPENWEATHER_UNITS=metric # metric = °C, imperial = °F -OPENWEATHER_LANG=de -``` +|:---|:---|:---| +| `SESSION_SECURE` | *(nicht gesetzt)* | Auf `false` setzen wenn kein HTTPS verfĂŒgbar (nur zum Testen!) | +| `RATE_LIMIT_MAX_ATTEMPTS` | `5` | Max. fehlgeschlagene Login-Versuche pro Minute | ### Weitere Optionen | Variable | Standard | Beschreibung | -|---|---|---| -| `PORT` | `3000` | Server-Port | -| `NODE_ENV` | `production` | Umgebung (nicht Ă€ndern) | -| `DB_PATH` | `/data/oikos.db` | Pfad zur SQLite-Datei im Container | -| `SYNC_INTERVAL_MINUTES` | `15` | Automatischer Kalender-Sync-Intervall | +|:---|:---|:---| +| `PORT` | `3000` | Server-Port im Container | +| `DB_PATH` | `/data/oikos.db` | Datenbankpfad im Container | +| `SYNC_INTERVAL_MINUTES` | `15` | Kalender-Sync-Intervall (in Minuten) | -VollstĂ€ndige Vorlage: [`.env.example`](./.env.example) +Die vollstĂ€ndige Vorlage mit allen Optionen findest du in [`.env.example`](./.env.example). + +
--- +
+ ## Kalender-Synchronisation +Oikos kann sich mit externen Kalendern synchronisieren, damit Termine aus Google Calendar oder Apple iCloud automatisch in der App erscheinen — und umgekehrt. + ### Google Calendar
-Einrichtung anzeigen +Schritt-fĂŒr-Schritt-Anleitung -#### Google Cloud Console vorbereiten +#### 1. Google Cloud Projekt anlegen -1. Projekt unter [console.cloud.google.com](https://console.cloud.google.com) anlegen -2. **Google Calendar API** aktivieren -3. **OAuth 2.0-Client-ID** erstellen (Typ: „Webanwendung") -4. Autorisierte Redirect-URI eintragen: - ``` - https://oikos.deine-domain.de/api/v1/calendar/google/callback - ``` -5. In `.env` eintragen: - ```env - GOOGLE_CLIENT_ID=... - GOOGLE_CLIENT_SECRET=... - GOOGLE_REDIRECT_URI=https://oikos.deine-domain.de/api/v1/calendar/google/callback - ``` -6. Container neu starten: `docker compose up -d` +1. Gehe zu [console.cloud.google.com](https://console.cloud.google.com) und erstelle ein neues Projekt +2. Aktiviere die **Google Calendar API** unter „APIs & Dienste" → „Bibliothek" +3. Unter „APIs & Dienste" → „Anmeldedaten" → **OAuth 2.0-Client-ID erstellen** + - Anwendungstyp: „Webanwendung" + - Autorisierte Redirect-URI: + ``` + https://oikos.deine-domain.de/api/v1/calendar/google/callback + ``` +4. Client-ID und Client-Secret kopieren -#### Verbindung herstellen +#### 2. In Oikos konfigurieren -1. Mit einem **Admin**-Konto einloggen -2. **Einstellungen → Kalender-Synchronisation → Mit Google verbinden** -3. Google-Konto autorisieren → automatische Weiterleitung zurĂŒck +In der `.env` eintragen: -**Sync-Verhalten:** -- Erster Sync: Events der letzten 3 Monate + nĂ€chsten 12 Monate -- Folge-Syncs: nur Änderungen via Google syncToken (effizient) -- Outbound: neue lokale Termine werden nach Google ĂŒbertragen -- Konflikt: Google gewinnt bei gleichzeitiger Änderung +```env +GOOGLE_CLIENT_ID=deine-client-id.apps.googleusercontent.com +GOOGLE_CLIENT_SECRET=dein-client-secret +GOOGLE_REDIRECT_URI=https://oikos.deine-domain.de/api/v1/calendar/google/callback +``` + +Container neu starten: `docker compose up -d` + +#### 3. Verbindung herstellen + +1. In Oikos einloggen (Admin-Account) +2. **Einstellungen** → **Kalender-Synchronisation** → **Mit Google verbinden** +3. Google-Konto auswĂ€hlen und autorisieren +4. Automatische Weiterleitung zurĂŒck zu Oikos + +#### So funktioniert der Sync + +- **Erster Sync:** Termine der letzten 3 Monate und nĂ€chsten 12 Monate werden importiert +- **Folge-Syncs:** Nur Änderungen werden abgeglichen (effizient via Google syncToken) +- **Neue lokale Termine** werden auch nach Google ĂŒbertragen (bidirektional) +- **Bei Konflikten** gewinnt Google — lokale ErgĂ€nzungen bleiben erhalten
-### Apple Calendar (iCloud CalDAV) +### Apple Calendar (iCloud)
-Einrichtung anzeigen +Schritt-fĂŒr-Schritt-Anleitung -#### App-spezifisches Passwort erstellen +#### 1. App-spezifisches Passwort erstellen -1. [appleid.apple.com](https://appleid.apple.com) → „Anmeldung und Sicherheit" → „App-spezifische Passwörter" -2. Neues Passwort fĂŒr „Oikos" erstellen -3. In `.env` eintragen: - ```env - APPLE_CALDAV_URL=https://caldav.icloud.com - APPLE_USERNAME=deine@apple-id.de - APPLE_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx - ``` -4. Container neu starten: `docker compose up -d` +Apple erfordert ein eigenes Passwort fĂŒr Drittanbieter-Apps: -Der Sync-Button erscheint automatisch in den Einstellungen. +1. Gehe zu [appleid.apple.com](https://appleid.apple.com) +2. Unter „Anmeldung und Sicherheit" → „App-spezifische Passwörter" → „Passwort generieren" +3. Label eingeben (z.B. „Oikos") +4. Das generierte Passwort kopieren (Format: `xxxx-xxxx-xxxx-xxxx`) + +#### 2. In Oikos konfigurieren + +In der `.env` eintragen: + +```env +APPLE_CALDAV_URL=https://caldav.icloud.com +APPLE_USERNAME=deine@apple-id.de +APPLE_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx +``` + +Container neu starten: `docker compose up -d` + +Der Sync-Button erscheint dann automatisch in den Einstellungen.
+
+ --- -## Familienmitglieder +
-Neue Mitglieder können nur Admins anlegen — es gibt keinen öffentlichen Registrierungs-Endpoint. +## Familienmitglieder verwalten -**Im Browser:** Einstellungen → Familienmitglieder → Mitglied hinzufĂŒgen +Neue Accounts können **nur Admins** anlegen — es gibt absichtlich keine öffentliche Registrierung. + +**In der App:** Einstellungen → Familienmitglieder → Mitglied hinzufĂŒgen + +**Per Terminal** (z.B. fĂŒr einen weiteren Admin): -**Per Script** (z.B. fĂŒr weiteren Admin): ```bash docker compose exec oikos node setup.js ``` +
+ --- +
+ ## Updates ```bash +cd oikos git pull docker compose up -d --build ``` -Datenbank-Migrationen laufen automatisch beim Start — kein manueller Eingriff nötig. Alle Daten im Volume `oikos_data` bleiben erhalten. +Das war's. Datenbank-Migrationen laufen automatisch beim Start. Alle Daten im Docker-Volume bleiben erhalten. -> **Empfehlung:** Vor jedem Update ein Backup erstellen — siehe [Datensicherung](#datensicherung). +> **Empfehlung:** Vor jedem Update ein Backup erstellen. + +
--- -## Entwicklung - -```bash -npm install -cp .env.example .env -# SESSION_SECRET setzen — DB_ENCRYPTION_KEY weglassen (kein SQLCipher lokal) -npm run dev # Server mit Auto-Reload -``` - -```bash -npm test # 146 Tests, 7 Suiten (In-Memory-SQLite, keine laufende App nötig) -``` - ---- +
## Datensicherung +### Backup erstellen + ```bash -# Backup erstellen docker run --rm \ -v oikos_oikos_data:/data \ -v $(pwd):/backup \ alpine tar czf /backup/oikos-backup-$(date +%Y%m%d).tar.gz /data +``` -# Backup wiederherstellen +Das erstellt eine komprimierte Sicherung der gesamten Datenbank im aktuellen Verzeichnis. + +### Backup wiederherstellen + +```bash docker compose down docker run --rm \ -v oikos_oikos_data:/data \ @@ -395,22 +601,124 @@ docker run --rm \ docker compose up -d ``` +> Ersetze `YYYYMMDD` durch das Datum deines Backups (z.B. `20260326`). + +
+ --- +
+ +## Lokale Entwicklung + +Falls du Oikos weiterentwickeln oder anpassen möchtest: + +```bash +git clone https://github.com/ulsklyc/oikos.git +cd oikos +npm install +cp .env.example .env +# In der .env: SESSION_SECRET setzen, DB_ENCRYPTION_KEY leer lassen +npm run dev # Server starten mit Auto-Reload bei DateiĂ€nderungen +``` + +Tests ausfĂŒhren: + +```bash +npm test # 146 Tests, 7 Suiten (In-Memory-SQLite, kein laufender Server nötig) +``` + +
+ +--- + +
+ ## Sicherheit -- Sessions: `httpOnly`, `SameSite=Strict`, `Secure` in Produktion, 7 Tage TTL -- CSRF-Schutz via Double Submit Cookie (`crypto.timingSafeEqual`) auf allen schreibenden Requests -- Passwörter mit bcrypt (Cost Factor 12) gehasht -- Login-Rate-Limit: 5 Versuche/Minute, API-Rate-Limit: 300 Requests/Minute pro IP -- Content Security Policy via Helmet (strikte CSP, HSTS, X-Frame-Options) -- Zentrale Input-Validation auf allen Endpoints (LĂ€ngenlimits, Typ-PrĂŒfung, Enum-Whitelists) -- Parametrisierte SQL-Queries (kein String-Concatenation, kein `eval()`) -- Datenbank optional mit SQLCipher AES-256 verschlĂŒsselt (im Docker-Container) -- Kein API-Endpoint ohne Session-Auth erreichbar (außer `/api/v1/auth/login`) +Oikos nimmt den Schutz deiner Familiendaten ernst: + +| Maßnahme | Details | +|:---|:---| +| **VerschlĂŒsselte Datenbank** | SQLCipher (AES-256) — Daten sind auch bei Serverzugriff geschĂŒtzt | +| **Sichere Passwörter** | bcrypt mit Cost Factor 12 — kein Klartext, nie | +| **Session-Schutz** | `httpOnly`, `SameSite=Strict`, `Secure`-Cookies, 7 Tage Ablauf | +| **CSRF-Schutz** | Double Submit Cookie mit `crypto.timingSafeEqual` | +| **Rate Limiting** | 5 Login-Versuche/Minute, dann 15 Min. Sperre | +| **Input-Validation** | Zentrale Validierung auf allen Endpoints (LĂ€nge, Typ, Whitelist) | +| **SQL-Injection-Schutz** | Parametrisierte Queries ĂŒberall — kein String-Zusammenbau | +| **Security Headers** | CSP, HSTS, X-Frame-Options via Helmet | +| **Kein offener Zugang** | Jeder API-Endpoint erfordert Authentifizierung (außer Login) | + +
--- -## Lizenz +
-[MIT](./LICENSE) © 2025–2026 ulsklyc +## FAQ + +
+Brauche ich Docker-Erfahrung? + +Nein. Die Installation besteht aus 6 Befehlen, die du einfach kopieren und einfĂŒgen kannst. Docker sorgt dafĂŒr, dass alles in einem isolierten Container lĂ€uft — du musst nichts manuell installieren oder konfigurieren. + +
+ +
+Kann ich Oikos auf einem Raspberry Pi betreiben? + +Ja. Oikos lĂ€uft auf jedem System, das Docker unterstĂŒtzt — einschließlich Raspberry Pi 4 (ARM64). Der Build dauert dort etwas lĂ€nger (~5 Min), aber die App selbst lĂ€uft flĂŒssig. + +
+ +
+Ist Oikos auch auf dem Handy nutzbar? + +Ja, Oikos ist eine Progressive Web App (PWA). Du kannst sie im Browser nutzen oder auf deinen Homescreen installieren — sie verhĂ€lt sich dann wie eine native App, inklusive Offline-Grundfunktionen. + +
+ +
+Wie viele Familienmitglieder werden unterstĂŒtzt? + +Oikos ist fĂŒr 2–6 Personen konzipiert. Technisch gibt es kein festes Limit, aber das UI ist fĂŒr kleine Familien und WGs optimiert. + +
+ +
+Ist die Kalender-Synchronisation Pflicht? + +Nein. Der integrierte Kalender funktioniert komplett eigenstÀndig. Google- und Apple-Sync sind optionale Zusatzfunktionen. + +
+ +
+Was passiert mit meinen Daten bei einem Update? + +Deine Daten liegen in einem Docker-Volume und bleiben bei Updates erhalten. Datenbank-Migrationen laufen automatisch beim Start. Trotzdem empfehlen wir vor jedem Update ein Backup. + +
+ +
+Kann ich das Design anpassen? + +Ja. Oikos verwendet CSS Custom Properties (Design Tokens) fĂŒr Farben, AbstĂ€nde und Schriften. Diese kannst du in `public/styles/tokens.css` nach deinem Geschmack anpassen — ohne Build-Step. + +
+ +
+ +--- + +
+ +
+ +**Oikos** wird mit Sorgfalt entwickelt und ist Open Source. + +Feedback, Ideen und BeitrĂ€ge sind willkommen — erstelle einfach ein [Issue](https://github.com/ulsklyc/oikos/issues). + +[MIT-Lizenz](./LICENSE) · Made with care + +
diff --git a/package.json b/package.json index f918caf..1eaea85 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "oikos", "version": "1.0.0", - "description": "Selbstgehostete Familienplaner-Web-App", + "description": "Selbstgehosteter Familienplaner — Kalender, Aufgaben, Einkauf, Essensplan, Budget und mehr. Privat, offen, ohne Abo.", "main": "server/index.js", "scripts": { "start": "node server/index.js",