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](https://img.shields.io/github/v/release/NexaFlowFrance/OpenFamily?color=2563eb&label=version)](https://github.com/NexaFlowFrance/OpenFamily/releases/latest) [![CI](https://img.shields.io/github/actions/workflow/status/NexaFlowFrance/OpenFamily/ci.yml?branch=main&label=CI)](https://github.com/NexaFlowFrance/OpenFamily/actions/workflows/ci.yml) [![Live demo](https://img.shields.io/badge/Live%20demo-online-DC4A60)](https://openfamily.fr/demo/) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?logo=docker&logoColor=white)](https://github.com/NexaFlowFrance/OpenFamily/pkgs/container/openfamily) [![License: AGPL v3](https://img.shields.io/badge/License-AGPL--v3-blue.svg)](licence.md) [![PWA](https://img.shields.io/badge/PWA-ready-5A0FC8)](https://github.com/NexaFlowFrance/OpenFamily)
---
### ๐ŸŽฌ [Try the live demo](https://openfamily.fr/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](https://github.com/NexaFlowFrance/OpenFamily/releases/latest/download/OpenFamily.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](API.md) with personal tokens and webhooks, and integrations with Home Assistant, [Gladys Assistant](https://github.com/NexaFlowFrance/gladys-openfamily), 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](#-docker-in-one-command), nothing to configure. On Windows, an installer with no Docker at all. | | โ˜๏ธ **Or hosted for you** | [OpenFamily Cloud](https://openfamily.fr/#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](API.md) 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](https://github.com/NexaFlowFrance/gladys-openfamily)** | ๐Ÿก Home automation | The family calendar, shopping list and tasks in [Gladys](https://gladysassistant.com), 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](https://www.youtube.com/@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. ```bash 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://: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](INSTALLATION.md)** 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](https://github.com/NexaFlowFrance/home-assistant-apps) | | **Umbrel** | [Add the community app store](https://github.com/NexaFlowFrance/umbrel-app-store) | | **CasaOS, ZimaOS** | [Add the app store](https://github.com/NexaFlowFrance/casaos-appstore) | | **Runtipi** | [Add the app store](https://github.com/NexaFlowFrance/runtipi-appstore) | | **Unraid** | [Get the template](https://github.com/NexaFlowFrance/unraid-templates) | | **TrueNAS** | In the catalog of community apps, under OpenFamily | | **Proxmox** | A [script](INSTALLATION.md#proxmox) that creates the container | The first five are new. If one does not work on your system, [tell us](https://github.com/NexaFlowFrance/OpenFamily/issues): 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](https://github.com/ImranR98/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](INSTALLATION.md)** walks through it: secrets to set, HTTPS with a domain or Tailscale, updates and backups. ```bash cp .env.example .env # edit your settings docker-compose up -d --build ``` - Frontend: http://localhost:3000 - Backend API: http://localhost:3001 Verify the stack end-to-end: ```bash 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`: ```yaml 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 ```bash npm run install:all psql -U postgres -c "CREATE DATABASE openfamily;" cp .env.example .env npm run dev ``` - Frontend: http://localhost:5173 ยท Backend: http://localhost:3001 ## ๐Ÿ†š 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](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](https://github.com/NexaFlowFrance/OpenFamily/discussions). - **Something does not work?** Open an [issue](https://github.com/NexaFlowFrance/OpenFamily/issues/new/choose). - **Your language is missing or imperfect?** [TRANSLATING.md](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](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](licence.md). ## ๐Ÿ™ Credits Built and maintained by [NexaFlow France](https://nexaflow.fr).