No description
  • Python 44.9%
  • JavaScript 40.6%
  • CSS 10.7%
  • TeX 1.8%
  • Makefile 0.8%
  • Other 1.2%
Find a file
2026-11-05 20:40:41 +01:00
backend Make it an absolute path 2026-11-05 20:40:17 +01:00
data/relatives Migrate to fastapi and react 2026-11-01 06:51:34 +01:00
frontend Migrate to fastapi and react 2026-11-01 06:51:34 +01:00
.gitignore Move data/temp to /temp 2026-11-03 19:31:53 +01:00
docker-compose.dev.yml Migrate to fastapi and react 2026-11-01 06:51:34 +01:00
docker-compose.yml Move data/temp to /temp 2026-11-03 19:31:53 +01:00
Makefile Mount data to /data 2026-11-03 16:57:30 +01:00
noxfile.py Add noxfile 2026-11-05 20:40:41 +01:00
README.md Move data/temp to /temp 2026-11-03 19:31:53 +01:00

Genealogy

A family-tree application with a React frontend and a FastAPI backend. The backend stores all records as Markdown files in data/relatives/ so the data remains easy to read, edit and version.

Usage with Docker

# Development (hot reload for the backend, Vite dev server for the frontend)
make dev

# Production build (creates config.json if needed and uses ./data by default)
make prod

# Production with a separate data directory (recommended)
make prod PROD_DATA_DIR=/srv/genealogy/data

The services started by docker compose are:

  • backend — FastAPI API, reachable only inside the Docker network;
  • backend-worker — watches data/relatives/ and regenerates family/pedigree graphs;
  • frontend — React app on 127.0.0.1:3000.

In development the backend is additionally published on 127.0.0.1:8000. Production publishes only the frontend on loopback; see Production deployment for the external nginx setup.

The backend containers run as your local user (the Makefile passes your UID and GID as build arguments) so files written to the bind-mounted data directory keep your ownership instead of becoming root-owned. When calling docker compose directly, export the IDs and data path yourself or rely on the defaults:

LOCAL_UID=$(id -u) LOCAL_GID=$(id -g) GENEALOGY_HOST_DATA_DIR=./data \
  docker compose up --build

Place relative Markdown files in data/relatives/ and configuration in data/config.json. The file is ignored by git because it contains secrets. An example configuration:

{
  "SECRET_KEY": "<random hex value, e.g. from make secret>",
  "ntfy": {
    "url": "https://ntfy.sh/topic",
    "token": "optional-token"
  }
}

The optional ntfy block is used for notifications (logins, edits, signups and daily birthday/anniversary reminders). If it is absent notifications are simply disabled.

Production deployment

The production setup assumes:

  • the app is served at the root of a domain (https://genealogy.example.com/), not under a subpath, because the frontend uses absolute URLs such as /api and /assets;
  • TLS is terminated by an external nginx;
  • the Docker services bind only to loopback, and the backend is not reachable from the network at all;
  • production data lives outside the repository; the data/ directory in the repository is demo data and must not be used.

1. Prepare the production data directory

Create a directory for records, users and generated graphs. It must be owned by the user the containers run as. By default that is the user running make (LOCAL_UID/LOCAL_GID); override those variables if necessary.

export PROD_DATA_DIR=/srv/genealogy/data
install -d -m 750 -o "$(id -u)" -g "$(id -g)" "$PROD_DATA_DIR"

The application creates relatives/, login/, images/, documents/ and the other directories on demand. Back up this whole directory regularly. Temporary LaTeX build files are written outside the data directory (/temp in the containers).

2. Create the session secret

make secret PROD_DATA_DIR="$PROD_DATA_DIR"

This writes $PROD_DATA_DIR/config.json with a random SECRET_KEY and sets permissions to 600. If the file already exists it is left unchanged, so it is safe to run repeatedly. Changing SECRET_KEY invalidates existing sessions.

Add the optional ntfy block to the same file if you want notifications.

The backend refuses to start with GENEALOGY_SECURE_COOKIES enabled and a placeholder/missing SECRET_KEY, so production cannot accidentally run with the built-in demo key.

3. Create the first login

Users are stored in $PROD_DATA_DIR/login/login.md, one user per line:

role;display name;email;password/token;relative-hash

role is active, inactive or admin. The fourth field is both the password and the bearer token, so generate a long random value. The last field links the user to a relative hash and may be empty.

mkdir -p "$PROD_DATA_DIR/login"
TOKEN=$(openssl rand -hex 32)
umask 077
printf 'admin;Admin;admin@example.com;%s;\n' "$TOKEN" > "$PROD_DATA_DIR/login/login.md"

Do not reuse data/login/login.md from the repository: its user Lilibet with password pw is a public demo account.

4. Start the containers

make prod PROD_DATA_DIR="$PROD_DATA_DIR"

This builds the images and starts:

  • frontend on 127.0.0.1:3000 (the only published port);
  • backend on the internal Docker network (no host port);
  • backend-worker on the internal Docker network.

docker-compose.yml enables secure session cookies by default. They require HTTPS from the browser, so only reach the app through the TLS proxy. Local development (make dev) disables secure cookies automatically because it uses plain HTTP. For a one-off HTTP smoke test of the production image, set GENEALOGY_SECURE_COOKIES=0; never do that for a public deployment.

To run detached, use the same environment explicitly:

docker compose -f docker-compose.yml up --build -d

Logs are available with docker compose logs -f backend.

5. External nginx with TLS

Point the public server block at the frontend container. Uploads need at least 12m, and graph generation can take up to a couple of minutes:

server {
    listen 80;
    server_name genealogy.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name genealogy.example.com;

    ssl_certificate     /etc/letsencrypt/live/genealogy.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/genealogy.example.com/privkey.pem;

    # The backend accepts uploads up to 10 MB; leave room for multipart data.
    client_max_body_size 12m;

    # LaTeX graph generation can exceed nginx's 60 second default.
    proxy_read_timeout 120s;
    proxy_send_timeout 120s;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Optional: hide the interactive API documentation in production.
    # location = /api/docs        { return 404; }
    # location = /api/openapi.json { return 404; }
}

The app must be mounted at /. Do not add a prefix such as /genealogy/ without changing the frontend build and API paths.

If nginx runs in a container or on another host, change the Compose port binding from 127.0.0.1:3000:3000 to an address reachable by nginx. Never publish the backend port; all traffic must go through nginx so TLS and the security headers apply.

6. Verify

curl -fsS https://genealogy.example.com/api/health
curl -I https://genealogy.example.com/

After logging in, the session cookie must have the Secure, HttpOnly and SameSite=Lax attributes. If it does not, check that the public URL uses HTTPS and that GENEALOGY_SECURE_COOKIES is not disabled.

Operations notes

  • Backups: back up the entire $PROD_DATA_DIR; it contains the records, users, configuration and generated images.
  • Updates: git pull, then rerun make prod PROD_DATA_DIR=.... The data migration is not needed; Markdown records stay compatible.
  • Secret rotation: replacing SECRET_KEY logs everybody out. It does not change user passwords in login/login.md.
  • Graphs: the worker regenerates family and pedigree images when relatives change. Large trees can take a while; the nginx timeouts above cover this.
  • Rate limiting: consider adding limit_req rules for /api/login, /api/signup and /api/contact in the public nginx.
  • Tokens in URLs: the API supports ?token=, which can end up in access logs. Prefer the session cookie (normal login) in production.

API

Interactive documentation is available at http://localhost:8000/docs. Every endpoint is available under /api (for example /api/relatives) and the legacy Flask paths are still supported (/relatives).

Authentication uses the password/token from data/login/login.md. After POST /api/login the token is stored in a session cookie; it can also be sent as an Authorization: Bearer <token> header or as a ?token= query parameter.

Route Method Auth Description
/api/ GET — Service information
/api/hello GET — Health/hello endpoint
/api/health GET — Health check
/api/calendar?token= GET token param Upcoming birthdays, weddings and remembrances
/api/relatives GET login List all relatives (?todo=true for todo entries)
/api/relatives POST login Create a relative
/api/relatives/{hash} GET login Relative details, relations, documents and images
/api/relatives/{hash} PUT/PATCH login Update (or rename) a relative
/api/relatives/{hash} DELETE login Delete a relative
/api/relatives/{hash}/edit GET login Data for the edit form (empty record if new)
/api/create GET login Generate a new relative hash
/api/relatives/{hash}/upload POST login Upload a profile image
/api/relatives/{hash}/upload_document POST login Upload a document
/api/relatives/{hash}/graph GET/POST login Fetch or generate family/pedigree graphs
/api/search?query= GET/POST login Search relatives by name
/api/todo GET login Relatives with "todo" in their body
/api/validate GET login Validate cross-references
/api/validate/hash POST login Validate a hash for the edit form
/api/login GET/POST — Login (form or JSON with password)
/api/login/{token} GET — Login with a token
/api/logout GET login Log out
/api/me GET login Current user
/api/signup POST — Request a new account
/api/contact GET/POST — Contact form / admin user list
/api/images/... GET login Serve uploaded images
/api/documents/... GET login Serve uploaded documents

Local frontend development

The React app lives in frontend/ and talks to the FastAPI backend through relative /api URLs. During development Vite proxies those requests to the backend:

cd frontend
npm ci
VITE_API_PROXY=http://127.0.0.1:8000 npm run dev

The dev server is available at http://localhost:3000. If VITE_API_PROXY is not set it defaults to http://localhost:8000; inside Docker Compose it is set to http://backend:8000.

npm run lint    # oxlint
npm run build   # production bundle in frontend/dist

The Docker image builds the bundle and serves it with nginx on port 3000. nginx also proxies /api/ to the backend, so the production container does not need any build-time API URL configuration. The main routes are /, /login, /contact, /relatives, /relatives/{hash}, /relatives/{hash}/edit, /relatives/{hash}/upload, /relatives/{hash}/upload_document, /search and /todo.

Local backend development

python -m venv venv
venv/bin/pip install -r backend/requirements.txt
venv/bin/uvicorn backend.main:app --reload --port 8000

The data directory defaults to data/ in the repository root and can be selected explicitly with the GENEALOGY_DATA_DIR environment variable. In the Docker containers it is mounted at /data.

Temporary LaTeX build files default to temp/ in the repository root; the containers use /temp. Set GENEALOGY_TEMP_DIR to override this location.