Genealogical Index

A searchable web application for genealogical data with a PostgreSQL database, Python FastAPI backend, and a vanilla JavaScript frontend. Designed as a monorepo that supports multiple country installations sharing the same core code but with per-site branding, translations, and configuration.

List of Genealogical Index sites

• indeks.rodoslovje.si - run by Slovensko rodoslovno društvo
• indeks.rodoslovlje.hr - run by Hrvatsko rodoslovno društvo "Pavao Ritter Vitezović"

Architecture

Layer	Technology
Database	PostgreSQL 16 (with pg_trgm for fuzzy search)
Backend API	Python 3.11 / FastAPI / Uvicorn
Frontend	Vanilla JS / HTML / CSS (Vite build)
Reverse proxy	Caddy 2
Containerisation	Docker & Docker Compose

Internet → Caddy → /          → static files (site dist/)
                 → api.domain → Docker: sgi_api (FastAPI :8000)
                                        ↕
                                Docker: sgi_postgres (:5432)

---

Repository Layout

core/
  web/          # Shared frontend (JS / HTML / CSS) — imports @site-config
  backend/      # Shared FastAPI application
  tools/        # Shared JSON import scripts
sites/
  slo/          # Slovenia installation
    web/
      site.config.js   # Branding, languages, intro texts, API host
      public/          # Logo, favicons
    vite.config.js     # Sets root=core/web, resolves @site-config alias
    package.json       # name: "slo-index"
    docker-compose.yml
    .env.example
    caddy/
data/             # Gitignored — raw GEDCOM files and extracted JSON

Adding a new country installation

1. Copy sites/slo/ to e.g. sites/cro/.
2. Edit sites/cro/web/site.config.js — set logo, links, languages, intro texts, API host.
3. Replace assets in sites/cro/web/public/.
4. Edit sites/cro/package.json — set a unique name (e.g. "cro-index").
5. Add workspace scripts to the root package.json:

   "dev:cro": "npm run dev --workspace=sites/cro",
   "build:cro": "npm run build --workspace=sites/cro"
   

6. Set up a docker-compose.yml and .env in sites/cro/ pointing to the new server's data directory and API host.

---

Prerequisites

Local development machine

Windows

Tool	Install	Notes
Git	GitHub Desktop (recommended) or Git for Windows	GitHub Desktop bundles Git and makes git available system-wide in PowerShell/Command Prompt; Git for Windows also installs Git Bash, which supports python3, mkdir -p, and most bash commands used in this guide
Node.js LTS + npm	nodejs.org	Use the Windows installer; npm is included
Python 3.11+	python.org/downloads	Required for data processing (sections 1.1–1.2); tick "Add Python to PATH" during install; after install python and pip are available in PowerShell
Docker Desktop	docker.com/products/docker-desktop	Enable the WSL2 backend during setup; required only to run the backend stack locally
Text editor	VS Code (recommended)

macOS

This is the beginning of the README. Read the rest at the original. Read the full README ↗