Gramps Web

Gramps Web is a fully self‑hosted genealogy platform that exposes the rich data model of the Gramps desktop application through a modern, stateless REST API. The backend is written in Python 3 and built atop the FastAPI framework, leveraging asynchronous request handling to serve concurrent genealogy queries with low latency. The API layer sits directly on top of Gramps’ native SQLite or PostgreSQL database, exposing CRUD operations for persons, families, events, sources, and media. This separation of concerns allows developers to integrate genealogy data into custom dashboards, mobile apps, or third‑party analytics tools without duplicating the complex data model that Gramps already provides.

Architecture

• Framework: FastAPI (Python 3.11+) – offers automatic OpenAPI generation, dependency injection, and built‑in support for OAuth2/JWT authentication.
• Data Layer: Gramps’ own ORM (Python objects) backed by SQLite or PostgreSQL. The API uses the gramps Python package to load, query, and persist the genealogy database.
• Serialization: Pydantic models define request/response schemas, ensuring type safety and validation across the API surface.
• Deployment: The project ships a pre‑built Docker image (gramps-project/gramps-web-api) that bundles Gunicorn with Uvicorn workers, making it trivial to run behind a reverse proxy (NGINX, Traefik) or within Kubernetes.
• Observability: Structured JSON logs and Prometheus metrics endpoints (/metrics) enable integration with Grafana or Loki for monitoring.

Core Capabilities

• Full CRUD: Create, read, update, and delete all Gramps entities via RESTful endpoints (/api/persons, /api/families, etc.).
• Advanced Querying: Filter, sort, and paginate results with query parameters (?surname=Smith&limit=20). The API also supports complex searches (e.g., location, date ranges) through a dedicated /search endpoint.
• Batch Operations: Import or export entire GEDCOM files (/api/import, /api/export) to migrate data between Gramps installations.
• Webhooks & Events: Subscribe to database change events via a WebSocket endpoint (/ws/events) for real‑time synchronization in collaborative environments.
• Authentication & Authorization: Role‑based access control (admin, editor, viewer) is configurable through JSON Web Tokens, allowing fine‑grained permissions for multi‑user deployments.

Deployment & Infrastructure

The self‑hosted nature of Gramps Web makes it ideal for privacy‑centric genealogy projects. Key deployment considerations:

• Containerization: The Docker image is lightweight (~200 MB) and supports environment variables for database credentials, secret keys, and logging levels.
• Scalability: As a stateless API, multiple replicas can be spun up behind a load balancer. The underlying Gramps database can be switched from SQLite (single‑user) to PostgreSQL for concurrent access.
• Persistence: The Gramps database file or PostgreSQL cluster must be mounted as a persistent volume. Backups can be automated via cron jobs that snapshot the SQLite file or perform logical PostgreSQL dumps.
• Security: TLS termination is recommended at the reverse proxy. The API enforces HTTPS, HSTS headers, and rate limiting through middleware.

Integration & Extensibility

• Plugin System: Developers can write Python plugins that hook into Gramps’ event system and expose new API endpoints. The plugin registry is discovered at startup, allowing custom extensions without modifying core code.
• External APIs: Gramps Web can act as a data source for other genealogy tools (e.g., FamilySearch, Ancestry) via its OpenAPI spec. The API supports CORS configuration for cross‑origin consumption.
• Webhooks: Third‑party services can register webhook URLs to receive notifications on data changes, enabling real‑time updates in external dashboards or mobile apps.
• Custom Frontends: The provided Gramps Web frontend is a single‑page React application, but the API is framework agnostic. Developers can build their own UIs or embed Gramps data into existing web portals.

Developer Experience

• Documentation: The project hosts comprehensive API docs (Swagger UI) at /docs and a dedicated developer portal with code samples, authentication flows, and plugin guides.
• Community: An active GitHub repository with issue tracking, pull request reviews, and a Discord channel facilitates rapid feedback. The Gramps community has a long history of open‑source genealogy development, ensuring backward compatibility and shared best practices.
• Testing: The codebase includes extensive unit tests (pytest) and integration tests against a temporary SQLite database, allowing developers to run CI pipelines confidently.

Use Cases

Advantages

• Native Gramps Integration: No