Installation
Install Yuvomi your way.
Get your self-hosted family planner running in a few minutes. Pick a one-click app-store install, a Docker setup with a handful of commands, or the guided web installer.
What you need
Yuvomi runs as a Docker or Podman container, so there is no Node.js or other runtime to install. App-store installs bring even the container engine along; only the guided web installer also needs Git and Node.js.
Docker or Podman
Packages the app so you don't need to install anything else. Free for personal use. Podman (RHEL/Fedora/CentOS Stream) works too - rootless and SELinux-ready.
Terminal
A command-line interface to type a few commands. Built into every OS - no extra install needed.
macOS: Terminal · Windows: PowerShell · Linux: bash
System
256 MB RAM minimum. Runs on a Raspberry Pi, NAS, home server, or any desktop machine.
~500 MB disk for the Docker image
Choose your platform
Seven ways to install. Pick the one that matches your setup; the result is the same private Yuvomi instance.
Docker / Podman
.env. On Portainer, see the note at the end of this path.
Download the configuration files
Run these two commands. They download the compose file and the template for your settings.
Docker
Podman (RHEL, Fedora, CentOS Stream)
On Windows: in PowerShell, type curl.exe instead of curl - Windows PowerShell answers curl with a different command. PowerShell has no openssl for step 2: run these steps in WSL, or let the web installer generate both values. notepad .env opens the file for editing.
Create your configuration
Copy the template, then print two random values:
DB_ENCRYPTION_KEY. Once set there is no way back: it cannot be changed, and a lost key never opens the database again - so back up .env somewhere safe.
Now open .env, for example with nano .env (Ctrl+O and Enter save, Ctrl+X quits), and replace both REPLACE_WITH_… placeholders: the first value goes to SESSION_SECRET, the second to DB_ENCRYPTION_KEY. Yuvomi does not start while a placeholder is still in there. To run without encryption, clear the DB_ENCRYPTION_KEY line instead.
Start the container
The first line downloads the Yuvomi image and starts it in the background - the first download takes a minute. The second follows its log.
Docker
Podman (RHEL, Fedora, CentOS Stream)
Server running on port 3000. Ctrl+C stops following the log; the container keeps running in the background. Restarting over and over instead? See troubleshooting.
docs/docker-compose.portainer.yml as a stack instead of these steps. Portainer puts no .env next to a stack, so that file lists every variable itself, and SESSION_SECRET and DB_ENCRYPTION_KEY go under the stack's environment variables - both are required there.
Compose file for Portainer
Portainer guide
Proxmox
Create an unprivileged LXC
Run this on the Proxmox host shell. The first lines refresh the template list and download the newest Debian 13 image, so no version number sits in here to go stale. nesting=1 is what lets Docker run inside an unprivileged container; without it the daemon will not start. Adjust the ID, storage and bridge to match your setup.
Prefer a full VM? That works too and needs no nesting flag: install Debian as usual and continue from step 2.
Install Docker inside the container
From Debian's own repositories, so there is no install script piped into a shell. On Debian 13 the docker-compose package brings the docker compose command the next steps use.
Download the configuration files
Still inside the container: make a folder for Yuvomi and fetch the compose file and the settings template into it.
Create your configuration
Copy the template, then print two random values:
DB_ENCRYPTION_KEY. Once set there is no way back: it cannot be changed, and a lost key never opens the database again - so back up .env somewhere safe.
Now open .env, for example with nano .env (Ctrl+O and Enter save, Ctrl+X quits), and replace both REPLACE_WITH_… placeholders: the first value goes to SESSION_SECRET, the second to DB_ENCRYPTION_KEY. Yuvomi does not start while a placeholder is still in there. To run without encryption, clear the DB_ENCRYPTION_KEY line instead.
Start the container
The first line downloads the Yuvomi image and starts it in the background - the first download takes a minute. The second follows its log.
Server running on port 3000. Ctrl+C stops following the log; the container keeps running in the background. Restarting over and over instead? See troubleshooting.
Yuvomi then answers on the container's IP at port 3000; Open Yuvomi below shows how to find it.
Web Installer
Clone the repository
Open your terminal and clone Yuvomi to a folder of your choice.
Start the installer
Run this command from the repository root. The installer server starts on port 8090.
No browser on the server, or rather stay in the terminal? bash install.sh in the same folder sets Yuvomi up as a dialog there instead (Linux and macOS): it generates the keys, starts the container and creates your admin account.
Open the wizard in your browser
Navigate to the following address. The wizard guides you through configuration, container startup, and admin account creation.
The installer only answers on the machine itself. From another device, open a tunnel first - ssh -L 8090:localhost:8090 user@server - and then open http://localhost:8090 on that device.
From source
Clone the repository
Create your configuration
Copy the template, then print two random values:
DB_ENCRYPTION_KEY. Once set there is no way back: it cannot be changed, and a lost key never opens the database again - so back up .env somewhere safe.
Now open .env, for example with nano .env (Ctrl+O and Enter save, Ctrl+X quits), and replace both REPLACE_WITH_… placeholders: the first value goes to SESSION_SECRET, the second to DB_ENCRYPTION_KEY. Yuvomi does not start while a placeholder is still in there. To run without encryption, clear the DB_ENCRYPTION_KEY line instead.
Build and start
The --build flag compiles the Docker image locally. This takes a few minutes the first time.
TrueNAS
Open the Apps Catalog
In your TrueNAS SCALE web UI, go to Apps → Discover Apps and search for Yuvomi.
Configure and install
Click Install. Set a strong value for Session Secret (required) and Database Encryption Key (optional, but irreversible once set - back it up). Adjust the port and storage paths if needed, then Install.
Open the WebUI
Once the app status shows Running, click WebUI in the Apps overview. The first visit walks you through creating your admin account directly in the browser.
Umbrel
Open the App Store
In your Umbrel dashboard, open the App Store and search for Yuvomi.
Install with one click
Click Install. Umbrel pulls the image, generates both security keys itself and starts the container - no configuration files to edit.
Open Yuvomi
Launch Yuvomi from your Umbrel home screen. The first visit walks you through creating your admin account directly in the browser.
Unraid
Open Community Applications
In Unraid, open the Apps tab (the Community Applications plugin) and search for Yuvomi.
Configure the template
Click Install. Set SESSION_SECRET (required) and DB_ENCRYPTION_KEY (optional, but irreversible once set - back it up). Adjust the WebUI port and the appdata path if needed.
Apply and open
Click Apply. Once the container is running, click the Yuvomi icon → WebUI. The first visit walks you through creating your admin account.
Two settings decide your security
One is mandatory, one is optional but permanent. Everything below this section can be changed later; the second of these two cannot.
Both live in the .env file you created next to your compose file.
On TrueNAS and Unraid both sit in the form you filled in at install, so there is no .env file to edit. You find them again in the app's configuration screen - but the database key, once set, stays as it is.
Umbrel sets both itself at install, from a secret it keeps for each app: there is nothing to fill in and no .env file to edit, and the database is encrypted from the first start.
openssl rand -hex 32 to generate a secure value.openssl rand -hex 32. Leave it empty and the database stays unencrypted. Set it and there is no way back: lose the value and the data can never be opened again, not by you and not by us.You are installing on Docker / Podman Change
Open Yuvomi
Docker, Podman or from source
Open this address in your browser. The first visit walks you through creating your admin account.
From another device, use the server's IP address or host name instead of localhost, and your own port if you changed OIKOS_HTTP_PORT.
Prefer the command line? This creates the admin account instead:
Docker
Podman
Web Installer
The wizard already created your admin account: sign in with it here. This is the address unless you gave the wizard another host or port:
Proxmox
Open the container's address in your browser. The first visit walks you through creating your admin account.
On the Proxmox host, this prints the IP of container 110 from step 1:
TrueNAS, Umbrel, Unraid
Open Yuvomi the way your app store offers it: the WebUI button on TrueNAS and Unraid, the Yuvomi tile on your Umbrel home screen. The address is your server's, not this machine's - localhost only works if you are sitting at the box itself. The first visit walks you through creating your admin account.
Once you are in, invite the rest of the family by link from the Settings page, so everyone chooses their own password.
Something not working?
Most issues have a simple fix. If you're still stuck, open an issue on GitHub.
The container keeps restarting
Almost always a placeholder: Yuvomi refuses to start while SESSION_SECRET still reads REPLACE_WITH_… from .env.example, and on a new install the same goes for DB_ENCRYPTION_KEY. The log says which one:
Docker
Podman
Put a value from openssl rand -hex 32 in its place, or clear the DB_ENCRYPTION_KEY line to run without encryption, then start it again:
Docker
Podman
Port 3000 is already in use
Another application is using port 3000. This shows which one:
Either stop it, or give Yuvomi another host port in .env, for example OIKOS_HTTP_PORT=8080 - Yuvomi then answers on http://localhost:8080, inside the container it stays on 3000. Then start it again:
Docker
Podman
Docker: Permission denied
Add your user to the Docker group, then log out and back in:
Container starts but the page is not reachable
Check the container status and logs:
Docker
Podman
Accessing from another device? Check your firewall rules.
Database encryption error
The DB_ENCRYPTION_KEY in your .env is missing or doesn't match the key used when the database was created. On a fresh install with no data yet, delete the database folder and start again:
Docker
Podman
rm -rf ./data deletes the database for good - only on a fresh install. With existing data you need the original key; nothing else opens it. down -v is no shortcut: the data sits in a host folder, not in a Docker volume, so it survives that command.Nginx shows 502 Bad Gateway
Nginx can't reach the container. Check it's running and the port matches:
Docker
Podman
Ensure the proxy_pass port in your Nginx config matches OIKOS_HTTP_PORT in your .env (default: 3000).
Go further
Once Yuvomi is running, you can set up these extras. All of them are environment variables.
You set them in the same .env file, then restart:
Docker
Podman
On TrueNAS and Unraid you add them in the app's configuration screen and restart it.
On Umbrel they need an override in the app's compose file.
HTTPS & network access
Reach Yuvomi from other devices or the internet: set up Nginx as a reverse proxy with a free Let's Encrypt certificate.
Guide →Weather widget
Show local weather on the dashboard via Open-Meteo, no API key. Set WEATHER_LAT and WEATHER_LON to your coordinates.
Calendar & contact sync
Two-way sync with Google Calendar (OAuth) and multi-account CalDAV/CardDAV (iCloud, Nextcloud, Radicale), plus a one-way push to Outlook.com via Microsoft Graph. Reminder lists (Apple Reminders, Nextcloud, Radicale) mirror two-way into Tasks or Shopping - a task created in Yuvomi can be sent to a list of your choice, and completing, editing or deleting reaches the server too.
Guide →SSO / OpenID Connect
Single sign-on via any OIDC provider (Authentik, Keycloak, Google, Microsoft Entra). Set the four OIDC_* vars and a "Sign in with SSO" button appears automatically. Serving more people than this household? OIDC_ALLOW_SIGNUP=false stops unknown identities from getting an account, while known ones still sign in and still get linked. Or go one step further: AUTH_ALLOW_PASSWORD_LOGIN=false makes SSO the only way in - no login form, no password reset.
Automated backups
Scheduled backups run by default - daily at 2 AM, 7 copies kept; disable via BACKUP_ENABLED=false. Optionally upload each backup to a WebDAV server (Nextcloud, ownCloud, Hetzner, etc.). Manage and restore in Settings → Household → Backup and restore.
Document storage
Store new document files and calendar attachments outside SQLite in a mounted host folder, on WebDAV, or in Google Drive. Drive OAuth is connected and explicitly selected later in Settings. Database backups contain metadata only, so back up every external binary target separately.
Guide →Email / SMTP
Configure an outgoing SMTP server and four things become available: the self-service "Forgot password" flow, invitations mailed straight to the new member, email as a household notification channel next to Gotify, ntfy and webhooks, and sending a shopping list to whoever is doing the run. Set the EMAIL_SMTP_* vars and BASE_URL (password-reset and invitation mails are only sent with it; reminder mails without it arrive without a link back into the app), or configure it later in Settings → Household → Email.
Live currency conversion
Budget → Subscriptions works fully without external services. Set FIXER_API_KEY to convert subscriptions billed in foreign currencies into your household base currency, with a 12-hour rate cache.
Immich photo screensaver
Let an idle wall tablet show photos from your own Immich library instead of a fixed dashboard, which burns into the panel over time. Set it up under Settings → Household → Photos and weather → Immich, or preconfigure IMMICH_URL and IMMICH_API_KEY; the key never leaves the server.
Updates
Pull the latest image and restart. Your data persists across updates.
Docker
Podman