diff --git a/README.md b/README.md index f0e8a68..67949b7 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,56 @@

- - -

🏠 Oikos

- Self-hosted family planner β€” private, open, no subscription. + + + Oikos +

+ +

Oikos

+ +

+ Self-hosted family planner β€” tasks, calendars, shopping, meals, budget.
+ Your data stays on your server. No subscriptions. No tracking. No cloud lock-in.

MIT License - Node.js >=20 - Docker Ready - SQLCipher Encrypted - PWA Offline + Node.js β‰₯20 + Docker Ready + SQLCipher Encrypted + PWA Offline GitHub Stars Last Commit

-

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

-

Features Β· Quick Start Β· Configuration Β· Calendar Sync Β· Security

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

- - - - Dashboard - + Dashboard

- - - + + + - - - + + +
- - - - Tasks - -
Tasks - 		- - - - Shopping - -
Shopping - 		- - - - Budget - -
Budget - 		Tasks
Tasks		Shopping
Shopping		Budget
Budget
- - - - Notes - -
Notes - 		- - - - Contacts - -
Contacts - 		- - - - Tablet View - -
Tablet View - 		Notes
Notes		Contacts
Contacts		Calendar – Tablet
Calendar β€” Tablet
@@ -92,19 +58,23 @@ Screenshots adapt to your GitHub theme β€” switch between light and dark mode to see both variants.

+--- + ## 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 @@ PWA

-**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. + +---
-πŸ“‹ Configuration Reference +

Configuration

 ### Required @@ -216,8 +191,12 @@ Full template: [`.env.example`](.env.example)
+--- +
-πŸ“… Calendar Sync +

Calendar Sync

 + +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.
+--- + ## 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 + +---
-πŸ› οΈ Development +

Development

 ### Local Setup @@ -315,8 +296,10 @@ public/
+--- +
-πŸ’Ύ Backup & Restore +

Backup & Restore

 ### 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. +
-## Updates +--- + +
+

Updates & Family Members

 + +### 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` +
+ +--- + ## 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