Install Yuvomi: Family Planner with Docker and Caddy

Yuvomi is a family planner that you run yourself. Tasks, calendar, shopping list, meal plan, household budget and more live in a single web app that you use on your phone like a normal app. Your data stays on your server, there is no subscription and no provider in between.

In this guide I install Yuvomi with Docker on a Debian 13 server and secure it with HTTPS through Caddy. It also covers how to connect the calendar to Google Calendar, iCloud or another calendar service.

What is Yuvomi?

Many households have a separate app for everything: one for tasks, one for the family calendar, one for the shopping list, one for recipes. Yuvomi bundles them. You decide which building blocks (modules) are visible. Anything you don’t need, you switch off and it disappears from the menu.

The modules work together. The meal plan for the next seven days becomes a shopping list with one click, completed tasks earn points that children trade for rewards, and a receipt is attached to the booking and to the inventory item at the same time.

The software is released under the MIT license and is free. It runs as a single container, needs at least 256 MB of RAM and stores everything in one SQLite file.

Prerequisites

Push notifications, installing the app on your phone and the Google connection only work with an address that starts with https://.

Install Docker

Connect to the server over SSH. Docker comes from the official Docker repository. First save the key that Debian uses to verify the packages:

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

Then add the package source. Copy the whole block, including the line EOF:

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

Install Docker:

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

All Docker commands in this guide start with sudo. Check that Docker is running:

sudo docker ps

You see a table with the columns CONTAINER ID, IMAGE and more, still without rows. A detailed explanation of every step and the variant for Ubuntu is in Docker Basics.

Create folders and files

Create a directory for Yuvomi with two subfolders:

mkdir -p ~/yuvomi/data ~/yuvomi/backups
cd ~/yuvomi

• data holds the database with all events, tasks and accounts.
• backups receives Yuvomi’s automatic backups.

On start, Yuvomi sets the owner of both folders to user ID 1000, the user it runs as. You don’t have to configure anything. If your user has a different ID (check with id -u), the folders no longer belong to you afterwards. That does not affect operation. When you copy or back up the folders you then need sudo, as in the Backup section.

The compose.yaml

The project’s own docker-compose.yml publishes port 3000 straight to the network, so without HTTPS. I use my own file instead, in which only Caddy is reachable from outside.

nano compose.yaml

services:
    yuvomi:
        image: ghcr.io/ulsklyc/yuvomi:latest
        container_name: yuvomi
        restart: unless-stopped
        env_file:
            - .env
        volumes:
            - ./data:/data
            - ./backups:/backups

    caddy:
        image: caddy:2
        container_name: caddy
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        volumes:
            - ./Caddyfile:/etc/caddy/Caddyfile
            - caddy_data:/data
            - caddy_config:/config

volumes:
    caddy_data:
    caddy_config:

• env_file reads all settings from the file .env, which you create in a moment.
• ./data:/data and ./backups:/backups connect the folders on the server to the folders in the container. Your data survives every update.
• Yuvomi has no ports entry. It is only reachable through Caddy.

The Caddyfile

nano Caddyfile

{{domain}} {
    reverse_proxy yuvomi:3000
}

On first start, Caddy gets a certificate from Let’s Encrypt and passes all requests on to Yuvomi. Yuvomi listens on port 3000 inside the container.

The .env

The .env contains two secrets. Generate two random values by running this command twice and copy the outputs:

openssl rand -hex 32

Create the file and put the two values into the first lines:

nano .env

SESSION_SECRET=first-random-value
DB_ENCRYPTION_KEY=second-random-value
NODE_ENV=production
BASE_URL=https://{{domain}}
SESSION_SECURE=true
TRUST_PROXY=1
TZ=Europe/Berlin

Restrict access to the file, because it contains keys:

chmod 600 .env

Start Yuvomi

sudo docker compose up -d

Check the status:

sudo docker compose ps

caddy and yuvomi must show Up. You can see in the log whether Caddy got the certificate:

sudo docker compose logs caddy | grep "certificate obtained"

The log of Yuvomi must contain Environment: production:

sudo docker compose logs yuvomi | tail -n 12

Then call the health check:

$curl https://{{domain}}/health
{"status":"ok","timestamp":"2026-11-12T06:49:20.225Z"}

Create the admin account

Open https://{{domain}} in the browser. On the first visit you land on the page /setup, where you create the administrator account.

• Username: You log in with it. It cannot be changed later.
• Display name: This is how you appear in the calendar and in tasks.
• Password: At least 8 characters, preferably much longer.

After you click Create account you are signed in. A short welcome dialog explains the basic idea, and you can close it with Skip.

The interface

At the top is the Overview: it shows at a glance what is on today. Top right, New creates an event, a task or a shopping entry quickly.

Three more modules are switched off at first: Inventory, Waste collection and Schedule. You switch them on under Settings, Modules, Active modules. That is also where you switch off everything your household does not need.

What the modules do

• Calendar: Shared events with month, week, day and agenda views. Every event can be assigned to one or more people.
• Tasks: A task list with deadlines, subtasks and recurring tasks such as “take out the trash”. You see who completed what.
• Rewards: Completed tasks earn points. Children “buy” rewards with the points, which you define beforehand.
• Notes: Short notes, also as a checklist you can tick off.
• Kitchen: A weekly plan for meals, your own recipes and a shared shopping list sorted by supermarket aisle. One click moves the ingredients of the next days onto the shopping list. The pantry remembers amounts and best-before dates.
• Documents: Important family papers in folders, searchable.
• Contacts and Birthdays: An address book with phone numbers and a list of birthdays with reminders.
• Health: Values, medication and preventive appointments per person. Health data is sensitive, which is what the database encryption from the .env is for.
• Budget: Income, expenses, accounts and shared costs. Yuvomi calculates who owes whom how much.

Invite family members

Under Settings, Household, Members you manage the people. New members receive an invitation link that is valid for seven days. When they open it, they choose their own password. For children without a phone you create an account directly. Under Roles & permissions you decide per role which modules someone may use fully, read only, or not see at all.

Yuvomi as an app on your phone

Open https://{{domain}} in your phone’s browser. Android offers Install after a short while. On the iPhone you tap Share and then Add to Home Screen. The app then appears like any other, without an app store. Reminders arrive as push notifications, even when the app is closed.

Connect the calendar to other calendars

The first two ways need no credentials, and you can combine them.

Show Yuvomi events in Google Calendar

This is the most common wish: the family’s events should appear in Google Calendar on your phone. Yuvomi provides a feed for that.

1. Switch on the feed in Yuvomi

   Open Settings, Modules, Calendar and scroll to Export calendar feed. Turn the switch on. The Feed address appears below it:

   Feed address

   https://{{domain}}/feed/calendar/SECRET-TEXT.ics

   With Copy address you put it on the clipboard.

2. Subscribe to the feed in Google Calendar

   Open calendar.google.com on a computer. The option does not exist in the phone app. Next to Other calendars on the left, click the plus and choose From URL. Paste the address and confirm with Add calendar.

3. It shows up on your phone by itself

   A calendar added by URL is linked to your Google account. In the Google Calendar app it appears under Other calendars as soon as you switch it on there.

• The feed is read-only. You keep creating and changing events in Yuvomi.
• Google refreshes subscribed calendars only every few hours. A new event therefore appears with a delay. That is Google’s doing, not Yuvomi’s.
• Anyone who knows the address sees all your visible events. Don’t share it. Generate new link invalidates the old address.
• The same address works in Apple Calendar, Thunderbird and any other app with ICS support. The switch Show assigned people in the title appends the names to every event, for example Pool party (Mom, Dad).
• You export the birthday calendar with a separate switch and a separate address.

Read Google events in Yuvomi

The reverse way: your Google calendar should appear in Yuvomi. For this, Google provides a secret web address (iCal address) behind which the calendar lies as a text file. You don’t have to set anything up at Google.

1. Get the secret address from Google

   Open calendar.google.com on a computer. In the left column, hover over the calendar you want, click the three dots and then Settings and sharing. In the section Integrate calendar you copy the Secret address in iCal format.

2. Subscribe in Yuvomi

   Open Settings, Modules, Calendar and the section ICS Subscriptions. Paste the address and save. Alternatively you import a downloaded .ics file once.

Here too, events flow in one direction only. You create new events at Google, and Yuvomi reads them in regularly. The address must start with https:// and be reachable from the internet. For security reasons Yuvomi blocks addresses in your home network, unless you allow them in the .env with ICS_SUBSCRIPTION_ALLOW_PRIVATE_NETWORK=true.

Sync with Google in both directions

If events you create in Yuvomi should land in your Google calendar and the other way round, you need the Google connection. For that, Yuvomi has to be registered at Google as an application of its own, so that you can allow it to access your account without giving it your password (OAuth).

Under Settings, Modules, Calendar sync in the section More providers, the Google Calendar card shows exactly what is missing: the three variables GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and GOOGLE_REDIRECT_URI. The steps and the redirect URI to copy are there too.

1. Create a project and enable the Calendar API

   Open the Google Cloud Console and create a new project. Enable the Google Calendar API there.

2. Set up the consent screen

   Set up the OAuth consent screen. Choose External as user type. As long as the status is Testing, only accounts you add as test users can connect. Add your Google account there.

3. Create an OAuth client

   Create an OAuth client of the type Web application. Under authorized redirect URIs, enter this address exactly as shown, without a slash at the end:

   Redirect URI

   https://{{domain}}/api/v1/calendar/google/callback

   Google then shows you a Client ID and a Client secret.

4. Enter the values in the .env

   Open the file and add the three lines:

   Terminalbash

   nano ~/yuvomi/.env

   .env

   GOOGLE_CLIENT_ID=your-client-id
   GOOGLE_CLIENT_SECRET=your-client-secret
   GOOGLE_REDIRECT_URI=https://{{domain}}/api/v1/calendar/google/callback

   The redirect URI must match the one entered at Google character for character.

5. Recreate Yuvomi

   A simple restart does not reliably re-read the .env. Recreate the container instead:

   Terminalbash

   cd ~/yuvomi
   sudo docker compose up -d --force-recreate yuvomi

6. Connect

   Open Settings, Modules, Calendar sync again. Instead of the instructions, the button Connect with Google now appears. Sign in under the domain for this, not through the IP address. Then choose under Synced calendars which Google calendars Yuvomi syncs. The import only starts once you tick one.

• Events you create in Yuvomi go to Google only if you pick a Google calendar under Sync target in the event form. Otherwise the event stays local.
• With the switch Read-only, Yuvomi imports but writes nothing back to Google.
• One Google account can be connected per installation.
• Reminders are not transferred. You set them in Yuvomi, and they come from Yuvomi.

Without this effort, the feed from the first section works, but only in one direction.

Sync with iCloud, Nextcloud or Radicale

CalDAV is a standard that iCloud, Nextcloud and many other services speak. Yuvomi syncs over it in both directions and needs nothing in the .env. Open Settings, Modules, Calendar sync and click Add CalDAV Account under CalDAV Calendars.

You need three details: the address of the CalDAV server, the user name and a password. For Apple that is an app-specific password, which you create at account.apple.com under Sign-In and Security. Your normal Apple password does not work. As address you use https://caldav.icloud.com. For Nextcloud you find the address in the calendar settings under Copy private link. With Connect & test, Yuvomi checks the credentials and lists your calendars. You choose which ones are synced.

Yuvomi syncs every 15 minutes. You change that in the .env with SYNC_INTERVAL_MINUTES.

Outlook.com

For personal Microsoft accounts there is only one way from Yuvomi to Outlook. It needs an app registration in a Microsoft Entra directory. That is more effort than at Google, so I don’t go into it here. The feed from the first section is the easier route here too: Outlook can subscribe to ICS addresses.

Backup

Yuvomi backs itself up: every night at 2 a.m. (in the time zone from TZ) it puts a backup in ~/yuvomi/backups and keeps the last seven. You find manual backups and restore under Settings, Household, Backup and restore.

A backup on the same server does not protect you if the server fails. So copy the whole folder somewhere else regularly:

cd ~
sudo tar czf yuvomi-backup.tar.gz yuvomi

The file also contains your .env with all the keys. Don’t store it unencrypted.

Update Yuvomi

cd ~/yuvomi
sudo docker compose pull
sudo docker compose up -d

Data and settings live in data and .env, outside the container. After the update you check in the log that the database migrations ran through:

sudo docker compose logs yuvomi | tail -n 12

I use the image with the tag latest. If you want full control over updates, put a fixed version in the compose.yaml, for example ghcr.io/ulsklyc/yuvomi:2.89.1.

When something goes wrong

• Caddy shows 502 Bad Gateway: Yuvomi is not running yet or keeps restarting. Check sudo docker compose ps and sudo docker compose logs yuvomi. A placeholder you did not replace or a typo in the .env stops the start.
• No certificate: Check that the domain’s A record points to the server and that ports 80 and 443 are open. sudo docker compose logs caddy names the reason.
• The log says Environment: development: NODE_ENV=production is missing in the .env.
• Login does not work: SESSION_SECURE=true requires HTTPS. Open Yuvomi only through https://{{domain}}, not through the IP address.
• Google reports redirect_uri_mismatch: The address at Google and the value of GOOGLE_REDIRECT_URI are not identical character for character. Watch https, upper and lower case, and a slash at the end.
• Events are shifted by hours: Check the time zone under Settings, Account, Appearance and the variable TZ.
• New events are missing in Google Calendar: With a subscribed feed, Google refreshes only every few hours. Wait, or use the Google connection.

Who is Yuvomi for?

Yuvomi suits families and couples who want tasks, events, shopping and the household budget in one place and don’t mind running the server themselves. The range of functions is large, and you switch off what you don’t need.

• You take care of updates, backups and the database key yourself.
• Syncing with Google takes effort because Google demands it. The feed is the quick way.

Conclusion

With Docker and Caddy, Yuvomi runs behind HTTPS in a few minutes. For the calendar, an exported feed and, if needed, an ICS subscription are enough for most people. If you want to sync with Google in both directions, you set up an OAuth client at Google once and enter three values in the .env. With iCloud and Nextcloud, CalDAV works without a detour through the .env.

FAQ