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

Configuring ARLAS-wui

ARLAS-wui app settings

With environment variables

With file/URL based settings

File

URL

ARLAS-wui settings properties

Authentication

Persistence

Base url/href properties

ARLAS-wui configuration file

Embarked config.json file

File

URL

Fetched from ARLAS-persistence server

How to obtain a config.json file?

Translation files

File

URL

about.md file

File

URL

How to obtain a `config.json` file?

`about.md` file