Example deployment configuration#

This section contains two working versions of a full deployment configuration. These configuration files have also been installed along with the deployment. You can find them in the data files under share/freva/deployment/config of your python environment, for example:
/usr/share/freva/deployment/config for system wide installations.
$CONDA_PREFIX/share/freva/deployment/config for conda based installations.
~/.local/share/freva/deployment/config for user based installations.
Typical deployment#

The inventory.toml file contains a typical setup for freva. The services are installed with root privileges on remote machines. The core is installed under a normal user on a login node of a HPC system.
# NOTE: this key must be the first in the file.
project_name = "freva"

## The `deployment_method` key sets the option of how the installation
## of the service is realised. `docker`, `podman` leverages podman or docker,
## `conda` uses conda-forge to install the service while `k8s` involves a
### kubernetes based deployment
## Chosse between: "docker", "podman", "conda", "k8s"
deployment_method = "podman"


## Specify the path to the SSL certificate files used for secure connections
## to the vault server or as web certificates.
[certificates]

## Path to the public key file.
public_keyfile = ""

## Path to the private key file.
private_keyfile = ""

## Path to the chain file.
chain_keyfile = ""

[db]
## Config variables for the database service.

## Specify the host name were the database server should be deployed
db_host = "localhost"

## The freva infrastructure uitilises a small vault server that stores
## database secrets for client connections. You can specify the host name
## where this server should be running. If you don't set it (default)
## the vault server will be deployed on the database host.
vault_host = ""

## The database runs in a Docker container. You can change the port
## that is exposed to the external network. Every DB connection from
## outside the container uses this port.
port = 3306

## Set the username of the MariaDB user.
user = "freva"

## Set the name of the MariaDB database.
db = "frevadb"

## If the username running the deployment software and the username
## that installs the services differ, instruct Ansible to use the
## specified username for SSH connections to the target server.
## If left blank, the current username will be used.
ansible_user = ""

## Set the become (sudo) username to change to for installing the services.
## Leave blank to utilise a non-privileged user-based installation.
## Non-privileged installation means the system will be installed in the
## user space of the user that logs on to the system.
ansible_become_user = "root"

## Ansible needs a Python 3 interpreter on the target server. This interpreter
## can be set for custom Python 3 instances. By default, Ansible will try
## to use the default Python interpreter path /usr/bin/python.
ansible_python_interpreter = ""

## Indicate whether to empty any pre-existing folders/docker volumes.
## Useful for a truly fresh start (default: false).
wipe = false

## Set the path where the permanent database data should be stored.
## By default, this is set to /opt/freva/<project_name>/db_service.
data_path = "/opt/freva"

## Set the username that will own all files created by the service such as
## database files etc. This can be useful if multiple users take turn in
## deploying and administering the service. The value of the username
## will default to the user that deploys the service
admin_user = ""

[freva_rest]
## Specify the host name were the ferva-rest-api server should be deployed
freva_rest_host = "localhost"

## To search for data the freva-rest-api needs a metadata index service.
## Typically this services apache solr. You can set the host where this
## index server should be running at. Leave empty to deploy the service
## on the same host as the freva-rest-api
search_server_host = ""

## Search statistics and user data related will be stored in a mongoDB
# service You can set the host where the server should be running at.
## Leave empty to deploy the service on the same host as the freva-rest-api
mongodb_server_host = ""

### The the host name of the redis-cache, this cache is used for caching
### different kinds of data. If not set this will fall back to the host name
### of the rest-api server.
redis_host = ""

### Set the hostname(s) for the data-loading portal. The data-loading portal
### is a services that provisions data via zarr. The data-loading portal is
### a distributed system, meaning that you can set multiple hostnames that
### form a distributed memory. The first entry will be used as the master
### scheduler and the consecutive ones as workers. If you leave this blank
## then the service will be disabled.
data_loader_portal_hosts = ""

## Set the amount of memory allocated to the search engine (Solr).
solr_mem = "4g"

## Set the port for the freva_rest service.
freva_rest_port = 7777

## Set the become (sudo) username to change to for installing the services.
## Leave blank to utiilise a non-privileged user-based installation.
## Non-privileged installation means the system will be installed in the
## user space of the user that logs on to the system.
ansible_become_user = "root"

## Ansible needs a Python 3 interpreter on the target server. This interpreter
## can be set for custom Python 3 instances. By default, Ansible will try
## to use the default Python interpreter path /usr/bin/python.
ansible_python_interpreter = ""

## If the username running the deployment software and the username
## that installs the services differ, instruct Ansible to use the
## specified username for SSH connections to the target server.
## If left blank, the current username will be used.
ansible_user = ""

## Indicate whether to empty any pre-existing folders/docker volumes.
## Useful for a truly fresh start (default: false).
wipe = false

## Set the path where the permanent freva-rest data should be stored.
## By default, this is set to /opt/freva.
data_path = "/opt/freva"

### Indicate whether or not the redis-caching services will be shared among
### other freva instances. In this case the name of the service will simply
### be called redis-cache service otherwise <project_name>-cache
shared_cache = false

### Authentication is done via open id connect. This deployment assumes that
## you have set up and configured a open id connect host. Set the url
## to the open id discovery. This url usually ends with
## `.well-known/openid-configuration`
oidc_url = ""


### Set the client id (app name) of the open id connect service.
oidc_client = "freva"

### If you have configured that your OIDC client needs a client secret
### you can define it here, if not then you don't have to set it
oidc_client_secret = ""

## Set the username that will own all files created by the service such as
## database files etc. This can be useful if multiple users take turn in
## deploying and administering the service. The value of the username
## will default to the user that deploys the service
admin_user = ""

# A dict of claim-based filters in {<key1.key2> = [<pattern>]}. Each filter
# matches if the decoded JWT contains the specified claim
# (e.g., group, role) and its value includes the given pattern. Patterns can
# be plain substrings or regular expressions.
# Nested claims are defined by '.' separation.
oidc_token_claims = {}


[core]
## Specify the host name were the client should be deployed
core_host = "localhost"

## List of users that can alter the configuration of the freva command line interface.
## If blank, the user that runs the deployment is chosen.
admins = ""

## The path where the core library should be installed.
## Conda is used for installing the core library. Setting this
## instructs Conda to install a new Conda environment into this folder.
install_dir = "/opt/freva/conda"

## The directory where the project configuration files will be stored.
## This can be useful if you want to set up multiple freva instances with
## the same software stack (Anaconda environment). Leave blank to use the
## same directory as anaconda installation directory.
root_dir = "/home/freva/freva-env"

## If you do not wish to install a new freva Conda environment but only
## (re)configure an already installed system, you can set the `install`
## variable to false. This can be useful if you have a central instance
## of freva deployed and want to set up a project-specific configuration
## that uses this central instance.
install = true

## The directory where user-specific output will be stored.
## If left blank, it defaults to the folder that holds the project
## specific (config) data `<root_dir>/work`.
base_dir_location = ""

## Set the directory holding user content, like plots, for the web user
## interface. Note: After a plugin application, display content of the plugin
## output will be copied to this directory. The default location of this
## directory (if left blank) is the user-specific output dir
## `<base_dir_location/share/preview`.
preview_path = ""

## Set the workload manager system. Currently available options are:
## "local", "slurm", "pbs", "lfs", "moab", "oar", "sge".
scheduler_system = "local"

## Set the path to the directory that contains the stdout of the plugins.
## This directory must be accessible to the web UI. The workload manager
## will write the stdout into this directory. Defaults to user-specific
## output dir `<base_dir_location>/share`.
scheduler_output_dir = ""

## Set the target architecture of the system where the backend will be installed.
## You can choose from the following options:
## linux-64 (default), linux-aarch64, linux-ppc64le, linux-s390x,
## oss-64, osx-arm64
arch = "linux-64"

## If you need to install the core or its configuration as a different user,
## set the ansible_become_user variable. This will install the core as a
## different user. Leave blank if not needed.
ansible_become_user = ""

## If the username running the deployment software and the username
## that installs the services differ, instruct Ansible to use the
## specified username for SSH connections to the target server.
## If left blank, the current username will be used.
ansible_user = ""

## Ansible needs a Python 3 interpreter on the target server. This interpreter
## can be set for custom Python 3 instances. By default, Ansible will try
## to use the default Python interpreter path /usr/bin/python.
ansible_python_interpreter = ""

## If you want to set special group rights for freva configuration files,
## you can set the admin_group variable. If `admin_group` is set, then config
## files and directories in the `base_dir_location` are only writable to
## `admin_group`.
admin_group = ""

## Indicate whether to empty any pre-existing folders/docker volumes.
## Useful for a truly fresh start (default: false).
wipe = false

[web]
## Specify the host name were the web ui service should be deployed
web_host = "localhost"

## Set the URL of the web user interface.
project_website = "www.freva.dkrz.de"

## Freva can connect to a GPT service (that has to be set up seperately)
## you can set the <HOSTNAME>:<PORT> of this service - if configured.
## if you leave this blank, the website will not provid the chat interface.
chatbot_host=""

## Ansible needs a Python 3 interpreter on the target server. This interpreter
## can be set for custom Python 3 instances. By default, Ansible will try
## to use the default Python interpreter path /usr/bin/python.
ansible_python_interpreter = ""

## If the username running the deployment software and the username
## that installs the services differ, instruct Ansible to use the
## specified username for SSH connections to the target server.
## If left blank, the current username will be used.
ansible_user = ""

## Set the path where the permanent web data should be stored.
## By default, this is set to /opt/freva.
data_path = "/opt/freva"

## Set the main HTML color scheme.
main_color = "Tomato"
## Set the HTML border colors.
border_color = "#6c2e1f"
## Set the HTML hover colors.
hover_color = "#d0513a"

## The "About Us" text is a small blurb about freva within the project.
about_us_text = ""

## Set the path to the institution logo. This should be the path to the logo
## as seen by the target system. Ensure this path exists on the target machine.
institution_logo = ""

## Set email addresses for contact points for users.
contacts = ""

## Set the postal address, which will appear in the footer of the website.
imprint = "Project name, German Climate Computing Centre (DKRZ), Bundesstr. 45a, 20146 Hamburg, Germany."

## Here you can set a lengthy project description.
## You can also set a path to a file containing the information,
## like an HTML file.
homepage_text = "Bal bla bla."

## Set a one-line blurb of the project.
homepage_heading = "Short description of the project."

## Set the name of the project/institution, such as FUB, DWD, DKZ, etc.
institution_name = "Freva"

## Set the workload manager scheduler host. The web app will log into this
## machine via SSH to submit plugin jobs.
scheduler_host = ["localhost"]

## Set the hosts that are allowed to execute WSGI code.
allowed_hosts = ["localhost"]

## Turn on/off debug mode on the website.
debug = false

## Specify the plugin ID to be used for the web tour.
guest_tour_result = 105

## Set the menu entries.
# Menu entries consist of three elements: [Label, URL, HTML ID] -> e.g., ["Plugins", "plugins:home", "plugin_menu"].
menu_entries = [
    ["Data-Browser", "solr:data_browser", "browser_menu"],
    ["Plugins", "plugins:home", "plugin_menu"],
    ["History", "history:history", "history_menu"],
    ["Result-Browser", "history:result_browser", "result_browser_menu"],
    ["Help", "plugins:about", "doc_menu"]
]

## Set the become (sudo) username to change to for installing the services.
## Leave blank to utiilise a non-privileged user-based installation.
## Non-privileged installation means the system will be installed in the
## user space of the user that logs on to the system.
ansible_become_user = "root"


## Set the username that will own all files created by the service such as
## database files etc. This can be useful if multiple users take turn in
## deploying and administering the service. The value of the username
## will default to the user that deploys the service
admin_user = ""