Oikos

Self-hosted family planner for small households

_{Toggle GitHub light/dark mode to see both themes.}

Oikos is a self-hosted web app for families who want to organize their everyday life in one place — without cloud accounts, subscriptions, or data leaving the house. It runs as a Docker container on any home server or NAS, is accessible from every device in the household, and can be installed as a PWA on phones and tablets.

The goal is a single, private place for everything that keeps a household running: shared tasks, grocery lists, meal plans, a family calendar, budgets, and more. Each module is independent — use what fits, ignore what doesn't.

Features

Module	Description
Tasks	Shared tasks with deadlines, priorities, subtasks, and recurring schedules. Kanban board with touch-friendly one-tap status buttons. Archive completed tasks to keep lists clean. Inline reminder presets (15 min to 2 weeks before due).
Shopping Lists	Collaborative lists organized by aisle. Import ingredients from meal plans in one click.
Meal Planning	Weekly drag-and-drop planner. Export ingredient lists directly to your shopping list.
Recipes	Create, duplicate, and scale reusable recipes. Pre-fill meal slots from a recipe or save any meal as a recipe.
Calendar	Two-way sync with Google Calendar (OAuth) and Apple iCloud (CalDAV). Subscribe to any public ICS/webcal URL with per-subscription color and visibility. Overlapping timed events render side-by-side. Events support file attachments (images, PDFs, Office documents).
Documents	Upload and manage family files (PDF, images, Office documents up to 5 MB). Grid/list view, drag-and-drop upload, 14 category tags (medical, school, identity, finance, and more), per-document visibility (family, selected members, private), archive and download.
Budget	Track income and expenses with recurring entries, monthly trends, and CSV export. 35 predefined categories plus custom ones. Supports 15 currencies. Loans tab for instalment-based loan tracking with per-payment history and automatic paid-off detection.
Notes & Contacts	Colored sticky notes with Markdown support. Contact directory with vCard import/export.
Birthdays	Birthday tracker with automatic annual calendar events, age display, profile photos, and 1-day-before reminders.
Reminders	Time-based reminders on tasks and calendar events. In-app notification badge.
Family	Assign family roles, profile pictures, phone, email, and birthday per member. Family details are automatically synced to Contacts and Birthdays.
API Tokens	Named Bearer / X-API-Key tokens for external integrations. SHA-256-hashed at rest, with optional expiry. OpenAPI 3.0 spec at /api/v1/openapi.json.
Backup	Admin-only database backup and restore via the Settings UI. Download a snapshot or restore from a file upload with an automatic pre-restore rollback copy.

Design & Technology

• Liquid Glass UI — translucent surfaces, backdrop blur, module-tinted overlays, spring animations — inspired by Apple's Liquid Glass, built in pure CSS
• PWA — installable on any device, works offline, dark mode, responsive from phone to desktop
• Privacy First — SQLCipher AES-256 encrypted database, fully self-hosted, zero telemetry
• Zero Build Step — pure ES modules, no bundler, no transpiler, no framework
• Multilingual — 15 languages with automatic locale detection (de, en, es, fr, it, sv, el, ru, tr, zh, ja, ar, hi, pt, uk)

Quick Start

Option A — Web Installer (recommended)

git clone https://github.com/ulsklyc/oikos.git && cd oikos
node tools/installer/install-server.js

Open http://localhost:8090 in your browser. The wizard configures your .env, starts Docker, and creates your admin account. Requires Node.js 18+ on the host.

Option B — Pre-built image (no clone required)

curl -O https://raw.githubusercontent.com/ulsklyc/oikos/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/ulsklyc/oikos/main/.env.example
cp .env.example .env          # set SESSION_SECRET and DB_ENCRYPTION_KEY
docker compose up -d
docker compose exec oikos node setup.js

Option C — Build from source

git clone https://github.com/ulsklyc/oikos.git && cd oikos
cp .env.example .env          # set SESSION_SECRET and DB_ENCRYPTION_KEY
docker compose up -d --build
docker compose exec oikos node setup.js

Open http://localhost:3000 and sign in with the admin credentials you created above.

New to Docker? The Installation Guide covers Docker setup, HTTPS, backups, and troubleshooting step by step.

Tech Stack

Documentation

Installation	Spec & Data Model	Contributing	Security	Changelog	Backlog

License

_{Built with care for families who value privacy and simplicity.}