Installation
Install Yuvomi your way.
Get your self-hosted family planner running in a few minutes. Pick a one-click app-store install, a two-command Docker setup, or the guided web installer.
What you need
Yuvomi runs as a Docker or Podman container, so you don't need to install Node.js or any other runtime. Just a container engine, and you're good to go. (App-store installs handle even this for you; the guided web installer is the one path that 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
Download the configuration files
Run these two commands. They download the Docker configuration and the template for your settings.
Create your configuration
Copy the template, then open .env in a text editor. SESSION_SECRET is required; DB_ENCRYPTION_KEY is optional but permanent.
This prints two secure values - paste one as SESSION_SECRET and the other as DB_ENCRYPTION_KEY:
.env file somewhere safe. If you lose the DB_ENCRYPTION_KEY, your data cannot be recovered.
Start the container
Docker downloads the Yuvomi image and starts it in the background. The first download takes a minute.
docker compose logs -f. You should see Server running on port 3000. The container keeps running in the background.
Create your admin account
On the first visit, Yuvomi walks you through creating your admin account right in the browser. Prefer the command line? Run the setup wizard instead:
Proxmox
Create an unprivileged LXC
Run this on the Proxmox host shell. 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.
Follow the Docker steps
From here nothing is Proxmox-specific: the Docker image path applies unchanged. Afterwards Yuvomi answers on the container's IP at port 3000 - pct exec 110 -- hostname -I on the host prints 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.
Open the wizard in your browser
Navigate to the following address. The wizard guides you through configuration, container startup, and admin account creation.
From source
Clone the repository
Create your configuration
Copy the template, then open .env in a text editor. SESSION_SECRET is required; DB_ENCRYPTION_KEY is optional but permanent.
Build and start
The --build flag compiles the Docker image locally. This takes a few minutes the first time.
Create your admin account
On the first visit, Yuvomi walks you through creating your admin account right in the browser. Prefer the command line? Run the setup wizard instead:
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 (recommended - back it up, it cannot be recovered). 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 and starts the container for you - 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.
You are installing on Docker / Podman Change
You're all set
Open your browser and navigate to:
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.
Log in with the admin credentials you just created. From the Settings page you can invite more family members by link, so they choose their own password.
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.
Your app store asked for both in its install form, so there is no .env file to edit. Change them in the app's configuration screen and restart it.
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.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 with docker compose up -d.
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 → Administration → 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 three things become available: the self-service "Forgot password" flow, 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 (reminder mails carry a link back into the app; without it they arrive without one), or configure it later in Settings → Administration → 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 → Administration → Immich, or preconfigure IMMICH_URL and IMMICH_API_KEY; the key never leaves the server.
Updates
Pull the latest image and restart: docker compose pull && docker compose up -d. Your data persists across updates.
Something not working?
Most issues have a simple fix. If you're still stuck, open an issue on GitHub.
Port 3000 is already in use
Another application is using port 3000. Either stop it, or change the port in docker-compose.yml:
Or edit docker-compose.yml and change 3000:3000 to e.g. 8080:3000.
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:
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 you can reset:
docker compose down -v deletes all data. Only use this on a fresh install with no data.Nginx shows 502 Bad Gateway
Nginx can't reach the container. Check it's running and the port matches:
Ensure the proxy_pass port in your Nginx config matches the host port in docker-compose.yml (default: 3000).