Configuration Overview

Katalogue configuration is performed in a number of different locations:

Frontend Service (spa)

The configuration required for the frontend application can be set both in the config file /services/spa/src/appsettings.json or as environment variables. Note that the environment variables must be set during the Docker build stage, they cannot be injected at Docker Startup phase due to the nature of Reactjs.

Some settings can be set in multiple locations and the list below is ordered by priority from high to low. Higher priority means that a configuration parameter set there overrides any value set in a source with lower priority, e.g. environment variables overrides parameters set in the configuration file or database table.

Environment variables
Configuration file (/services/spa/appsettings.json)
Default configuration file (/services/spa/appsettings_default.json)

The file /services/spa/src/appsettings_default.json can be used as an example and template for the configuration file.

See the Configuration Parameter Reference for all available config parameters.

Initial Configuration

Set the URL in /services/spa/src/appsettings.json to point at the Katalogue API backend server.

Backend Service (api)

The Katalogue API backend service uses a number of sources for configuration, see below. Some settings can be set in multiple locations and the list below is ordered by priority from high to low. Higher priority means that a configuration parameter set there overrides any value set in a source with lower priority, e.g. environment variables overrides parameters set in the configuration file or database table.

Environment variables
Configuration file (/services/api/config/appsettings.json)
Default configuration file (/services/api/config/appsettings_default.json)
Database table (public.settings.setting_value)
Default value in database table (public.settings.setting_default_value)

See the Configuration Parameter Reference for all available config parameters.

Environment Variables

The primary use case for these is to set passwords and secrets like the encryption key, Azure client secret and SMTP mail server password. There are only a few parameters that can be set as environment variables, see table below.

Configuration File (`appsettings.json`)

The purpose of this file is to set configuration parameters required to start the backend service, and a number of parameters that are considered to be static during the lifetime of the application.

The configuration file is the only place where all parameters can be set. The environment variables and database table contain a subset of the available parameters.

The configuration file is located here: /services/api/config/appsettings.json

The file /services/api/config/appsettings_default.json can be used as an example and template for the configuration file.

Database Table (`public.settings`)

The database table contains parameters that might change during the lifetime of the applications. All parameters (with a few exceptions) in the database can be changed through the Settings page in the Katalogue GUI (requires the admin role).

Examples

Config File

To set OIDC_APPLICATION_ID in the appsettings.json config file (here, “authentication” and “oidc” is the Category and Subcategory for the parameter as specified in the Configuration Parameter Reference):

{
  "config":
  {
    ...,
    "authentication": {
      "oidc": {
        "OIDC_APPLICATION_ID": "abcd-12345678-defg"
      }
    }
    ...,
  }
}

Environment Variable

To set OIDC_APPLICATION_ID as an environment variable (use just the parameter name):

EXPORT OIDC_APPLICATION_ID=abcd-12345678-defg

Database Table

To set OIDC_APPLICATION_ID in the database table, use the GUI (preferred) or a query like the one below.

UPDATE public.setting
    SET setting_value = 'abcd-12345678-defg'
WHERE setting_code = 'OIDC_APPLICATION_ID';