Installation
Get your self-hosted family planner running in a few minutes. No programming experience required — Docker, Podman, or a one-click app store.
Before you start
Yuvomi runs as a Docker or Podman container — 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.)
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.
A command-line interface to type a few commands. Built into every OS — no extra install needed.
macOS: Terminal · Windows: PowerShell · Linux: bash
256 MB RAM minimum. Runs on a Raspberry Pi, NAS, home server, or any desktop machine.
~500 MB disk for the Docker image
Step by step
Six ways to install. Pick the one that matches your setup — the result is the same private Yuvomi instance.
Open your terminal and clone Yuvomi to a folder of your choice.
Run this command from the repository root. The installer server starts on port 8090.
Navigate to the following address. The wizard guides you through configuration, container startup, and admin account creation.
Run these two commands. They download the Docker configuration and the template for your settings.
Copy the template, then open .env in a text editor and set the two required secrets.
Generate a secure value for each secret by running this twice — paste one result as SESSION_SECRET and one as DB_ENCRYPTION_KEY:
.env file somewhere safe. If you lose the DB_ENCRYPTION_KEY, your data cannot be recovered.
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 läuft auf Port 3000. The container keeps running in the background.
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:
Copy the template, then open .env in a text editor and set the two required secrets.
The --build flag compiles the Docker image locally. This takes a few minutes the first time.
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:
In your TrueNAS SCALE web UI, go to Apps → Discover Apps and search for Yuvomi.
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.
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.
In your Umbrel dashboard, open the App Store and search for Yuvomi.
Click Install. Umbrel pulls the image and starts the container for you — no configuration files to edit.
Launch Yuvomi from your Umbrel home screen. The first visit walks you through creating your admin account directly in the browser.
In Unraid, open the Apps tab (the Community Applications plugin) and search for Yuvomi.
Click Install. Set SESSION_SECRET (required) and DB_ENCRYPTION_KEY (recommended — back it up). Adjust the WebUI port and the appdata path if needed.
Click Apply. Once the container is running, click the Yuvomi icon → WebUI. The first visit walks you through creating your admin account.
Open your browser and navigate to:
Log in with the admin credentials you just created. You can add more family members from the Settings page.
Configuration
Two variables in your .env file are mandatory. Everything else is optional.
openssl rand -hex 32 to generate a secure value.openssl rand -hex 32. Back this up — without it, data is unrecoverable.Optional
Once Yuvomi is running, you can set up these extras. All are configured in your .env file.
Reach Yuvomi from other devices or the internet — set up Nginx as a reverse proxy with a free Let's Encrypt certificate. Guide →
Show local weather on the dashboard via Open-Meteo — no API key. Set WEATHER_LAT and WEATHER_LON to your coordinates.
Two-way sync with Google Calendar (OAuth) and multi-account CalDAV/CardDAV (iCloud, Nextcloud, Radicale). Apple Reminders can mirror read-only into Tasks or Shopping. Guide →
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. Guide →
Enable scheduled backups via BACKUP_ENABLED=true — daily at 2 AM, 7 copies kept. Manage and restore in Settings → Backup. Guide →
Pull the latest image and restart: docker compose pull && docker compose up -d. Your data persists across updates.
Troubleshooting
Most issues have a simple fix. If you're still stuck, open an issue on GitHub.
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.
Add your user to the Docker group, then log out and back in:
Check the container status and logs:
Accessing from another device? Check your firewall rules.
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 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).