OpenFamily

OpenFamily

Docker app from NexaFlowFrance's Repository

OpenFamily is a family organizer for your own server: a shared calendar with reminders, tasks and chores with a rewards system for kids, shopping lists updated live on every…

Overview
OpenFamily is a family organizer for your own server: a shared calendar with reminders, tasks and chores with a rewards system for kids, shopping lists updated live on every phone, meal planning with a recipe book, a family budget, a kiosk mode for a wall tablet and an optional AI assistant. It has an Android app, a documented API with webhooks, and integrations with Home Assistant, Gladys Assistant, Mealie, Grocy and Nextcloud. The interface is available in eight languages.

This one container holds the web interface, the API and its PostgreSQL database. There is nothing to prepare: the secrets are generated on the first start and kept in the data folder. Start it, open the Web UI and create your account.

Everything to back up is in the data folder.
OpenFamily

OpenFamily

The open-source, self-hosted family organizer
Keep full control of your family's data: run it on your own server, or let us host it for you in France.

🇬🇧 English · 🇫🇷 Français · 🇨🇳 简体中文

Release CI Live demo Docker License: AGPL v3 PWA


🎬 Try the live demo

No sign-up, runs entirely in your browser, nothing is saved.

OpenFamily dashboard

OpenFamily is a self-hosted alternative to apps like Cozi or FamilyWall: shopping lists, tasks, a shared calendar, weekly planning, recipes, meal planning, a pantry and a household budget, all in one place, on your own server.

🌟 What sets it apart

📱 A real Android app An APK that connects to your own server, kept up to date with Obtainium. On any other phone, the web app installs to the home screen.
🔌 Open to the rest of the house A documented API with personal tokens and webhooks, and integrations with Home Assistant, Gladys Assistant, Mealie, Tandoor, Grocy and Nextcloud. Your home automation can read the family's day and add to the shopping list.
🖼️ At home on a wall A kiosk mode for a tablet in the kitchen, with a screensaver, and login-free pages made for an e-paper frame or an e-reader.
🤖 An assistant that can stay at home Add things in plain language and get menu ideas from your own recipes, with a local model through Ollama or the provider of your choice. Optional, and off until you set it up.
🐳 Running in one command One container, nothing to configure. On Windows, an installer with no Docker at all.
☁️ Or hosted for you OpenFamily Cloud runs the same open-source app on servers in France, for families who would rather not run one. You can export everything and move to your own server whenever you want.

✨ Features

🛒 Shopping list Categories, prices, quantities, templates, aisle-by-aisle store mode
🧊 Pantry What is at home, by place (fridge, freezer, cupboard), with use-by dates and what to eat first, barcode lookup (typed, scanned with the camera or a handheld scanner) and one tap to the shopping list
✅ Tasks Recurring tasks, family assignment, statistics
📅 Appointments Monthly calendar, automatic reminders, color coding, birthdays taken from the family's dates of birth, iCal export (.ics / webcal)
🗓️ Weekly planning Work hours and school timetables per family member
🍳 Recipes Family library, advanced filters, prep/cook times
🍽️ Meal planner Weekly view, PDF export, linked recipes
💰 Budget Monthly tracking, charts, per-category limits with alerts, recurring debits
👨‍👩‍👧‍👦 Family Member profiles, health info, emergency contacts
🔄 Real-time sync Instant updates across every device (WebSocket)
🔔 Notifications Appointment reminders, task alerts (Web Push VAPID) + in-app
🖼️ Wall & e-paper displays Full-screen kiosk for a tablet, with a screensaver (photos or a moving clock) for screens left on all day, and display links: a login-free page of the family's day for an e-paper frame (InkyPi), an e-reader or any screen that cannot sign in
🔌 API, tokens & webhooks A documented API for Home Assistant, Gladys Assistant, n8n or a script: personal tokens, read-only or read-write and revocable at any time, real-time updates over WebSocket, and webhooks that call your tools when the family's data changes
🤖 AI assistant (optional) Say it in plain language ("lasagna on Thursday evening, and remind Mia about her swimming bag") and it lands in the right place, and get menu ideas from your recipes. Works with a local model (Ollama), any OpenAI-compatible API, Anthropic Claude or Google Gemini
👥 Shared accounts Invite by link, access requests, ownership transfer
🔑 Single sign-on Sign in with your own OpenID Connect provider (Authentik, Keycloak, Pocket ID...), optional SSO-only servers, sign out of all devices
🛡️ Roles & permissions Parent / child accounts, with a read-only budget for children
🌍 Multilingual English / French / German / Portuguese / Russian / Spanish / Catalan / Simplified Chinese interface with automatic detection
📴 Offline mode Browse cached data without a connection (PWA)

📸 Screenshots

Shopping (store mode) Calendar Budget
Shopping list Calendar Budget
Meal planner Family Weekly planning
Meal planner Family Weekly planning

In the dark theme:

Home Calendar Weekly planning
Home, dark theme Calendar, dark theme Weekly planning, dark theme

On a phone:

Home Home, dark theme Shopping Calendar
Home, on a phone Home, on a phone, dark theme Shopping, on a phone Calendar, on a phone

🔗 Third-party integrations

Connect OpenFamily to the rest of your self-hosted setup from the Integrations page, with no config file to edit.

App Type What is synced
Gladys Assistant 🏡 Home automation The family calendar, shopping list and tasks in Gladys, the open-source home assistant made in France: dashboard widgets, scene actions and triggers. Installed from the Gladys integration store
Mealie 🍲 Recipes Automatic import of all recipes (pagination, API v1 & v2)
Tandoor 🌿 Recipes, meal plan Import via the Django REST API (meal plan: "Import from Tandoor" button on the meal planning page)
Home Assistant 🏠 Shopping Shopping-list sync over WebSocket (modern todo entities + legacy)
Grocy 🥦 Shopping & stock Shopping list and stock synchronization
Nextcloud ☁️ Calendar CalDAV import with auto-discovery and per-UID deduplication

🎬 Thanks to Makernix: the idea of connecting OpenFamily to the self-hosted family ecosystem (Mealie, Grocy, Home Assistant, Nextcloud) emerged from a direct exchange with him.

🚀 Quick start

🐳 Docker, in one command

One container holds the interface, the API and the database. There is nothing to configure: the secrets are generated on the first start and kept with your data.

docker run -d --name openfamily --restart unless-stopped \
  -p 3000:3000 -v openfamily:/data \
  ghcr.io/nexaflowfrance/openfamily:latest

Open http://localhost:3000, or http://<server-address>:3000 from a phone, and create your account. The image is published for amd64 and arm64 (Raspberry Pi 4 and 5, most NAS). The server guide covers HTTPS, updates and backups.

📦 From the app catalog of your server

On these systems OpenFamily installs from the catalog, like any other app. Each link says how to add it, step by step:

System How
Home Assistant (OS or Supervised) Add the app repository
Umbrel Add the community app store
CasaOS, ZimaOS Add the app store
Runtipi Add the app store
Unraid Get the template
TrueNAS In the catalog of community apps, under OpenFamily
Proxmox A script that creates the container

The first five are new. If one does not work on your system, tell us: it helps everyone after you.

🪟 Windows installer (.exe), the easiest path

For Windows users, NexaFlow provides an all-in-one graphical installer: Node.js and PostgreSQL are bundled: no Docker, no configuration required.

Download OpenFamily for Windows

Run OpenFamily-Setup.exe, click Start, and the app opens at http://localhost:3000. The window also shows your local network address so you can open it from a phone on the same Wi-Fi, and the Settings tab explains how to set up Tailscale for secure remote access.

📱 Android app (APK)

OpenFamily also has a native Android app, a thin client that connects to your own server (you enter its address on first launch, just like the Nextcloud or Home Assistant apps). It hosts nothing itself.

Download OpenFamily for Android

Install the APK, allow installs from unknown sources when prompted, open the app and enter your server URL (e.g. http://192.168.1.10:3000, or your HTTPS / Tailscale address).

🔄 Stay up to date automatically: add the repo to Obtainium to receive app updates straight from GitHub Releases, with no app store required.

🧩 Docker Compose, each part in its own container

The same app as three containers (PostgreSQL, the API, the web server), for a server where you want them apart or want to build from the sources. The step-by-step server guide walks through it: secrets to set, HTTPS with a domain or Tailscale, updates and backups.

cp .env.example .env   # edit your settings
docker-compose up -d --build

Verify the stack end-to-end:

npm run smoke:api

Prefer ready-made images? Every release is published for amd64 and arm64. Create a docker-compose.override.yml next to docker-compose.yml:

services:
  server:
    image: ghcr.io/nexaflowfrance/openfamily-server:2.2.0
  client:
    image: ghcr.io/nexaflowfrance/openfamily-client:2.2.0

then run docker compose pull server client && docker compose up -d, without --build. The image names need their -server / -client suffix. Settings such as REGISTRATION_ENABLED are read by the server at startup, so the published images need no rebuild.

🛠️ Manual install

npm run install:all
psql -U postgres -c "CREATE DATABASE openfamily;"
cp .env.example .env
npm run dev

🆚 Why OpenFamily?

OpenFamily Cozi / FamilyWall
Your data on your server ✅ ❌
Open source (AGPL-3.0) ✅ ❌
No ads, no tracking ✅ ❌
Self-hosted integrations (Gladys Assistant, Home Assistant, Mealie, Grocy…) ✅ ❌
A documented API, with tokens and webhooks ✅ ❌
An AI assistant that can run on a local model ✅ ❌
Works offline (PWA) ✅ ⚠️

🧰 Tech stack

Frontend: React 19 · TypeScript · Vite 7 · TailwindCSS · Radix UI · i18next · PWA (service worker, web push, offline) Backend: Node.js 26 · Express · PostgreSQL 16 (auto-migration) · WebSocket · Web Push (VAPID) · JWT + bcrypt 12 · helmet · rate limiting DevOps: one all-in-one image, or Docker Compose (postgres, server, client/nginx) · GitHub Actions (CI + Docker publish to ghcr.io + GitHub Pages demo)

🔐 Security

JWT auth (7 days, auto refresh) · passwords hashed with bcrypt (cost 12) · secure HTTP headers via helmet · rate limiting on auth endpoints · strict configurable CORS · server-side input validation · structured logs (no sensitive data) · optional OpenID Connect single sign-on (PKCE, signed ID tokens) · sessions revocable per account.

🗺️ Roadmap

Planned features and design decisions live in ROADMAP.md.

💛 Support the project

OpenFamily is free, open source (AGPL-3.0) and self-hosted: no ads, no tracking, no paid tier. It is built and maintained on personal time. If it helps your family, you can support its development:

Sponsor OpenFamily on GitHub Support OpenFamily on Ko-fi

Starring the repository helps just as much: it is how other families find the project.

🤝 Contributing

A good part of OpenFamily came from the people who use it: languages, integrations, ideas that became features.

  • An idea or a question? Start a discussion.
  • Something does not work? Open an issue.
  • Your language is missing or imperfect? TRANSLATING.md: a translation can arrive one text at a time, the app shows the rest in English.
  • You want to write code? CONTRIBUTING.md says how to run the project and what a pull request needs.

📄 License

GNU Affero General Public License v3.0 (AGPL-3.0-only), see licence.md.

🙏 Credits

Built and maintained by NexaFlow France.

Categories

Related apps

Links

Details

Repository
ghcr.io/nexaflowfrance/openfamily:latest
Last Updated2026-11-17
First Seen2026-11-17

Runtime arguments

Web UI
http://[IP]:[PORT:3000]/
Network
bridge
Shell
sh
Privileged
false
Extra Params
--restart unless-stopped

Template configuration

Web UI PortPorttcp

The address of OpenFamily in a browser and in the Android app: http://UNRAID-IP:PORT

Target
3000
Default
8480
Value
8480
DataPathrw

The database and the secrets generated on the first start. This is the folder to back up.

Target
/data
Default
/mnt/user/appdata/openfamily
Value
/mnt/user/appdata/openfamily
Allow RegistrationVariable

Leave on true to create your account, then set to false: after that only people invited from the Family page can create one.

Target
REGISTRATION_ENABLED
Default
true
Value
true
Public URLVariable

The address you open OpenFamily at, e.g. https://family.example.org. Needed for single sign-on, and when e-mail links show the wrong address behind a reverse proxy.

Target
APP_PUBLIC_URL
SMTP HostVariable

Mail server for invitation and password reset e-mails. Empty = no e-mail is sent; invitations still work by sharing their link.

Target
SMTP_HOST
SMTP PortVariable

Mail server port

Target
SMTP_PORT
Default
587
Value
587
SMTP UserVariable

Mail server user name

Target
SMTP_USER
SMTP PasswordVariable

Mail server password

Target
SMTP_PASS
Mail FromVariable

Sender of the e-mails, e.g. OpenFamily family@example.org

Target
MAIL_FROM
SSO Issuer URLVariable

Single sign-on (OpenID Connect) issuer URL. Empty = off. Redirect URI to register at your provider: [Public URL]/api/auth/oidc/callback

Target
OIDC_ISSUER_URL
SSO Client IDVariable

Single sign-on client ID

Target
OIDC_CLIENT_ID
SSO Client SecretVariable

Single sign-on client secret

Target
OIDC_CLIENT_SECRET
SSO Button LabelVariable

Shown as 'Continue with ...' on the sign-in page

Target
OIDC_PROVIDER_NAME
Allow Password Sign-inVariable

Set to false for an SSO-only server (ignored while SSO is not configured)

Target
PASSWORD_LOGIN_ENABLED
Default
true
Value
true