yuvomi README

项目的 README,来自 github.com/ulsklyc/yuvomi。合并为一个 markdown 文件:README.md。

Yuvomi logo

Yuvomi

The self-hosted family planner.
One home instead of many subscriptions.

Tasks, calendar, budget, meals, health and more for a family, a couple or just you, on a server you own.

Latest release GitHub stars Container image ghcr.io/ulsklyc/yuvomi Runs on amd64 and arm64 MIT license

→ Take the tour on yuvomi.cloud  ·  Install  ·  Docs  ·  Changelog  ·  Auf Deutsch

20 modules  ·  27 languages  ·  0 trackers  ·  1 SQLite file  ·  256 MB RAM minimum

The Yuvomi overview: today's events, tasks and shopping for the whole family, with the family, birthdays and rewards below

Most households glue their life together from a dozen paid apps, each with its own account, its own subscription and its own copy of your data on someone else's server. Yuvomi puts all of it in one place that belongs to you, running as a container on any home server or NAS.


Many apps, one place

Instead of juggling… Yuvomi gives you
a to-do & task app Tasks - Kanban, deadlines, recurring, multi-assignment
a family calendar app Calendar - sync, subscriptions, per-event visibility
a meal planner & recipe app Meals & Recipes - weekly planner with shopping export
a grocery-list app Shopping - shared, aisle-organized lists
a budgeting & cost-splitting app Budget - income, expenses, accounts, savings goals, shared costs with debt simplification
a document manager Documents - searchable family files in folders

The modules talk to each other

This is the part a folder full of separate apps cannot do:

On the kitchen wall, in every pocket

Yuvomi wall mode on a landscape tablet: the time in large type, today's events, tasks and shopping, who is up today, the weather and one-tap kitchen timers The shared shopping list on a phone, sorted by aisle: fruit and veg, bakery, dairy, meat and fish

Invited by your family? Open the invite link your admin sent you; it works for seven days. Choose a username if the invite leaves it open, and your own password (none if your household signs in with single sign-on). Then sign in and put Yuvomi on your home screen: tap Install when the app offers it, or on iPhone and iPad choose Share, then Add to Home Screen.

More on yuvomi.cloud

The twenty modules

Switch off what your household doesn't need, and it disappears from everyone's menu. Inventory, Waste collection and Schedule start switched off.

All 20 modules, one line each
Plan - Tasks · Calendar · Rewards · Notes & Contacts · Schedule
Household - Kitchen (Meals · Recipes · Shopping · Pantry) · Housekeeping · Waste collection · Documents · Inventory
People - Health · Birthdays
Finance - Budget
Settings - Family · Reminders · API Tokens · Backup
Module In one line
Tasks Kanban board with deadlines, subtasks, recurring chores, comments and a history of who ticked off what.
Calendar Two-way Google and CalDAV sync, Outlook push, subscriptions, holidays and per-event visibility.
Rewards Points from tasks, a parent-approved catalog, an auditable ledger and pocket money per child.
Notes & Contacts Markdown sticky notes with tappable checklists, plus contacts with CardDAV sync and vCard import/export.
Schedule Rotating shifts and fixed weekly timetables, shown as an overlay in the calendar. Off by default.
Meals Weekly drag-and-drop planner with a recipe sidebar and direct export to the shopping list.
Recipes Create and scale recipes, fill meal slots, or mirror a Mealie or Tandoor instance read-only.
Shopping Shared lists sorted by aisle, with swipe gestures and an import from the meal plan.
Pantry Amounts, storage locations and best-before dates, with a reminder before something expires.
Housekeeping Household staff: schedules, check-in/out, billing, chores and supply requests.
Waste collection Pickup schedules per waste type, even "the last Friday", or a subscribed municipal ICS calendar. Off by default.
Documents Searchable family files in folders, stored locally, on WebDAV or in Google Drive.
Inventory What you own, with purchase price, warranty, linked receipts, a service log and recurring deadline reminders. Off by default.
Health Per-member vitals, medications, preventive care, labs, activity, cycle tracking, a fasting journal and a nutrition log, with trend charts.
Birthdays Birthdays and optional name days, with calendar entries, ages and reminders.
Budget Income, expenses, accounts, loans, subscriptions and shared expenses with debt simplification.
Family Member profiles with roles, and invite links where new members pick their own password.
Reminders For tasks, events, medications, warranties, best-before dates, expiring documents and pickups - in-app, push, Gotify, ntfy, webhook or email.
API Tokens Bearer tokens with an OpenAPI 3.1 spec and a built-in MCP endpoint for AI agents.
Backup Manual and scheduled backups with optional WebDAV upload and pre-restore rollback; a backup from another installation restores right in the browser.

Every module in full detail is in the spec; building your own drop-in module - with its own dashboard widgets, permissions and translations - is covered in the module guide.


Before you commit

What if this project stops? Nothing changes on your machine. It is MIT-licensed and self-hosted, and there is no server of ours anywhere in the path. The container you already pulled keeps running exactly as it does today, with or without us.

What if you want your data somewhere else? Everything lives in one SQLite file on your own disk, and copying it is the whole export, as long as documents are stored in the database. Scheduled backups write a restorable archive on top of that, and the documented API pulls anything out in whatever shape you need.

How safe is access from outside? Every account can add a second factor (TOTP, with recovery codes), and an admin can require it for the whole household; new members join through an invite link and pick their own password. With single sign-on through an OIDC provider, password login can be switched off for the household, and a lost phone is signed out from any of your other devices.

What does it cost? Nothing. Yuvomi is free and MIT-licensed. You provide the server; there is no subscription, no upsell and no paid tier.

Does it phone home? On its own, it only asks GitHub whether a newer version exists, and blocking that breaks nothing. Anything else waits until you use or switch on a feature that needs it; every connection is listed in the Install section, under Requirements, network and your data.


Install

From your NAS app store - TrueNAS SCALE, Umbrel or Unraid: search for Yuvomi in the catalog and install, no terminal.

In Home Assistant on Home Assistant OS: add the repository ulsklyc/yuvomi-home-assistant under Settings → Apps and install Yuvomi as an app (steps).

On YunoHost 12.1.17 or newer: sudo yunohost app install https://github.com/ulsklyc/yuvomi_ynh installs the YunoHost package, not in the catalog yet (steps).

On Proxmox a community helper script sets up a Debian LXC with Yuvomi in one command (steps).

With Docker on any server. The image ghcr.io/ulsklyc/yuvomi:latest is about 500 MB and runs on amd64 and arm64 (Raspberry Pi 4/5); Yuvomi needs one port, 3000 by default.

curl -O https://raw.githubusercontent.com/ulsklyc/yuvomi/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/ulsklyc/yuvomi/main/.env.example
cp .env.example .env
openssl rand -hex 32   # SESSION_SECRET
openssl rand -hex 32   # DB_ENCRYPTION_KEY

Now open .env and replace both REPLACE_WITH_… placeholders with the two values, in that order, and write the second one down: it is the database key, and a lost or changed key never opens the database again, not by you and not by us. With a placeholder left in, Yuvomi refuses to start. Or delete both lines, and Yuvomi generates them on the first start. To run without encryption, delete the DB_ENCRYPTION_KEY line and set DB_ENCRYPTION_AUTO_KEY=false.

docker compose up -d

Open http://localhost:3000 and create your admin account. Podman, Proxmox, HTTPS, backups and troubleshooting, step by step: the install guide on yuvomi.cloud and the installation guide.

Podman, Proxmox, the guided setup and the encryption key
  • Podman - fetch podman-compose.yml instead of docker-compose.yml and start it with podman compose -f podman-compose.yml up -d; it carries the SELinux :Z volume labels that RHEL, Fedora and CentOS Stream need.

  • Page does not load - docker compose logs (on Podman, podman compose -f podman-compose.yml logs) usually names the reason, and the troubleshooting guide covers the common ones.

  • Proxmox - the community helper script installs Yuvomi without Docker; to keep the Docker setup, the same steps run inside a small Debian LXC: see the Proxmox guide on yuvomi.cloud.

  • Encryption key - optional, but there is no way back. Left unset, a new installation generates one on its first start; an admin finds it under Settings → Household → Backup and restore. Write it down either way: without it, backups cannot be opened.

  • Guided setup - a localized setup wizard in your browser. It detects Docker or Podman, sets up single sign-on and scheduled backups, prepares Yuvomi for an HTTPS reverse proxy (the certificate stays with your proxy), then starts the container and creates your admin account.

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

    Open http://localhost:8090 on the server itself; the wizard answers nowhere else. From another device, open a tunnel first, ssh -L 8090:localhost:8090 user@server, then open the same address there. Needs Node.js 24.12 or newer on the host; the container ships its own Node 24.

Requirements, network and your data
  • Browsers - Chrome and Edge 105, Firefox 115, Safari 15.4 and iOS 15.4 or newer. Older Safari and iOS, Chrome before 99 and Firefox before 97 get a page that names these versions; Chrome 99 to 104 and Firefox 97 to 114 start with gaps (details).
  • Writes - four volumes you own: data, backups, modules, documents.
  • Outbound - on its own, one update check against the GitHub releases API. Block it and nothing breaks, only the hint about a newer version stays away. Everything else reaches out only when you use or switch on a feature that needs it:
    • When you use it - opening the calendar settings loads the list of holiday countries from openholidaysapi.org; finding a logo for a subscription looks up the service's website.
    • If the operator turns it on - fetching your profile picture from Gravatar sends a hash of your email address to gravatar.com or the mirror the operator chose; with web install allowed, an admin can install extension modules from GitHub.
    • Once you switch them on - weather, public holidays, exchange rates, calendar and contact sync, recipe mirrors, Immich, Paperless or Papra, push and notification channels, cloud storage and backup.
  • Your LAN - calendar subscriptions, notification channels (webhook, Gotify, ntfy), WebDAV document storage, recipe mirrors and waste-collection feeds on private or internal addresses stay blocked until you opt in (how). Paperless and Papra are the exception: they may reach the LAN out of the box.
  • Your data - one SQLite file at /data/yuvomi.db, plus the folder, WebDAV or Drive if you moved documents there.
Before you go live: health data, Google Drive sharing and GDPR

Health is not a medical device. No diagnostic claims are made. Health data is sensitive, so enable database encryption (DB_ENCRYPTION_KEY, SQLCipher).

External document storage needs its own backup. Database backups hold document metadata and links, not binaries stored in a local folder, on WebDAV, or in Google Drive; back up the selected target separately. Yuvomi visibility settings only control access through Yuvomi. Anyone with access to the connected Yuvomi/Documents Google Drive folder can view all files stored there.

Self-hosting in a GDPR context? If you run Yuvomi in the EU/EEA and process other people's data, read privacy for self-hosters before going live. It covers third-country assessments for every external service, data-processing-agreement notes, log-retention guidance and a records-of-processing template.

Coming from Oikos, or seeing oikos in an app store? Same app, renamed.

Yuvomi was renamed from Oikos to avoid a trademark conflict with an unrelated product. Same code, same data, same maintainer.

  • Old links (github.com/ulsklyc/oikos) redirect here automatically.
  • The Docker image moved to ghcr.io/ulsklyc/yuvomi; the old ghcr.io/ulsklyc/oikos keeps working, so update at your convenience.
  • Existing data and settings are fully preserved on upgrade.
  • Some catalog slugs keep the technical name oikos (e.g. Unraid oikos-…) so existing installations upgrade seamlessly. Search for Yuvomi; an entry still shown as oikos is the same app.

Under the hood


Documentation

User guide (community-maintained): @Kyrodan writes a user documentation site in his own repository. It is not part of this project and can lag behind a release, so where it and the sources above disagree, the ones above are right.



Yuvomi logo

One home for your household. Yours to keep.

Install it once. No account with us, no subscription,
and nothing of ours between your household and its data.

→ Install it  ·  Take the tour  ·  Ask a question


MIT licensed, see LICENSE. More at yuvomi.cloud.

yuvomi (ulsklyc/yuvomi)

正在搜索数据库…

2.4K ·GitHub
这是什么?Yuvomi 是一款自托管的家庭规划应用,运行在你自己掌控的服务器或 NAS 上,可以替代十几款需要单独付费的应用(任务、日历、餐食、购物、预算、健康、文档等)。
这是要下载的手机应用,还是需要自己部署的服务?它是一款自托管的渐进式 Web 应用(PWA),以 Docker 容器的形式部署在你自己的服务器或 NAS 上。没有应用商店版本,只需在浏览器中把它添加到手机主屏幕即可。
怎么把它跑起来?可以直接从 NAS 应用商店安装(TrueNAS SCALE、Umbrel、Unraid),无需使用终端;也可以运行 Docker 镜像 `ghcr.io/ulsklyc/yuvomi:latest`(Podman 同样可用),填写两个 `.env` 配置项,开放 3000 端口,然后创建管理员账户。
除了 Docker,还需要别的东西吗?主要依赖是 Docker 或 Podman。可选的引导式设置向导需要在主机上安装 Node.js 22.14+ 或 23.6+(容器本身自带 Node 24,无论如何都能运行)。另外,你的服务器需要 HTTPS,推送通知才能正常工作。
如果丢了数据库加密密钥,还能找回来吗?不能。一旦设置了 DBENCRYPTIONKEY,就无法再恢复。密钥丢失或被更改后,数据库将永远无法再打开,即使是开发者也无能为力。
它会追踪我或向外回传数据吗?设计上不会追踪用户。唯一未经提示发出的网络请求是检查 GitHub 上是否有新版本;其他对外连接(天气、节假日、Gravatar、云同步)都只有在你自己手动开启对应功能后才会发生。
这些模块与单独使用各个应用有什么不同?模块之间共享数据:餐食计划会自动生成按超市货架分区排序的购物清单;勾选完成一项家务会为完成者发放奖励积分;归档的收据则会同时关联到预算条目、共享支出和储藏室物品。
如果 Yuvomi 项目停止开发,我的部署会受影响吗?不会。它采用 MIT 许可证,并且是自托管的,没有 Yuvomi 运营的服务器参与其中,因此你正在运行的容器会像现在一样继续正常工作,无论今后是否有更新。
我的家人能在挂在厨房墙上的平板电脑上使用它吗?可以。专用的墙面模式会在共享平板账户上显示当天计划,任何人都可以点击任务并选择由谁完成;空闲时还可以显示 Immich 照片屏保。
它内置了多少种语言和模块?Yuvomi 内置 20 个可切换的模块,并提供 27 种语言的翻译。库存和垃圾收运等扩展模块默认关闭,需要家庭手动开启。
有哪些类似的项目?TREK, HolyArrs, labtether, ENZO, dockge, linkding, dashy, DnsServer
作者
ulsklyc
大小
1.3 GB
星标
2.4K
时长
7个月
提交 · 90 天