- Python 44.9%
- JavaScript 40.6%
- CSS 10.7%
- TeX 1.8%
- Makefile 0.8%
- Other 1.2%
| backend | ||
| data/relatives | ||
| frontend | ||
| .gitignore | ||
| docker-compose.dev.yml | ||
| docker-compose.yml | ||
| Makefile | ||
| noxfile.py | ||
| README.md | ||
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/apiand/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_COOKIESenabled and a placeholder/missingSECRET_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 rerunmake prod PROD_DATA_DIR=.... The data migration is not needed; Markdown records stay compatible. - Secret rotation: replacing
SECRET_KEYlogs everybody out. It does not change user passwords inlogin/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_reqrules for/api/login,/api/signupand/api/contactin 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.