Configuring ARLAS-wui

ARLAS-wui has different elements of configuration.

  • The web application settings file (settings.yaml) that defines the application behaviour at deployment: use of authentication, peristence, ...
  • The base URL/href properties.
  • The Arlas configuration file (config.json) that defines the content of the application when it runs: map, timeline, analytics-board, ...
  • The translation files.
  • The about.md file.

ARLAS-wui app settings

The app settings is a yaml file that you can customise:

With environment variables

ARLAS-wui can run as a docker container. A rich set of properties of the settings file can be overriden by passing environment variables to the container:

docker run -ti -d \
   --name arlas-wui \
   gisaia/arlas-wui:latest

All supported environment variables are listed below.

With file/URL based settings

Instead of overriding some properties of the settings file, it is possible to start the ARLAS-wui container with a given settings file.

File

The ARLAS-wui container can start with a mounted settings file thanks to docker volume mapping. For instance, if the current directory of the host contains a settings.yaml file, the container can be started as follow:

docker run -ti -d \
   --name arlas-wui \
   -v `pwd`/settings.yaml:/usr/share/nginx/html/settings.yaml \
   gisaia/arlas-wui:latest

URL

The ARLAS-wui container can start with a settings file that is downloaded before starting up. The settings file must be available through an URL accessible from within the container. The URL is specified with an environment variable:

Environment variable Description
ARLAS_SETTINGS_URL URL of the ARLAS settings file to be downloaded by the container before starting

For instance, if the current directory of the host contains a settings.yaml file, the container can be started as follow:

docker run -ti -d \
   --name arlas-wui \
   -e ARLAS_SETTINGS_URL="http://somemachine/settings.yaml" \
   gisaia/arlas-wui:latest

ARLAS-wui settings properties

Authentication

Environment variable ARLAS-wui settings variable Default Description
ARLAS_USE_AUTHENT authentication.use_authent false Defines whether to be authenticated to Auth0
ARLAS_AUTHENT_FORCE_CONNECT authentication.force_connect false When authentication is enabled, this option forces to be connected to Auth0 at application bootstrap
ARLAS_AUTHENT_USE_DISCOVERY authentication.use_discovery false Defines whether we use document discovery service
ARLAS_AUTHENT_ISSUER authentication.issuer 'NOT_CONFIGURED' The issuer's uri
ARLAS_AUTHENT_CLIENT_ID authentication.client_id 'NOT_CONFIGURED' The client's id as registered with the auth server
ARLAS_AUTHENT_REDIRECT_URI authentication.redirect_uri 'NOT_CONFIGURED' The client's redirectUri as registered with the auth server
ARLAS_AUTHENT_SILENT_REFRESH_REDIRECT_URI authentication.silent_refresh_redirect_uri 'NOT_CONFIGURED' The client's silentRefreshRedirectUri as registered with the auth server
ARLAS_AUTHENT_SCOPE authentication.scope 'NOT_CONFIGURED' The requested scopes, e.g:'openid profile'
ARLAS_AUTHENT_TOKEN_ENDPOINT authentication.token_endpoint 'NOT_CONFIGURED' Url of the token endpoint as defined by OpenId Connect and OAuth 2. Mandatory if use_discovery is false
ARLAS_AUTHENT_USERINFO_ENDPOINT authentication.userinfo_endpoint 'NOT_CONFIGURED' Url of the userinfo endpoint as defined by OpenId Connect. Mandatory if use_discovery is false
ARLAS_AUTHENT_JWKS_ENDPOINT authentication.jwks_endpoint 'NOT_CONFIGURED' JSON Web Key Set (https://tools.ietf.org/html/rfc7517) with keys used to validate received id_tokens. This is taken out of the disovery document. Mandatory if use_discovery is false
ARLAS_AUTHENT_LOGIN_URL authentication.login_url 'NOT_CONFIGURED' The auth server's endpoint that allows to log the user in when using implicit flow. Mandatory if use_discovery is false
ARLAS_AUTHENT_LOGOUT_URL authentication.logout_url 'NOT_CONFIGURED' Redirecting the user to this URL (https://YOUR_DOMAIN/v2/logout) clears all Single Sign-on (SSO) cookies set by Auth0 for the user. If you want to navigate the user to a specific URL after the logout, set that URL at the returnTo parameter. More details.
ARLAS_AUTHENT_SHOW_DEBUG authentication.show_debug_information false Defines whether additional debug information should be shown at the console
ARLAS_AUTHENT_REQUIRE_HTTPS authentication.require_https true Defines whether https is required
ARLAS_AUTHENT_RESPONSE_TYPE authentication.response_type 'NOT_CONFIGURED' Response type values, e.g: 'id_token token'
ARLAS_AUTHENT_SILENT_REFRESH_TIMEOUT authentication.slient_refresh_timeout 5000 Timeout for silent refresh
ARLAS_AUTHENT_TIMEOUT_FACTOR authentication.timeout_factor 0.75 Defines when the token_timeout event should be raised. If you set this to the default value 0.75, the event s triggered after 75% of the token's life time.
ARLAS_AUTHENT_ENABLE_SESSION_CHECKS authentication.session_checks_enabled true If true, the app will try to check whether the user is still logged in on a regular basis as described
ARLAS_AUTHENT_CLEAR_HASH authentication.clear_hash_after_login false Defines whether to clear the hash fragment after logging in
ARLAS_AUTHENT_STORAGE authentication.storage localstorage Defines where authentication information is stocked. localstorage (default value) or sessionstorage.
ARLAS_AUTHENT_DISABLE_AT_HASH_CHECK authentication.disable_at_hash_check false This property has been introduced to disable at_hash checks and is indented for Identity Provider that does not deliver an at_hash EVEN THOUGH its recommended by the OIDC specs.
ARLAS_AUTHENT_DUMMY_CLIENT_SECRET authentication.dummy_client_secred 'NOT_CONFIGURED' dummy string for tests. DO NOT USE IT in production environment.

Example of authentication setting

Check out this section to get an example of a working authentication setting

Persistence

Environment variable ARLAS-wui settings variable Default Description
ARLAS_PERSISTENCE_URL persistence.url 'NOT_CONFIGURED' URL to ARLAS-persistence server. ARLAS-persistence stores Arlas configuration files that ARLAS-wui serve. Details in the section below.

Base url/href properties

The properties below are configurable by environment variables only:

Environment variable Default Description From version
ARLAS_WUI_APP_PATH '/' Base URL 12.2.0
ARLAS_WUI_BASE_HREF '/' Base href 12.5.3

ARLAS-wui configuration file

The content of the application when it runs: map, timeline, analytics-board... is configured by a dedicated configuration file (config.json).

It is possible to customise and use a config.json that is:

  • embarked with the application;
  • fetched from ARLAS-persistence server.

Embarked config.json file

ARLAS-wui comes with an embarked config.json file that can be overriden with:

File

The ARLAS-wui container can start with a mounted config.json file thanks to docker volume mapping. For instance, if the current directory of the host contains a config.json file, the container can be started as follow:

docker run -ti -d \
   --name arlas-wui \
   -v `pwd`/config.json:/usr/share/nginx/html/config.json \
   gisaia/arlas-wui:latest

URL

The ARLAS-wui container can start with a config.json file that is downloaded before starting up. The settings file must be available through an URL accessible from within the container. The URL is specified with an environment variable:

Environment variable Description
ARLAS_WUI_CONFIGURATION_URL URL of the config.json file to be downloaded by the container before starting

For instance, if the current directory of the host contains a config.json file, the container can be started as follow:

docker run -ti -d \
   --name arlas-wui \
   -e ARLAS_WUI_CONFIGURATION_URL="http://somemachine/config.json" \
   gisaia/arlas-wui:latest

Fetched from ARLAS-persistence server

if ARLAS_PERSISTENCE_URL variable is set, ARLAS-wui accepts configurations files coming from in the given server.

In this case, you need the configuration Id to access it this way:

https://arlas-wui-domain?config_id=YOUR_CONFIG_ID

How to obtain a config.json file?

The config.json contains a JSON object that describes the content of ARLAS-wui application (map, analytics board, timeline, ...).

It respects the following JSON schema

You can create this file using ARLAS-wui-builder application that allows you

  • to download a generated JSON configuration as a config.json file
  • to store it with ARLAS-persistence in your file system, a filestore or a database

ARLAS-wui-builder

Check out this tutorial of how to use ARLAS-wui-builder application

Go further

See how the ARLAS-Exploration Stack works and how to Get started

Translation files

ARLAS-wui comes with a list of translatable keys.

Translations are edited in i18n files embarked with the application container in /usr/share/nginx/html/assets/i18n/ folder. It could be overriden by a:

File

The ARLAS-wui container can start with a mounted i18n file thanks to docker volume mapping. For instance, if the current directory of the host contains a fr.json file, the container can be started as follow:

docker run -ti -d \
   --name arlas-wui \
   -v `pwd`/fr.json:/usr/share/nginx/html/assets/i18n/fr.json \
   gisaia/arlas-wui:latest

In this case, you can access ARLAS-wui with the fr translation this way:

https://arlas-wui-domain?lg=fr

URL

Two environment variables are available to set a url to English and French translation files.

Name Description From version
ARLAS_WUI_I18N_EN_URL Url to English file to translate ARLAS WUI labels and tooltips. Translatable keys here 7.4.1
ARLAS_WUI_I18N_FR_URL Url to French file to translate ARLAS WUI labels and tooltips. Translatable keys here 7.4.1

For instance, if the current directory of the host contains a en.json file, the container can be started as follow:

docker run -ti -d \
   --name arlas-wui \
   -e ARLAS_WUI_I18N_EN_URL="http://somemachine/en.json" \
   gisaia/arlas-wui:latest

For other languages, you can use HTTP_RESOURCES environment variable

Name Description From version
HTTP_RESOURCES target1@url1,target2@url2. Comma separated target@url pattern. target is the file to replace inside the docker container. url is the url to the resource to store in target 10.0.0

For instance, if the current directory of the host contains a it.json file, the container can be started as follow:

docker run -ti -d \
   --name arlas-wui \
   -e HTTP_RESOURCES="/usr/share/nginx/html/assets/i18n/@http://somemachine/it.json" \
   gisaia/arlas-wui:latest

about.md file

It's a markdown file that can be used tp sum up what your ARLAS-wui app is presenting, add mentions, credits,...

This file is embarked with the application in /usr/share/nginx/html/about.md. It could be overriden by a:

File

The ARLAS-wui container can start with a mounted about.md file thanks to docker volume mapping. For instance, if the current directory of the host contains a about.md file, the container can be started as follow:

docker run -ti -d \
   --name arlas-wui \
   -v `pwd`/aout.md:/usr/share/nginx/html/about.md \
   gisaia/arlas-wui:latest

URL

An environment variable is available to set a url to an about.md file.

Name Description From version
ARLAS_WUI_ABOUT_URL file that can be used tp sum up what your ARLAS-wui app is presenting, add mentions, credits,... 5.0.2

For instance, if the current directory of the host contains a about.md file, the container can be started as follow:

docker run -ti -d \
   --name arlas-wui \
   -e ARLAS_WUI_ABOUT_URL="http://somemachine/about.md" \
   gisaia/arlas-wui:latest