v0.7.0

This release contains breaking changes. Please read to the end of the release notes for upgrade instructions.

Multi-tree support

The main new feature in this release is initial support for hosting multiple family trees. As of this version, a Gramps Web API instance can serve multiple family tree databases, but each user account is linked to a single tree.

The default setup is still to serve a single family tree and the multi-tree setup is only recommended for advanced users. See the Gramps Web documentation site for instructions.

The following improvements are related to this new feature:

Add admin role

In addition to the "owner" role (that has full control of a family tree), there is now an additional role "admin" that has full control over all trees. This change affects also the single-tree setup: only "admin" users can view or edit the /api/config endpoints.

Add tree endpoints

The new /api/tree endpoints allow listing existing family trees as well as creating new ones.

Add people and media quotas

In order to manage a multi-tree, multi-user server, the possibility of imposing quotas on the total size of media files or the total number of people per tree has been added. When the quotas are reached, no media files or people can be added anymore.

Add shared PostgreSQL support

Support has been added for the SharedPostgreSQL Gramps addon, that allows storing multiple Gramps family tree databases in a single PostgreSQL database in an isolated way, which is particularly suited for a multi-tree Gramps Web API setup.

Other improvements

Use task queue for reports

If configured, the task queue is now also used for generating reports, which will prevent long running reports from causing a timeout.

Localize reports

The report endpoints gain a new locale parameter, which allows generating localized reports.

Bug fixes

• A bug affecting the synchronization of media files hosted on S3 with the Gramps Web Sync addon has been fixed
• Support for SMTP servers requiring authentication via STARTTLS has been added

Upgrade instructions

This release contains a change of the user database schema. If you use the default Docker image, the migration is done automatically. If not, please run python3 -m gramps_webapi --config path/to/config user migrate to migrate, replacing path/to/config with the path to your configuration file.

v0.6.1

This bugfix release fixes a regression introduced in v0.6.0 (#356).

v0.6.0

This is the first in several releases which introduce some API changes that are foreseen to enable support for hosting multiple family tree databases ("trees") on a single Gramps Web API deployment. Most (but not all) of these changes will be backwards compatible and the existing possibility of hosting a single tree will not be removed.

API changes

• The DISABLE_AUTH config option has been removed. It is no longer possible to run the API without authentication. See the docs for how to still easily query the API in local testing.
• The search index is moved to a subdirectory of where it used to be. This means that after upgrading, the search index must be fully rebuilt. This can be done by running python3 -m gramps_webapi --config path/to/config search index-full on the command line or simply using the new "update search index" button in Gramps Web.
• The thumbnail cache keys have changed. This only means the existing cached thumbnails will be ignored and it might make sense to clear the cache before the upgrade.
• The format of the tokens is changed which might force users to logout if they are active during the upgrade (but it should not invalidate the refresh tokens).
• Setting config options via environment vairables without the GRAMPSWEB_ prefix is deprecated and will be removed in a future release. Note that the unprefixed variables are already ignored if a corresponding prefixed one is present and the default docker file defines some of them. Those can only be overridden with prefixed ones.

Note that this release changes the schema of the user database. When using the default docker image, the migration will be performed automatically. Otherwise, use the (new) command python3 -m gramps_webapi --config path/to/config user migrate

New features

• Database exports now profit from the new task queue, if configured. Instead of generating and downloading the export in a single request with GET, a new POST endpoint triggers the export in the background and, once complete, can be fetched from a separate endpoint. See the API spec for details.
• The search endpoint now supports searching for non-ASCII strings by querying for a transliterated string. For instance, the query string Beograd will also yield results that only contain Београд.

Security issue

Users running the development version off the master branch (or the latest-devel docker image) may be affected by a security issue that was introduced in commit 0f99a9f 9 days ago and fixed in 338837a today. It caused the value of environment variables, such as SECRET_KEY, to be logged as clear text on the server. Users who think they might be affected by this issue are advised to change their secret key.

v0.5.1

This is a bug fix release solving an issue with file import.

v0.5.0

New feature: background task queue

The main new feature in this release is the addition of an optional background task queue powered by Celery. This makes it possible to run long-running tasks, like importing a large family tree or rebuilding the search index, in a separate process without blocking the web server and timing out.

Running celery is particularly convenient when using docker compose. For examples how to set it up, see the updated deployment documentation at https://gramps-project.github.io/web/.

New endpoints

• /api/tasks/ for monitoring the status of background tasks
• /api/search/index for updating the search index

Bugs fixed

• Fixed options format to make family descendant chart work (#335, thanks @jeffasuk)
• Add message ID to e-mail header (GMail was not accepting password reset e-mails) #333

Changes to configuration handling

Using the new "from prefixed environment" option introduced in Flask 2.2, all config options, even nested dictionaries, can now be specified as environment variables. They need to be prefixed with GRAMPSWEB_. This is not a breaking change.

Change to default configuration

• The thumbnail cache is now set to never expire by default.

v0.4.4

This is a maintenance release.

• Fix issue with rate limiting #326
• Fix EXIF orientation issue #323

v0.4.3

This is a minor release fixing an issue with the base docker image.

v0.4.2

Improvements in this release:

• The /api/media/<handle>/file endpoint gets a new boolean download query parameter that, if true, sets the content disposition of the HTTP response to "attachment", triggering a download in the browser (#311)
• For /api/reports/<id>/file, the JWT can now also be supplied in the query string, as for media files (#312)
• Changed default locale of Docker images to en_US (#314)
• The list of strings can now also be POST-ed as body JSON /api/translations/<lang>, avoid issues with long query length for GET (#313)
• The /api/relations/<handle1>/<handle2> should now be faster in many cases (#316)
• Several dependencies updated (#315)

v0.4.1

This minor release fixes one issue and makes one minor improvment:

• Square thumbnails (such as used for person pages in Gramps Web) were not centered correctly for images in landscape format.
• Now when the TREE config option points to a tree that does not exist, a new empty SQLite database is created. This will simplify deployment.

v0.4.0

This new release is packed with features but also contains breaking changes:

Important: Breaking changes

• This release changes the format of authentication tokens (in preparation for future features, e.g. being able to change a user name). This will invalidate all existing tokens, forcing users to login again.
• The format of the user database is changed. If you use the default docker image, the migration is done automatically. Otherwise, run a migration using

GRAMPS_API_CONFIG=/path/to/config.cfg python3 -m alembic upgrade head

New features

• Endpoint for face detection in media images using OpenCV, /api/media/{handle}/face_detection #291
• New endpoint /api/importers/{format}/file for importing a family tree, supporting all file formats supported by Gramps, including Gramps XML and GEDCOM #292
• Allow creating an admin user if no user exists yet #293
• New endpoint /api/config/ for changing the configuration #295
• The default docker image now creates a secure, random token if none is specified #299