Aktualisieren von README.md

2026-03-29 01:17:56 +01:00
parent 8e01d4c749
commit 396050e2cf
1 changed files with 103 additions and 107 deletions
@@ -1,90 +1,56 @@
 <p align="center">
-  <!-- Logo: Replace with your logo once created (recommended: SVG, 128×128 or 256×256) -->
-  <!-- <img src="public/logo.svg" alt="Oikos Logo" width="128"> -->
-  <h1>🏠 Oikos</h1>
-  <strong>Self-hosted family planner — private, open, no subscription.</strong>
+  <!-- Replace with your logo: recommended 120–160px, SVG or PNG, transparent background -->
+  <!-- <img src="docs/logo.svg" alt="Oikos" width="140"> -->
+  <img src="https://img.shields.io/badge/%F0%9F%8F%A0-Oikos-007AFF?style=for-the-badge&labelColor=F5F5F7" alt="Oikos" height="48">
+</p>
+
+<h1 align="center">Oikos</h1>
+
+<p align="center">
+  <strong>Self-hosted family planner — tasks, calendars, shopping, meals, budget.</strong><br>
+  Your data stays on your server. No subscriptions. No tracking. No cloud lock-in.
 </p>

 <p align="center">
  <a href="https://github.com/ulsklyc/oikos/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT License"></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js >=20">
-  <img src="https://img.shields.io/badge/docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white" alt="Docker Ready">
-  <img src="https://img.shields.io/badge/SQLCipher-AES--256-003B57?style=flat-square&logo=sqlite&logoColor=white" alt="SQLCipher Encrypted">
-  <img src="https://img.shields.io/badge/PWA-offline--capable-5A0FC8?style=flat-square&logo=pwa&logoColor=white" alt="PWA Offline">
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js ≥20"></a>
+  <a href="https://www.docker.com"><img src="https://img.shields.io/badge/docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white" alt="Docker Ready"></a>
+  <a href="https://www.zetetic.net/sqlcipher/"><img src="https://img.shields.io/badge/SQLCipher-AES--256-003B57?style=flat-square&logo=sqlite&logoColor=white" alt="SQLCipher Encrypted"></a>
+  <a href="https://web.dev/progressive-web-apps/"><img src="https://img.shields.io/badge/PWA-offline--capable-5A0FC8?style=flat-square&logo=pwa&logoColor=white" alt="PWA Offline"></a>
  <a href="https://github.com/ulsklyc/oikos/stargazers"><img src="https://img.shields.io/github/stars/ulsklyc/oikos?style=flat-square&color=f5c542" alt="GitHub Stars"></a>
  <a href="https://github.com/ulsklyc/oikos/commits/main"><img src="https://img.shields.io/github/last-commit/ulsklyc/oikos?style=flat-square" alt="Last Commit"></a>
 </p>

-<p align="center">
-  Oikos is a self-hosted family organizer for 2–6 people. Tasks, calendars, shopping lists, meal plans, budget tracking, and more — all running on your own server. No cloud dependency. No data leaves your network. No tracking.
-</p>
-
 <p align="center">
  <a href="#features">Features</a> · <a href="#quick-start">Quick Start</a> · <a href="#configuration">Configuration</a> · <a href="#calendar-sync">Calendar Sync</a> · <a href="#security">Security</a>
 </p>

 ---

+Oikos is a self-hosted family organizer for 2–6 people. Tasks, calendars, shopping lists, meal plans, budget tracking, notes, and contacts — all running on your own server inside a single Docker container. No cloud dependency, no telemetry, no data leaves your network.
+
+Built with Express.js, SQLite (optionally encrypted via SQLCipher), and vanilla JavaScript — no frontend framework, no build step. Works offline as a PWA on phones and tablets.
+
+Oikos is **not** a SaaS product, not a team collaboration tool, and not designed for public multi-tenant use. It is a private tool for one family on one server.
+
+---
+
+## Screenshots
+
 <p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/tablet-dark/tablet-dark-dashboard.png">
-    <source media="(prefers-color-scheme: light)" srcset="docs/screenshots/tablet-light/tablet-light-dashboard.png">
-    <img src="docs/screenshots/tablet-light/tablet-light-dashboard.png" alt="Dashboard" width="800">
-  </picture>
+  <img src="docs/screenshots/tablet-light/tablet-light-dashboard.png" alt="Dashboard" width="720">
 </p>

 <table>
  <tr>
-    <td align="center" width="33%">
-      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/mobile-dark/mobile-dark-tasks.png">
-        <source media="(prefers-color-scheme: light)" srcset="docs/screenshots/mobile-light/mobile-light-tasks.png">
-        <img src="docs/screenshots/mobile-light/mobile-light-tasks.png" alt="Tasks" width="240">
-      </picture>
-      <br><strong>Tasks</strong>
-    </td>
-    <td align="center" width="33%">
-      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/mobile-dark/mobile-dark-household.png">
-        <source media="(prefers-color-scheme: light)" srcset="docs/screenshots/mobile-light/mobile-light-household.png">
-        <img src="docs/screenshots/mobile-light/mobile-light-household.png" alt="Shopping" width="240">
-      </picture>
-      <br><strong>Shopping</strong>
-    </td>
-    <td align="center" width="33%">
-      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/mobile-dark/mobile-dark-budget.png">
-        <source media="(prefers-color-scheme: light)" srcset="docs/screenshots/mobile-light/mobile-light-budget.png">
-        <img src="docs/screenshots/mobile-light/mobile-light-budget.png" alt="Budget" width="240">
-      </picture>
-      <br><strong>Budget</strong>
-    </td>
+    <td align="center"><img src="docs/screenshots/mobile-light/mobile-light-tasks.png" alt="Tasks" width="220"><br><strong>Tasks</strong></td>
+    <td align="center"><img src="docs/screenshots/mobile-light/mobile-light-shopping.png" alt="Shopping" width="220"><br><strong>Shopping</strong></td>
+    <td align="center"><img src="docs/screenshots/mobile-light/mobile-light-budget.png" alt="Budget" width="220"><br><strong>Budget</strong></td>
  </tr>
  <tr>
-    <td align="center">
-      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/mobile-dark/mobile-dark-notes.png">
-        <source media="(prefers-color-scheme: light)" srcset="docs/screenshots/mobile-light/mobile-light-notes.png">
-        <img src="docs/screenshots/mobile-light/mobile-light-notes.png" alt="Notes" width="240">
-      </picture>
-      <br><strong>Notes</strong>
-    </td>
-    <td align="center">
-      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/mobile-dark/mobile-dark-contacts.png">
-        <source media="(prefers-color-scheme: light)" srcset="docs/screenshots/mobile-light/mobile-light-contacts.png">
-        <img src="docs/screenshots/mobile-light/mobile-light-contacts.png" alt="Contacts" width="240">
-      </picture>
-      <br><strong>Contacts</strong>
-    </td>
-    <td align="center">
-      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/tablet-dark/tablet-dark-notes.png">
-        <source media="(prefers-color-scheme: light)" srcset="docs/screenshots/tablet-light/tablet-light-notes.png">
-        <img src="docs/screenshots/tablet-light/tablet-light-notes.png" alt="Tablet View" width="240">
-      </picture>
-      <br><strong>Tablet View</strong>
-    </td>
+    <td align="center"><img src="docs/screenshots/mobile-light/mobile-light-notes.png" alt="Notes" width="220"><br><strong>Notes</strong></td>
+    <td align="center"><img src="docs/screenshots/mobile-light/mobile-light-contacts.png" alt="Contacts" width="220"><br><strong>Contacts</strong></td>
+    <td align="center"><img src="docs/screenshots/tablet-light/tablet-light-calendar.png" alt="Calendar – Tablet" width="220"><br><strong>Calendar — Tablet</strong></td>
  </tr>
 </table>

@@ -92,19 +58,23 @@
  <sub>Screenshots adapt to your GitHub theme — switch between light and dark mode to see both variants.</sub>
 </p>

+---
+
 ## Features

 | | Module | What it does | Highlights |
 |---|---|---|---|
-| 📋 | **Dashboard** | At-a-glance overview of your family's day | Weather widget, upcoming events, urgent tasks, today's meals, pinned notes |
-| ✅ | **Tasks** | Shared to-do lists with accountability | List + Kanban views, subtasks, recurring tasks (RRULE), swipe gestures, priority levels |
-| 🛒 | **Shopping** | Collaborative grocery lists | Multiple lists, aisle-grouped categories, auto-import from meal plan |
-| 🍽️ | **Meals** | Weekly meal planning | Week view (Mon–Sun), ingredient management, one-click export to shopping list |
-| 📅 | **Calendar** | Family calendar with external sync | Month/week/day/agenda views, Google Calendar & Apple iCloud sync (two-way) |
-| 📌 | **Notes** | Shared family pinboard | Colored sticky notes, pinning, lightweight Markdown (bold, italic, lists) |
-| 👥 | **Contacts** | Important family contacts | Category filters, tap-to-call, tap-to-email, map links for addresses |
-| 💰 | **Budget** | Income & expense tracking | Category breakdown, month-over-month comparison, CSV export |
-| ⚙️ | **Settings** | User & sync management | Password changes, calendar sync config, family member admin |
+| 📋 | **Dashboard** | At-a-glance overview of your family's day | Weather widget · upcoming events · urgent tasks · today's meals · pinned notes |
+| ✅ | **Tasks** | Shared to-do lists with accountability | List + Kanban views · subtasks · recurring tasks (RRULE) · swipe gestures · priority levels |
+| 🛒 | **Shopping** | Collaborative grocery lists | Multiple lists · aisle-grouped categories · auto-import from meal plan |
+| 🍽️ | **Meals** | Weekly meal planning with ingredients | Week view (Mon–Sun) · ingredient management · one-click export to shopping list |
+| 📅 | **Calendar** | Family calendar with external sync | Month/week/day/agenda views · Google Calendar & Apple iCloud two-way sync |
+| 📌 | **Notes** | Shared family pinboard | Colored sticky notes · pinning · lightweight Markdown (bold, italic, lists) |
+| 👥 | **Contacts** | Important family contacts | Category filters · tap-to-call · tap-to-email · map links for addresses |
+| 💰 | **Budget** | Income & expense tracking | Category breakdown · month-over-month comparison · CSV export |
+| ⚙️ | **Settings** | User & sync management | Password changes · calendar sync config · family member admin |
+
+---

 ## Tech Stack

@@ -116,26 +86,29 @@
  <img src="https://img.shields.io/badge/PWA-5A0FC8?style=flat-square&logo=pwa&logoColor=white" alt="PWA">
 </p>

-**Backend:** Node.js, Express, SQLite via better-sqlite3, optional SQLCipher encryption (AES-256), bcrypt, express-session, Helmet
+| Layer | Technology |
+|---|---|
+| **Server** | Node.js ≥ 20 · Express · better-sqlite3 · bcrypt · Helmet |
+| **Database** | SQLite with optional SQLCipher encryption (AES-256) |
+| **Frontend** | Vanilla JavaScript ES modules — no framework, no build step. Web Components (`oikos-*`). Lucide Icons (self-hosted SVG sprite) |
+| **Auth** | Session-based · httpOnly cookies · CSRF double-submit · express-session |
+| **Deployment** | Docker + Docker Compose · Nginx reverse proxy · Let's Encrypt SSL |
+| **Integrations** | Google Calendar API v3 (OAuth 2.0) · Apple iCloud CalDAV (tsdav) · OpenWeatherMap |

-**Frontend:** Vanilla JavaScript ES modules — no framework, no build step, no bundler. Web Components for reusable UI. Lucide Icons (self-hosted SVG sprite).
-
-**Deployment:** Docker + Docker Compose, Nginx reverse proxy with SSL, PWA with service worker for offline support
-
-**Integrations:** Google Calendar API v3 (OAuth 2.0), Apple iCloud CalDAV via tsdav, OpenWeatherMap
+---

 ## Quick Start

 **Prerequisites:** Docker + Docker Compose on a Linux server.

-**1. Clone**
+### 1. Clone

 ```bash
 git clone https://github.com/ulsklyc/oikos.git
 cd oikos
 ```

-**2. Configure**
+### 2. Configure

 ```bash
 cp .env.example .env
@@ -148,7 +121,7 @@ SESSION_SECRET=your-random-string-at-least-32-chars
 DB_ENCRYPTION_KEY=your-sqlcipher-aes256-key
 ```

-**3. Start**
+### 3. Start

 ```bash
 docker compose up -d
@@ -156,22 +129,24 @@ docker compose up -d

 First build takes 2–3 minutes (compiles SQLCipher against better-sqlite3).

-**4. Create admin account**
+### 4. Create admin account

 ```bash
 docker compose exec oikos node setup.js
 ```

-Interactive script — sets up username, display name, and password. This admin can create additional family members.
+Interactive script — sets up username, display name, and password. This admin can create additional family members from the settings page.

-**5. Open**
+### 5. Open

 Navigate to `http://localhost:3000` — or your configured domain after Nginx setup.

-> See [`nginx.conf.example`](nginx.conf.example) for a ready-to-use reverse proxy configuration. If you use [Nginx Proxy Manager](https://nginxproxymanager.com), paste the contents into the "Advanced" tab. Make sure `X-Forwarded-Proto` is set so session cookies work correctly in production.
+> **Nginx:** See [`nginx.conf.example`](nginx.conf.example) for a production-ready config. If you use [Nginx Proxy Manager](https://nginxproxymanager.com), paste the contents into the "Advanced" tab. Make sure `X-Forwarded-Proto` is set so session cookies work correctly in production.
+
+---

 <details>
-<summary><strong>📋 Configuration Reference</strong></summary>
+<summary><h2>Configuration</h2></summary>

 ### Required

@@ -216,8 +191,12 @@ Full template: [`.env.example`](.env.example)

 </details>

+---
+
 <details>
-<summary><strong>📅 Calendar Sync</strong></summary>
+<summary><h2>Calendar Sync</h2></summary>
+
+Oikos syncs bidirectionally with Google Calendar and Apple iCloud. External events are visually distinguished in the UI. On conflict, the external source wins.

 ### Google Calendar

@@ -237,11 +216,7 @@ Full template: [`.env.example`](.env.example)
 6. Restart: `docker compose up -d`
 7. In Oikos: **Settings → Calendar Sync → Connect Google**

-**Sync behavior:**
- Initial sync pulls events from 3 months ago to 12 months ahead
- Subsequent syncs use Google's `syncToken` for incremental updates
- Local events push to Google automatically
- Conflicts: Google wins on simultaneous edits
+**Sync behavior:** Initial sync pulls events from 3 months ago to 12 months ahead. Subsequent syncs use Google's `syncToken` for incremental updates. Local events push to Google automatically. Conflicts: Google wins on simultaneous edits.

 ### Apple Calendar (iCloud CalDAV)

@@ -259,19 +234,25 @@ The sync button appears automatically in Settings.

 </details>

+---
+
 ## Security

- **Sessions:** `httpOnly`, `SameSite=Strict`, `Secure` in production, 7-day TTL
- **CSRF:** Double Submit Cookie pattern on all state-changing requests
- **Passwords:** bcrypt with cost factor 12
- **Rate limiting:** 5 login attempts/min per IP, 300 API requests/min per IP
- **Headers:** Content Security Policy via Helmet (`self`-only)
- **Encryption:** Optional SQLCipher AES-256 database encryption
- **Access control:** No API endpoint accessible without session auth (except `/api/v1/auth/login`)
- **No public registration:** Only admins can create user accounts
+Oikos is designed to run on a private server behind SSL. No public endpoints exist except the login page.
+
+- **Sessions** — `httpOnly`, `SameSite=Strict`, `Secure` in production, 7-day TTL
+- **CSRF** — Double-submit cookie pattern on all state-changing requests
+- **Passwords** — bcrypt with cost factor 12
+- **Rate limiting** — 5 login attempts/min, 300 API requests/min per IP
+- **Headers** — Strict Content Security Policy via Helmet (`self`-only)
+- **Encryption** — Optional SQLCipher AES-256 database encryption at rest
+- **Access control** — No API endpoint accessible without session auth (except `/api/v1/auth/login`)
+- **No public registration** — Only admins can create user accounts
+
+---

 <details>
-<summary><strong>🛠️ Development</strong></summary>
+<summary><h2>Development</h2></summary>

 ### Local Setup

@@ -315,8 +296,10 @@ public/

 </details>

+---
+
 <details>
-<summary><strong>💾 Backup & Restore</strong></summary>
+<summary><h2>Backup & Restore</h2></summary>

 ### Backup

@@ -338,18 +321,25 @@ docker run --rm \
 docker compose up -d
 ```

+Database migrations run automatically on startup. Data in the `oikos_data` volume is preserved across container rebuilds.
+
 </details>

-## Updates
+---
+
+<details>
+<summary><h2>Updates & Family Members</h2></summary>
+
+### Updating Oikos

 ```bash
 git pull
 docker compose up -d --build
 ```

-Database migrations run automatically on startup. Data in the `oikos_data` volume is preserved.
+Migrations run automatically. Your data volume stays intact.

-## Family Members
+### Adding Family Members

 Only admins can create new accounts — there is no public registration endpoint.

@@ -357,12 +347,18 @@ Only admins can create new accounts — there is no public registration endpoint

 **Via CLI:** `docker compose exec oikos node setup.js`

+</details>
+
+---
+
 ## Contributing

 Contributions are welcome. If you find a bug or have a feature idea, [open an issue](https://github.com/ulsklyc/oikos/issues). Pull requests are appreciated — please keep the vanilla JS constraint in mind (no frameworks, no build tools).

 A `CONTRIBUTING.md` with detailed guidelines is coming soon.

+---
+
 ## License

 [MIT](LICENSE) © 2025 ulsklyc