Docker or Podman
Packages the app so you do not need to install anything else. Free for personal use. Podman (RHEL/Fedora/CentOS Stream) works too - rootless and SELinux-ready.
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.
~10 minutes
What you need
Yuvomi runs as a Docker or Podman container, so you do not need to install Node.js or any other runtime. Just a container engine, and you are 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.
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.
In a terminal
One-click app store
Current path
Docker / Podman
No Git, no build step - just two files and a single command. Requires only Docker or Podman. For Podman use podman-compose.yml.
1
Download the configuration files
Run these two commands. They download the Docker configuration and the template for your settings.
curl -O https://raw.githubusercontent.com/ulsklyc/yuvomi/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/ulsklyc/yuvomi/main/.env.example2
Create your configuration
Copy the template, then open .env in a text editor.SESSION_SECRET is required; DB_ENCRYPTION_KEY is optional but permanent.
Generate a secure value for each secret by running this twice - paste one result as SESSION_SECRET and one as DB_ENCRYPTION_KEY.
cp .env.example .envopenssl rand -hex 32Keep a backup of your .env file somewhere safe. If you lose the DB_ENCRYPTION_KEY, your data cannot be recovered.
3
Start the container
Docker downloads the Yuvomi image and starts it in the background. The first download takes a minute.
docker compose up -dCheck the logs with docker compose logs -f. You should see 'Server running on port 3000'. The container keeps running in the background.
4
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.
docker compose exec yuvomi node setup.jsYou are installing on Docker / Podman.
You're all set
Open your browser and navigate to:
http://localhost:3000Log 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.
SESSION_SECRET
Session SecretRequired
Signs and verifies login cookies. Use openssl rand -hex 32 to generate a secure value.
DB_ENCRYPTION_KEY
Database KeyIrreversible
Optional, and strongly recommended if the household will keep health or financial records. Encrypts the whole database with AES-256; generate with 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.
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.
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.
GuideWeather 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). Reminder lists mirror into Tasks or Shopping in both directions.
GuideSSO / 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.
GuideAutomated backups
Scheduled backups run by default - daily at 2 AM, 7 copies kept. Optionally upload each backup to a WebDAV server and manage restore in Settings -> Administration -> Backup and restore.
GuideDocument storage
Store new document files and calendar attachments outside SQLite in a mounted host folder, on WebDAV, or in Google Drive. Back up every external binary target separately.
GuideEmail / SMTP
Configure an outgoing SMTP server to enable the self-service 'Forgot password' flow and password reset links.
GuideLive currency conversion
Budget -> Subscriptions works without external services. Set FIXER_API_KEY to convert subscriptions billed in foreign currencies into your household base currency.
GuideImmich photo screensaver
Let an idle wall tablet show photos from your own Immich library instead of a fixed dashboard. Configure it in Settings -> Administration -> Immich.
GuideUpdates
Pull the latest image and restart with docker compose pull && docker compose up -d. Your data persists across updates.
Something not working?
Most issues have a simple fix. If you are 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.
lsof -i :3000
# find what is using the portOr edit docker-compose.yml and change 3000:3000 to for example 8080:3000.
Docker: Permission denied
Add your user to the Docker group, then log out and back in.
sudo usermod -aG docker $USERContainer starts but the page is not reachable
Check the container status and logs:
docker compose ps # should show "Up" and "healthy"
docker compose logs # look for error messagesAccessing from another device? Check your firewall rules.
Database encryption error
The DB_ENCRYPTION_KEY in your .env is missing or does not match the key used when the database was created. On a fresh install you can reset:
docker compose down -v
docker compose up -ddocker compose down -v deletes all data. Only use this on a fresh install with no data.
Nginx shows 502 Bad Gateway
Nginx cannot reach the container. Check it is running and the port matches:
docker compose ps
docker compose logs | grep "Server running"Ensure the proxy_pass port in your Nginx config matches the host port in docker-compose.yml (default: 3000).