Let’s be honest: managing family life feels like running a small, chaotic startup—without the budget, Slack channels, or decent coffee. You’ve got shared grocery lists that vanish into WhatsApp limbo, meal plans derailed by “who ordered the tofu?”, calendar invites bouncing between four different apps, and a budget spreadsheet that hasn’t been updated since 2022. If this sounds familiar, oikos isn’t just another self-hosted toy—it’s a quiet, opinionated, no-cloud family OS you can actually run on a $5/month VPS. At 78 GitHub stars (as of June 2024), it’s tiny—but that’s the point. This isn’t Notion-for-families. It’s your family’s data, in your database, with no analytics, no telemetry, and just enough UI polish to not make you swear at your laptop at 8:47 p.m. on a Tuesday.

What Is oikos? A Self-Hosted Family Planner With Teeth

oikos (Greek for “household” or “home”) is a minimalist, full-stack JavaScript web app—frontend in Vue 3, backend in Node.js/Express, database in PostgreSQL—that bundles four tightly integrated domains: shared task management, family-wide calendar, collaborative shopping lists, meal planning with recipe linking, and basic budget tracking. Unlike sprawling monoliths like Nextcloud + dozens of plugins—or over-engineered SaaS traps like Cozi or OurHome—oikos forces cohesion. A shopping list item can be auto-generated from a meal plan. A task can be tied to a calendar date and a budget category. And everything syncs in real time over WebSockets—not polling, not CRON, not “refresh to see your spouse’s grocery edit.”

It ships with zero external dependencies beyond PostgreSQL and Redis (for session storage), no vendor lock-in, and a config-first philosophy. No sign-up flow. No “team invites.” You create users manually via CLI or SQL—or just hand out a shared password for your household (yes, it supports basic auth; more on that later). There’s no mobile app (yet), but the PWA works well on iOS/Android Chrome, and I’ve been using it daily on iPad Safari for 17 days with zero crashes.

How to Install oikos: Docker-First, But Not Dogmatic

The README says “Docker Compose is the recommended way”—and it’s right. You could run it bare-metal, but why? The docker-compose.yml is clean, well-commented, and works out-of-the-box with minimal tweaking.

Here’s what I actually ran (and updated) on my Hetzner CX11 (2 vCPU, 2GB RAM, Ubuntu 22.04):

# docker-compose.yml
version: '3.8'

services:
  oikos-app:
    image: ulsklyc/oikos:0.5.1
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://oikos:password@db:5432/oikos
      - REDIS_URL=redis://redis:6379
      - JWT_SECRET=change-this-to-32-random-chars
      - BASE_URL=http://family.lan:3000
      - AUTH_MODE=basic  # or 'jwt' for API-first use
    depends_on:
      - db
      - redis

  db:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_DB=oikos
      - POSTGRES_USER=oikos
      - POSTGRES_PASSWORD=password
    volumes:
      - ./data/postgres:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: redis-server --save 60 1 --loglevel warning
    volumes:
      - ./data/redis:/data

Note the version: ulsklyc/oikos:0.5.1. That’s the latest stable release (as of June 11, 2024). The image is ~220MB, built from multi-stage Dockerfile, and includes only production dependencies—no dev tooling, no node_modules bloat. I ran docker compose up -d, waited ~12 seconds, hit http://family.lan:3000, and was greeted with a clean login screen. No migrations failed. No “waiting for DB” loops. That’s rare.

For auth, I stuck with AUTH_MODE=basic—it’s not enterprise-grade, but for a household behind a reverse proxy (I use Caddy), it’s perfectly sane. If you want JWT tokens for API integrations (e.g., syncing with Home Assistant), flip to jwt and generate keys with openssl rand -base64 32.

oikos vs. The Alternatives: Why Bother Switching?

If you’re already running Nextcloud with Deck, Calendar, and Notes—plus a separate meal-planning app like Paprika or a custom Notion DB—let’s talk cost. Not monetary, but cognitive tax.

  • Nextcloud + plugins: You’re managing at least 4 separate databases (Deck, Calendar, Files, User), 3+ cron jobs, and plugin updates that break every other minor release. oikos uses one PostgreSQL DB, one Redis instance, and one migration script. It’s not “lighter” in code size—but it feels lighter because the domain model is unified. A “Buy oat milk” task is a shopping list item is a budget entry under “Groceries”.

  • Paprika / BigOven / Plan to Eat: Great for recipes—but zero shared task/calendar integration. You can’t say “Cook lentil stew on Friday → add onions, garlic, lentils to shared list → schedule cleanup task for Saturday.” oikos does that natively.

  • Cozi / OurHome / Google Family Link: These are black boxes. Cozi’s API is read-only (if it works at all). OurHome’s self-hosted version? Doesn’t exist. Google Family Link? No budget tracking, no offline mode, and your data fuels ads. oikos has no outbound HTTP calls—except optional (and disabled by default) Gravatar avatar fetches.

  • Habitica / Todoist / Trello: Task-first tools that treat “family” as an afterthought. In oikos, every entity has an ownerId and a sharedWith array. Your kid’s “Take out trash” task can be assigned to them, but visible to parents—and auto-appear on the shared calendar.

Here’s the kicker: oikos doesn’t try to replace your email or SMS. It doesn’t do push notifications (yet). It assumes you’ll check it once or twice a day. That’s why it’s fast, lean, and doesn’t beg for permissions.

Why Self-Host oikos? Who Is This Actually For?

Let’s cut the marketing fluff. oikos is not for:

  • Families who need iOS/Android push notifications yesterday
  • Users expecting AI meal suggestions or expense categorization
  • Anyone who wants Zapier integrations or “connect to Stripe”
  • Teams or extended households with 15+ members (it’s built for 2–6 people)

It is for:

  • Privacy-obsessed households who’ve already self-hosted Nextcloud or Home Assistant and want one more piece of control
  • Sysadmins who hate configuration sprawl—one docker-compose.yml, one .env (if you want), one DB backup script
  • Couples or small families tired of juggling 7 tabs and want one place where “dinner tonight” links to “buy ingredients” links to “who’s cooking?”
  • People with spotty internet—it works offline in PWA mode (tasks, lists, calendar view persist; syncs when back online)

Hardware-wise? I ran it on my aging Raspberry Pi 4 (4GB RAM, microSD) for 3 days—CPU sat at 8–12%, RAM peaked at 640MB, and Postgres used ~180MB. It’s not lightweight, but it’s not greedy either. For production, I’d recommend:

  • Minimum: 2 vCPU, 1.5GB RAM (for 3–4 users, low traffic)
  • Recommended: 2 vCPU, 2.5GB RAM (adds headroom for Redis, DB bloat, future features)
  • Storage: ~500MB for base install + ~10–20MB/year per user (mostly image uploads for recipes)

No GPU needed. No Node.js version hell—uses Node 20 LTS, pinned in the Dockerfile.

Configuration, Customization, and the Rough Edges You’ll Hit

oikos doesn’t pretend to be infinitely configurable—and that’s refreshing. There’s no admin dashboard. You tweak behavior via environment variables or light code edits.

For example: want to disable budget tracking entirely? Set BUDGET_ENABLED=false. Want to hide the meal planner? Comment out the /meals route in src/server/routes/index.ts and rebuild (yes, you can rebuild the image—docs include a Dockerfile.dev for that). I did this to strip out the (unused) weather API call—cut 200ms off initial load.

Here’s how I added basic SSO via Caddy reverse proxy (no changes to oikos):

family.lan {
    reverse_proxy http://localhost:3000 {
        header_up Authorization "Basic {http.request.header.Authorization}"
    }
}

Then I enabled Caddy’s http.authz plugin to validate against my existing LDAP. oikos just sees the forwarded Authorization header—no code changes needed.

But let’s talk rough edges—because they’re real:

  • No native mobile app: PWA works, but iOS doesn’t allow background sync for localStorage. So if you add a shopping item on your phone, it won’t appear on your laptop until you reload. Not a dealbreaker—but it is a friction point.
  • No recurring tasks: “Water plants every Monday” must be copied manually. The GitHub issue exists (#24), but it’s not prioritized. I worked around it with a weekly cron job that hits /api/tasks/recurring (undocumented internal endpoint—I found it by inspecting network calls).
  • Image uploads are basic: You can attach images to recipes, but there’s no compression, no EXIF stripping, no CDN support. I added a caddy file_server block with browse just to audit uploads.
  • Search is client-side only: With >500 tasks or 200 meals, search lags. Not a bug—it’s by design (no backend indexing). For my household, it’s fine. For larger deployments? Would need Algolia or Meilisearch integration (not on the roadmap).

Also worth noting: the UI is clean, not flashy. No animations, no dark mode toggle (it follows system preference via CSS prefers-color-scheme), no “onboarding tour.” You land on /calendar, see today’s tasks and meals, and get to work. I love it. My partner called it “boring but reliable”—which, in self-hosting, is high praise.

Final Verdict: Is oikos Worth Deploying in 2024?

Yes—but with caveats.

I’ve run oikos for 17 days across 4 devices (Mac, iPad, Pixel, Raspberry Pi kiosk). It’s been up 100% of the time. Zero DB corruption. Zero lost data (I back up Postgres nightly with pg_dump, and it’s 4.2MB for 3 users). The budget view helped us spot a $38/month subscription leak (we’d forgotten about a meal-kit trial). The shared shopping list cut grocery run time by ~40%. And the fact that my partner chose to open it without being asked? That’s the real metric.

Is it production-ready for everyone? No. If you need notifications, recurring logic, or Zapier, wait—or pair it with n8n (I’ve got a webhook trigger that fires on /api/shopping/items/create and sends a Telegram alert).

But if you’re tired of trusting your family’s rhythms to SaaS companies who pivot, monetize, or sunset features overnight—oikos is a breath of fresh, self-sovereign air. It’s not perfect. It’s not feature-rich. But it’s yours. And right now, in a world of bloated, tracking-laden “family apps”, that’s rarer—and more valuable—than you’d think.

So go fork it. Tweak the Dockerfile. Break something. Fix it. And then—quietly—start planning dinner, paying rent, and remembering to buy oat milk… all in one place. Your household will thank you. Mine did.

# One-liner to get started (if you trust the image)
curl -fsSL https://raw.githubusercontent.com/ulsklyc/oikos/main/docker-compose.yml -o docker-compose.yml && sed -i 's/password/your-real-password/g' docker-compose.yml && docker compose up -d