Server Configuration¶
Using the default Docker image, all necessary configuration can be made from the browser. However, depending on the deployment, it can be necessary to customize the server configuration.
This page lists all methods to change the configuration and all existing configuration options.
Configuration file vs. environment variables¶
For the settings, you can either use a configuration file or environment variables.
When you use the Docker Compose based setup, you can include a configuration file by adding the following list item under the volumes:
key in the grampsweb:
block:
- /path/to/config.cfg:/app/config/config.cfg
/path/to/config.cfg
is the path to the config file in your server's file system (the right-hand side refers to the path in the container and must not be changed).
When using environment variables,
- prefix every setting name with
GRAMPSWEB_
to obtain the name of the environment variable - Use double underscores for nested dictionary settings, e.g
GRAMPSWEB_THUMBNAIL_CACHE_CONFIG__CACHE_DEFAULT_TIMEOUT
will set the value of theTHUMBNAIL_CACHE_CONFIG['CACHE_DEFAULT_TIMEOUT']
config option
Note that configuration options set via the environment take precedence over the ones in the configuration file. If both are present, the environment variable "wins".
Existing configuration settings¶
The following configuration options exist.
Required settings¶
Key | Description |
---|---|
TREE |
The name of the family tree database to use. Show available trees with gramps -l . If a tree with this name does not exist, a new empty one will be created. |
SECRET_KEY |
The secret key for flask. The secret must not be shared publicly. Changing it will invalidate all access tokens. |
USER_DB_URI |
The database URL of the user database. Any URL compatible with SQLAlchemy is allowed. |
Info
You can generate a secure secret key e.g. with the command
python3 -c "import secrets;print(secrets.token_urlsafe(32))"
Optional settings¶
Key | Description |
---|---|
MEDIA_BASE_DIR |
Path to use as base directory for media files, overriding the media base directory set in Gramps. When using S3, must have the form s3://<bucket_name> |
SEARCH_INDEX_DB_URI |
Database URL for the search index. Only sqlite or postgresql are allowed as backends. Defaults to sqlite:///indexdir/search_index.db , creating an SQLite file in the folder indexdir relative to the path where the script is run |
STATIC_PATH |
Path to serve static files from (e.g. a static web frontend) |
BASE_URL |
Base URL where the API can be reached (e.g. https://mygramps.mydomain.com/ ). This is necessary e.g. to build correct password reset links |
CORS_ORIGINS |
Origins where CORS requests are allowed from. By default, all are disallowed. Use "*" to allow requests from any domain. |
EMAIL_HOST |
SMTP server host (e.g. for sending password reset e-mails) |
EMAIL_PORT |
SMTP server port. defaults to 465 |
EMAIL_HOST_USER |
SMTP server username |
EMAIL_HOST_PASSWORD |
SMTP server password |
EMAIL_USE_TLS |
Boolean, whether to use TLS for sending e-mails. Defaults to True . When using STARTTLS, set this to False and use a port different from 25. |
DEFAULT_FROM_EMAIL |
"From" address for automated e-mails |
THUMBNAIL_CACHE_CONFIG |
Dictionary with settings for the thumbnail cache. See Flask-Caching for possible settings. |
CELERY_CONFIG |
Settings for the Celery background task queue. See Celery for possible settings. |
REPORT_DIR |
Temporary directory where the output of running Gramps reports will be stored |
EXPORT_DIR |
Temporary directory where the output of exporting the Gramps database will be stored |
REGISTRATION_DISABLED |
If True , disallow new user registration (default False ) |
Info
When using environment variables for configuration, boolean options like EMAIL_USE_TLS
must be either the string true
or false
(case sensitive!).
Settings only for PostgreSQL backend database¶
This is required if you've configured your Gramps database to work with the PostgreSQL addon.
Key | Description |
---|---|
POSTGRES_USER |
The user name for the database connection |
POSTGRES_PASSWORD |
The password for the database user |
Settings relevant for hosting multiple trees¶
The following settings are relevant when hosting multiple trees.
Key | Description |
---|---|
MEDIA_PREFIX_TREE |
Boolean, whether or not to use a separate subfolder for the media files of each tree. Defaults to False , but strongly recommend to use True in a multi-tree setup |
NEW_DB_BACKEND |
The database backend to use for newly created family trees. Must be one of sqlite , postgresql , or sharedpostgresql . Defaults to sqlite . |
Settings only for AI features¶
These settings are needed if you want to use AI-powered features like chat or semantic search.
Key | Description |
---|---|
LLM_BASE_URL |
Base URL for the OpenAI-compatible chat API. Defaults to None , which uses the OpenAI API. |
LLM_MODEL |
The model to use for the OpenAI-compatible chat API. If unset (the default), chat is disabled. |
VECTOR_EMBEDDING_MODEL |
The Sentence Transformers model to use for semantic search vector embeddings. If unset (the default), semantic search and chat are disabled. |
Example configuration file¶
A minimal configuration file for production could look like this:
TREE="My Family Tree"
BASE_URL="https://mytree.example.com"
SECRET_KEY="..." # your secret key
USER_DB_URI="sqlite:////path/to/users.sqlite"
EMAIL_HOST="mail.example.com"
EMAIL_PORT=465
EMAIL_USE_TLS=True
EMAIL_HOST_USER="gramps@example.com"
EMAIL_HOST_PASSWORD="..." # your SMTP password
DEFAULT_FROM_EMAIL="gramps@example.com"