OpenFamily¶
Metadata¶
| Field | Value |
|---|---|
| Service | OpenFamily |
| Purpose | Self-hosted family calendar, tasks, lists, meals, and budget |
| Criticality | Tier 3 |
| Owner | Application / platform owner |
| Clusters | homelab |
| Namespace | openfamily |
| Exposure | internet |
| Stateful | yes |
| Backup class | PostgreSQL dump plus PVC backup |
| RPO / RTO | Daily backup target, 2 to 4 hours to restore |
| Last reviewed | 2026-09-14 |
1. Service Overview¶
OpenFamily provides shared household planning through a browser, installable PWA, and Android client. It stores structured state in PostgreSQL and uploaded files on a separate PVC.
2. Architecture Diagram¶
[Browser / PWA / Android]
-> [Traefik: openfamily.home.mutana.fr]
-> [OpenFamily client/nginx]
-> /api, /health, /ws -> [OpenFamily server]
-> [PostgreSQL]
-> [uploads PVC]
OpenFamily is deployed from openfamily/base with the cluster-specific configuration in openfamily/overlays/homelab. Fleet maps that overlay to cluster homelab; operators address the same cluster directly with kube context homelab-k3s.
3. Deployment Specifications¶
| Component | Workload | Persistence | Notes |
|---|---|---|---|
| Client | Deployment | none | nginx-served PWA and same-origin reverse proxy |
| Server | Deployment (Recreate) |
uploads, 5 GiB NFS |
API, WebSocket, migrations, and uploaded files |
| PostgreSQL | StatefulSet | postgres-data, 8 GiB local-path |
Primary application data |
All application images are pinned to 1.7.0. PostgreSQL is pinned to the multi-architecture digest for postgres:16.15-alpine3.24.
4. Configuration Guide¶
Non-secret runtime settings are generated into openfamily-config. The required openfamily-secrets Secret is bootstrapped outside Git from the ignored .openfamily-secrets.env file and contains:
| Key | Required | Purpose |
|---|---|---|
POSTGRES_PASSWORD |
yes | Database authentication |
JWT_SECRET |
yes | Application session signing |
VAPID_PUBLIC_KEY |
no | Web Push public key |
VAPID_PRIVATE_KEY |
no | Web Push private key |
The route relies on OpenFamily's own authentication. Authelia is deliberately omitted to preserve PWA, WebSocket, invitation, and Android-client flows.
5. Access Protocols¶
- External URL:
https://openfamily.home.mutana.fr - TLS termination: Traefik
- Dependencies: Traefik, cluster DNS,
local-path,truenas-nfs-apps, and the out-of-band Secret - Health endpoint:
/health, proxied by the client to the server
6. Operations and Observability¶
The client, server, and PostgreSQL probes provide workload health. The external /health endpoint traverses Traefik and the client proxy to the API. Component logs and namespace events are the primary diagnostic sources.
7. Backup and Recovery Notes¶
Back up PostgreSQL logically and protect both PVCs through the applicable storage backup process. Restoring the database without the uploads PVC can leave attachment references unresolved. Preserve the JWT secret during routine restores so existing sessions behave predictably.
See the OpenFamily runbook for deployment, verification, backup, and rollback commands.
8. Release and Change Notes¶
The initial deployment pins the upstream OpenFamily v1.7.0 application images and PostgreSQL 16.15 on Alpine 3.24.