Home Ops

A self-hosted household management system: chores, a shared calendar, recipes and meal planning, groceries, contacts, notes and health records — one private application on hardware you own.

It is built for a household rather than a company, which mostly shows up in one place: members have different levels of trust. A teenager, a housemate and a grandparent should not see the same things, and "the admin can see everything" is the wrong answer for a family's medical notes. So every record carries its own visibility, and there is no administrator override on any of it.

Runs as one Docker container — application, web server and database together — with a single volume and a single port.

What it does

Two ideas run through all of it. Every member owns a colour that follows them into every list, so you find your own row before you read a word. And visibility is per record — private, shared with named people, or the whole household — enforced on every read path.

Requirements

• Docker, with Compose v2 (docker compose, not docker-compose)
• About 1 GB of disk for the image, plus whatever your data comes to
• No cloud account, no API key, no external service

Installation

1. Set a database password. Do this before the first start — Postgres bakes it into the data directory on first boot, and changing it afterwards does not change the user.

cp .env.example .env

Then edit .env and set:

POSTGRES_PASSWORD=<something long and random>
RUN_MIGRATIONS=true
APP_HOSTS=localhost,192.168.1.50        # your server's LAN address

RUN_MIGRATIONS=true matters: it creates the database schema. Left off, the app starts but has no tables, and the first page fails.

2. Start it.

docker compose up -d --build

The first build takes a few minutes. If your Docker's Compose has trouble building, build the image directly and then start it:

docker build -t home-ops:single .
docker compose up -d

3. Open it at http://localhost:8080 — or the address in APP_HOSTS, on the port in WEB_PORT.

The first visit shows a setup page, because no account exists yet. Whoever completes it becomes the administrator. That page stops existing once there is a user.

Configuration

.env is written so each value appears once. Four lines cover a normal install:

DATABASE_URL and TRUSTED_ORIGINS are assembled from those and should stay blank unless you need something they cannot express.

Reaching it over HTTPS

The app is designed to answer on several addresses at once — a public HTTPS hostname, a VPN name, and a LAN address — because a household reaches it from different places. Two consequences:

• SESSION_COOKIE_SECURE defaults to false, because a Secure cookie is silently dropped over plain HTTP and would lock out the LAN. Set it true only if every path is HTTPS.
• TLS is not handled here. Put a tunnel or a reverse proxy in front and add the hostname to PUBLIC_BASE_URL.

Everyday operation

Update to a newer version. Your data lives in a Docker volume, not the image, so replacing the image keeps it:

docker compose down
docker compose up -d --build
docker compose exec app home-ops-migrate      # if the schema changed

Apply migrations by hand (what RUN_MIGRATIONS=true does for you on start):

docker compose exec app home-ops-migrate
docker compose exec app home-ops-migrate current

Back it up. Everything is under /data in the one volume — the database and the uploaded recipe images together:

docker run --rm -v home-ops_home_ops_data:/data -v "$PWD:/out" \
  alpine tar czf /out/home-ops-backup.tar.gz -C /data .

A database dump on its own is not a complete backup: recipe images live beside it. Keep the archive somewhere other than the machine it came from.

Logs.

docker compose logs -f app

Troubleshooting

The first page errors, or nothing loads. The schema was never created. Set RUN_MIGRATIONS=true in .env and restart, or run docker compose exec app home-ops-migrate.

"Password authentication failed" in the logs. POSTGRES_PASSWORD was changed after the first start. Postgres fixed it at initialisation. Either put the original back, or start over with a fresh volume (docker compose down -v — this deletes your data).

Locked out of the app. Five failed sign-ins for one username in fifteen minutes locks that name out; it clears itself after the window. The message for that is "Too many failed attempts", which is different from a wrong password.

Port already in use. Change WEB_PORT in .env.

Nothing at your LAN address, but localhost works. Add that address to APP_HOSTS and restart. Origins are explicit on purpose — the app never trusts the Host header to work out what it is called.

How it is built

Python 3.12 + FastAPI · PostgreSQL 16 · React 19 + TypeScript + Vite · SQLAlchemy 2 + Alembic · nginx, supervised by s6-overlay. No cloud services at runtime, no telemetry, no Redis.

One container holds all three processes with one volume at /data. nginx serves the built frontend and proxies /api to the application over loopback, so the browser only ever sees one origin and every URL in the app is relative.

Licence

MIT — see LICENSE.