Gramps Web releases

Configuration for trees

This release adds the possibility to add tree-specific configuration to the database. This will enable features requiring tree owner configuration in Gramps Web (https://github.com/gramps-project/gramps-web-api/pull/833)

Nested filters

Filter rules can now be nested, matching the full complexity of filters that can be defined in Gramps core (https://github.com/gramps-project/gramps-web-api/pull/828)

Track background tasks in database

Celery background tasks like imports or search index updates are now tracked in the database, enabling more consistent and complete progress tracking in Gramps Web (https://github.com/gramps-project/gramps-web-api/pull/827)

Speed up loading of revision history

Loading the revision history was unnecessarily slow on large databases due to suboptimal SQL queries. Fixed in https://github.com/gramps-project/gramps-web-api/pull/836

Other changes

• Fix GEDCOM7 import error handling to use appropriate HTTP status codes (https://github.com/gramps-project/gramps-web-api/pull/832)
• Allow customizing the transaction commit message (https://github.com/gramps-project/gramps-web-api/pull/834)
• Fix alembic duplicate head and detect in CI (https://github.com/gramps-project/gramps-web-api/pull/838)
• Set HuggingFace cache path (https://github.com/gramps-project/gramps-web-api/pull/837)

User database migration ⚠️

Since the new OIDC feature requires a change to the schema of the Gramps Web user database, a schema migration must be run once (regardless of whether you plan to use OIDC or not). When using the default docker image and entrypoint, this is done automatically on startup. In custom environments, you will need to run

python3 -m gramps_webapi --config /app/config/config.cfg user migrate

in the Gramps Web API contrainer, or something equivalent for your custom setup.

The same command can also be used inside the Dev Container by developers using the recommended development environment, after pulling the latest Web API version.

Full Changelog: https://github.com/gramps-project/gramps-web-api/compare/v3.12.2...v3.13.0

Another maintenance release fixing four bugs:

• The oldest open bug in our code base, https://github.com/gramps-project/gramps-web-api/issues/281, was about family event participants always being using the English form (Person A and Person B) due to a limitation in Gramps core. We now fixed this by reimplementing the relevant functions with proper translations. https://github.com/gramps-project/gramps-web-api/pull/822
• Sorting the family list would lead to a server error when a family existed without a parent #823
• Deleting all objects in the database has always been quite slow. Although it's still not blazing fast, the improvement in https://github.com/gramps-project/gramps-web-api/pull/825 should speed it up significantly.
• The transaction undo endpoint had a bug that would incorrectly flag each transaction as not undoable without conflict. Fixed in https://github.com/gramps-project/gramps-web-api/pull/826

Full Changelog: https://github.com/gramps-project/gramps-web-api/compare/v3.12.1...v3.12.2

This is a maintenance release that makes two improvements to the celery background worker:

1. The track_started configuration option is now always set to "true". This allows Gramps Web to distinguish between a background job that is still queued and one that is already running, but hasn't produced output yet.
2. So far, several error scenarios caused an unhelpful "Unknown error" message for background tasks like imports. Now, the error messages are properly propagated, so they can be displayed in the frontend.

Full Changelog: https://github.com/gramps-project/gramps-web-api/compare/v3.12.0...v3.12.1

Yet another feature release in April, this time focusing on performance :rocket:

Performance improvements

Several changes reduce the overhead of loading and reading the Gramps database:

• Disk I/O on database load is reduced by avoiding redundant file reads.
• Database metadata files are cached in memory after first read.
• The Tesseract version and other slow metadata lookups are cached per process – the Tesseract version fetch alone took ~20 ms on a typical machine. This will speed up Gramps Web initial load in the browser.
• The undo-database schema migration check is no longer done in every request. Pre-3.0 databases can still be migrated with python -m gramps_webapi grampsdb migrate-undodb.

More reliable anonymous telemetry

Telemetry reporting is more robust in multi-worker deployments: the server UUID is now consistent across all workers, duplicate pings from concurrent workers are prevented, and any network or HTTP errors are caught and logged rather than surfacing as API errors. The anonymous tree UUID is now generated with faster hashing function, which is more appropriate for this use case and avoids unnecessary delays.

Place references in place profile

The extended place profile now includes a list of all places that reference the given place – i.e., places for which this place is a parent in the hierarchy. This enables an interface improvement in the Gramps Web frontend.

Cache-Control header for translations

The translation endpoint now returns a Cache-Control header, allowing clients and CDNs to cache translation files and avoid unnecessary round-trips.

Fix: Docker image size

After switching to Debian trixie in v3.11, users noticed a bloated Docker image size. The issues causing this have been resolved and Docker images are now back to the size before the switch.

Full Changelog: https://github.com/gramps-project/gramps-web-api/compare/v3.11.1...v3.12.0

This release fixes a security vulnerability in the media ZIP archive upload endpoint. See the related security advisory for details.

Improved thumbnail handling

Thumbnails now use the modern AVIF format that offers better compression (smaller file size at same or better quality) compared to JPEG. Thumbnails will be automatically generated as needed - the upgrade might be a good moment to clear your thumbnail cache.

The thumbnail endpoints also got a new optional query parameter that will ease thumbnail caching by the Gramps web frontend.

Remote vector embedding support

So far, the vector embeddings required for semantic search and AI chat were always computed by the background worker. In this release, @cbcoutinho added support for alternatively using an external provider for embedding computation. It supports both a local Ollama container or a remote API like OpenAI's.

Faster place list

The places endpoint got a new query paremeter that allows skipping the costly calculation of the place hierarchy for each place. This will speed up loading of Gramps Web's map view for trees with a large number of places.

Security fix: private sub-objects in non-private objects

Users with "Guest" permissions (the lowest permission level for registered users in Gramps Web) do not have access to objects marked as "private", and this is respected everywhere in Gramps Web API. However, Gramps also allows marking parts of objects as private when the object itself is not private, such as a person's name.

It has been realized that Gramps' private proxy database class, which is used to filter out private information, does not filter out those private sub-objects of non-private objects properly under certain circumstances.

Although the Gramps Web frontend only allows setting privacy on entire objects, this bug could potentially leak private information if tree owners have made sub-objects private.

A security advisory has been created for maximum transparency.

New Contributors

• @cbcoutinho made their first contribution in https://github.com/gramps-project/gramps-web-api/pull/776

Full Changelog: https://github.com/gramps-project/gramps-web-api/compare/v3.10.0...v3.11.0

Three minor releases in two weeks – don't get used to this pace! In any case, this release adds three smaller features and resolves 5 bugs.

New Features

• Strikethrough tags (supported by Gramps since v5.2) are now allowed in note HTML output, by @DavidMStraub in https://github.com/gramps-project/gramps-web-api/pull/794
• The gender "Other" (supported by Gramps since v5.2) is now supported everywhere, by @DavidMStraub in https://github.com/gramps-project/gramps-web-api/pull/795
• Endpoints that support person profile now allow customizing the precision of the age display (years only, year/month, year/month/day) like the timeline endpoints, by @DavidMStraub in https://github.com/gramps-project/gramps-web-api/pull/793

Bug Fixes

• Tags cannot be edited, by @DavidMStraub in https://github.com/gramps-project/gramps-web-api/pull/796
• Regression in OIDC authentication (affecting Keycloak setups), by @DavidMStraub in https://github.com/gramps-project/gramps-web-api/pull/799
• Death/birth reference indices are incorrect after changing event type, by @DavidMStraub in https://github.com/gramps-project/gramps-web-api/pull/797
• Require permissions for custom filters by @DavidMStraub in https://github.com/gramps-project/gramps-web-api/pull/513
• Fix localized type strings corrupting event types in fix_object_dict() by @mahula in https://github.com/gramps-project/gramps-web-api/pull/770

New Contributors

• @mahula made their first contribution in https://github.com/gramps-project/gramps-web-api/pull/770

Full Changelog: https://github.com/gramps-project/gramps-web-api/compare/v3.9.1...v3.10.0

This bug fix release fixes a regression affecting the task status endpoint for background tasks, which lead to errors in the Web Sync addon.

Allow editing researcher

Researcher details have been made accessible in Gramps Web 25.11. Now, Gramps Web API supports modifying those details by a PUT request to /api/metadata/researcher. Owner permissions are required.

Allow renaming the database

It's now possible to change the name of the underlying Gramps database, even in a single-tree setup, by sending a PUT request to /api/trees/-/.

Since single-tree setups currently identify the Gramps tree by name, this requires setting a new, additional configuration option TREE_ID (or the corresponding environment variable GRAMPSWEB_TREE_ID) to the tree's ID (equal to the name of the database directory, displayed in Gramps Web under "system information"). Renaming a tree in a single-tree setup without TREE_ID set will fail.

Full Changelog: https://github.com/gramps-project/gramps-web-api/compare/v3.8.0...v3.9.0

New API documentation architecture

The main change in this release is to migrate from a manually created API specification to an automatically generated one using flask-smorest. This has several benefits:

• Latent documentation errors are (missing parameters, incorrect trailing slashes) are resolved and prevented for the future
• The OpenAPI specs are upgraded from OpenAPI v2 to v3
• Gramps Web API now always serves the Swagger UI with the current API docs and allows to execute API calls from the UI

Other changes

• Solve issue #584: add config parameter PILLOW_MAX_IMAGE_PIXELS by @Jacute in https://github.com/gramps-project/gramps-web-api/pull/774
• Don't push images from forks by @hgohel in https://github.com/gramps-project/gramps-web-api/pull/782

New Contributors

• @Jacute made their first contribution in https://github.com/gramps-project/gramps-web-api/pull/774

Full Changelog: https://github.com/gramps-project/gramps-web-api/compare/v3.7.1.1...v3.8.0

The only purpose of this release is to resolve a problem with the ARM64 docker release image.

This is a maintenance release with two minor improvements/fixes:

• Using recent versions of the boto3 library can lead to problems when using media object storage on GCS. This is solved by https://github.com/gramps-project/gramps-web-api/pull/758
• Changing the email address to one that already exists in the user database lead to a server error. Now, a meaningful error message and the appropriate HTTP status 409 is returned instead. Added in https://github.com/gramps-project/gramps-web-api/pull/757

GEDCOM 7 Import Support (#751)

Gramps Web now supports importing family tree data in the GEDCOM 7 format, making it easier to migrate from other genealogy programs. GEDCOM 7 is the latest version of the widely-used file format for sharing genealogy data. The system automatically detects whether you're importing a GEDCOM 5.5 or GEDCOM 7 file and handles it appropriately, so you don't need to worry about which version you have.

Username Change Support (#748)

Backend support for changing usernames has been added to the API. This enables a future Gramps Web user interface improvement.

Performance Analysis Tool (#750)

A new built-in profiling tool helps understand API performance characteristics across different configurations. It measures response times for common operations like viewing people, searching, and generating ancestor trees, providing insights into how performance varies with different hardware, database backends, and tree sizes. This data helps guide optimization efforts and understand system bottlenecks.

Administrators can run the tool with:

python3 -m gramps_webapi profile run --tree my_tree --username admin

Full Changelog

For a complete list of changes, see the commit history.