oikos/README.md

Oikos

Der Familienplaner, der bei dir zuhause bleibt.

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.

Funktionen · Screenshots · Installation · Konfiguration · 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
Dashboard	Dein Tagesstart auf einen Blick: Wetter, anstehende Termine, dringende Aufgaben, heutiges Essen und angepinnte Notizen. Alles in einem personalisierten Feed.
Aufgaben	Aufgaben erstellen, priorisieren und Familienmitgliedern zuweisen. Mit Teilaufgaben, Wiederholungen (täglich/wöchentlich/monatlich), Statusfiltern und Swipe-Gesten auf dem Handy.
Einkauf	Mehrere 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.
Essensplan	Wochenplan für Frühstück, Mittag, Abend und Snacks. Zutaten pro Mahlzeit erfassen und mit einem Klick auf die Einkaufsliste übernehmen.
Kalender	Familienkalender mit vier Ansichten (Monat, Woche, Tag, Agenda). Farbcodiert pro Person. Wiederkehrende Termine. Optional mit Google Calendar und Apple iCloud synchronisierbar.
Pinnwand	Farbige Sticky Notes im Masonry-Grid. Für schnelle Erinnerungen, Nachrichten an die Familie oder Ideen. Mit Markdown-Light (fett, kursiv, Listen).
Kontakte	Wichtige Kontakte der Familie — Kinderarzt, Schule, Handwerker, Versicherung. Mit Direktanruf per Tap, E-Mail-Links und Kartennavigation.
Budget	Einnahmen und Ausgaben tracken, nach Kategorien auswerten, Monate vergleichen. Mit wiederkehrenden Buchungen (Miete, Gehalt) und CSV-Export.
Einstellungen	Dark Mode (System / Hell / Dunkel), Passwort ändern, Kalender-Sync verwalten, Familienmitglieder anlegen.

---

Screenshots

Light Mode

Dashboard Wetter, Termine, Aufgaben, Essen	Aufgaben Prioritäten, Zuweisung, Filter	Kalender Monatsansicht, Tagesdetails
Einkauf Mehrere Listen, Kategorien	Essensplan Wochenplan, Zutaten

Dark Mode

Dashboard	Aufgaben	Kalender
Einkauf	Essensplan

_{Dark Mode folgt automatisch deiner Systemeinstellung oder lässt sich manuell unter Einstellungen umschalten.}

---

Technik auf einen Blick

Oikos setzt bewusst auf einen minimalen, wartungsarmen Stack — keine 200 npm-Pakete, kein Build-Step, kein Framework-Lock-in.

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)

---

Installation

Zeitaufwand: ca. 10–15 Minuten, auch wenn du Docker zum ersten Mal nutzt.

Voraussetzungen

Du brauchst einen Linux-Server (oder eine lokale Linux-Maschine / VM / Raspberry Pi) mit:

• Docker und Docker Compose — Installationsanleitung (offizielle Docs)
• 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 herunterladen

Öffne ein Terminal auf deinem Server und führe aus:

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 — Konfiguration anlegen

cp .env.example .env

Jetzt die .env-Datei bearbeiten — z.B. mit nano:

nano .env

Mindestens diese zwei Felder musst du ausfüllen:

# 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).
# Ebenfalls mit openssl generieren. Leer lassen = keine Verschlüsselung.
DB_ENCRYPTION_KEY=hier_einen_starken_schluessel_eintragen

Schlüssel generieren — so geht's

Führe diesen Befehl zweimal aus und kopiere die Ausgabe jeweils in die .env:

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 erklärt. Für den Start brauchst du nur die zwei Pflichtfelder.

Speichern in nano: Strg+O, Enter, Strg+X.

---

Schritt 3 — App starten

docker compose up -d --build

Der erste Build kompiliert SQLCipher und dauert 2–3 Minuten. Alle weiteren Starts sind deutlich schneller.

Prüfe, ob der Container läuft:

docker compose ps

Du solltest sehen, dass der Container oikos den Status Up hat. Falls etwas nicht stimmt:

docker compose logs oikos --tail=30

Wenn in den Logs steht:

[Oikos] Server läuft auf Port 3000

...ist alles bereit.

---

Schritt 4 — Ersten Benutzer anlegen

docker compose exec oikos node setup.js

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

Im Browser aufrufen:

http://<deine-server-ip>:3000

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:

SESSION_SECURE=false

Dann Container neu starten: docker compose down && docker compose up -d

Entferne diese Zeile wieder, sobald du HTTPS eingerichtet hast (siehe nächster Schritt).

---

Schritt 6 — HTTPS einrichten (empfohlen)

Für den dauerhaften Betrieb sollte Oikos hinter einem Reverse Proxy mit SSL laufen. Das schützt Passwörter und Sessions auf dem Transportweg.

Variante A: Nginx Proxy Manager (empfohlen für Einsteiger)

Nginx Proxy Manager ist ein benutzerfreundlicher Reverse Proxy mit Web-Oberfläche.

1. Nginx Proxy Manager installieren (falls noch nicht vorhanden) — Anleitung
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 einfügen

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 und passe die Domain an:

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:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d oikos.deine-domain.de

Nginx neu laden:

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	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:

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)	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 im Container
DB_PATH	/data/oikos.db	Datenbankpfad im Container
SYNC_INTERVAL_MINUTES	15	Kalender-Sync-Intervall (in Minuten)

Die vollständige Vorlage mit allen Optionen findest du in .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

Schritt-für-Schritt-Anleitung

1. Google Cloud Projekt anlegen

1. Gehe zu 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

2. In Oikos konfigurieren

In der .env eintragen:

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)

Schritt-für-Schritt-Anleitung

1. App-spezifisches Passwort erstellen

Apple erfordert ein eigenes Passwort für Drittanbieter-Apps:

1. Gehe zu 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:

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 verwalten

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):

docker compose exec oikos node setup.js

---

Updates

cd oikos
git pull
docker compose up -d --build

Das war's. Datenbank-Migrationen laufen automatisch beim Start. Alle Daten im Docker-Volume bleiben erhalten.

Empfehlung: Vor jedem Update ein Backup erstellen.

---

Datensicherung

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

Das erstellt eine komprimierte Sicherung der gesamten Datenbank im aktuellen Verzeichnis.

Backup wiederherstellen

docker compose down
docker run --rm \
  -v oikos_oikos_data:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/oikos-backup-YYYYMMDD.tar.gz -C /
docker compose up -d

Ersetze YYYYMMDD durch das Datum deines Backups (z.B. 20260326).

---

Lokale Entwicklung

Falls du Oikos weiterentwickeln oder anpassen möchtest:

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:

npm test           # 146 Tests, 7 Suiten (In-Memory-SQLite, kein laufender Server nötig)

---

Sicherheit

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)

---

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.

MIT-Lizenz · Made with care