Frontend configuration

The OpenCDMP webapp is configured through its config.json file. When the webapp container starts, it fills in config.json from the environment variables below, which the Docker example sets in its .env file (see the Docker Compose environment). Other values of config.json can be changed with a config-override.json file.

Environment variables

Core configuration

Env Variable	Description	Required	Default Value	Example
WEBAPP_API_URL	Address of the API, as the browser reaches it, with a trailing slash.	Yes	-	https://opencdmp.example.org/api/
INSTALLATION_URL	Address of the webapp, with a trailing slash.	Yes	-	https://opencdmp.example.org/
WEBAPP_BASE_URL	Base path of the webapp, when it is not served at the root of its host.	No	/	/opencdmp/
DEFAULT_CULTURE	Default language of the webapp, as an ISO 639 code.	No	en	en

Keycloak authentication

Env Variable	Description	Required	Default Value	Example
KEYCLOAK_ADDRESS	Keycloak server URL, including its relative path (/auth/ in the Docker example).	Yes	-	https://opencdmp.example.org/auth/
KEYCLOAK_REALM	Keycloak realm.	Yes	-	OpenCDMP
KEYCLOAK_CLIENT_ID	Keycloak client of the webapp.	Yes	-	webapp
KEYCLOAK_SCOPE	Scopes the webapp requests. They must include api (the API audience) and, for comments and notifications, annotation and notification.	No	openid profile email address phone api notification annotation identity_provider	openid profile email api notification annotation identity_provider

Appearance and accessibility

Env Variable	Description	Required	Default Value	Example
PRIMARY_COLOR	Main colour of the installation (theme.primaryColor). Each organisation can set its own on its Branding page.	No	-	#1e6b52
CSS_OVERRIDES	Style variables of the installation (theme.cssOverride): a JSON object of variable names and values, see Branding. The value is inserted into a JSON string, so escape its quotes; it cannot contain a comma, so set more than one variable in config-override.json instead.	No	-	{\"--mat-sys-primary\":\"#1e6b52\"}
USERWAY_ID	Account id of the UserWay accessibility widget (userWay.id). The widget is not loaded when it is empty.	No	-	<userway-account-id>

Logging

Env Variable	Description	Required	Default Value	Example
LOGGING_ENABLED	Writes the webapp's log messages to the browser console.	No	false	true

Overrides

To change other values of config.json, mount a config-override.json file at /usr/share/nginx/html/assets/config/config-override.json in the webapp container (the Docker example has the volume line commented out in docker-compose.override.yml). The webapp merges it over config.json when it loads: objects are merged key by key, and any other value that is not null in the override replaces the value of config.json, including values set from the environment variables. List only the keys you change. The sections you can change are listed below.

Notifications

"notification_service": {
    "enabled": true,
    "address": null
}

Variable	Description	Required	Default Value	Example
enabled	Shows the in-app notifications.	No	true	false
address	Address under which the webapp calls the notification service (<address>api/notification/...), with a trailing slash. When null, the webapp calls its own address, where the proxy forwards /api/notification/.	No	null	https://notifications.example.org/

Annotations

"annotation_service": {
    "enabled": true,
    "address": null
}

Variable	Description	Required	Default Value	Example
enabled	Shows comments on plans and assets.	No	true	false
address	Address under which the webapp calls the annotation service (<address>api/annotation/...), with a trailing slash. When null, the webapp calls its own address, where the proxy forwards /api/annotation/.	No	null	https://annotations.example.org/

Logging

When LOGGING_ENABLED is true, logLevels selects the levels written to the browser console.

"logging": {
    "logLevels": ["debug", "info", "warning", "error"]
}

Variable	Description	Required	Default Value	Example
logLevels	Levels to write.	No	["debug", "info", "warning", "error"]	["warning", "error"]

Sidebar menu

Default:

"sidebar": {
    "infoItems": [
        {
            "title": "SIDE-BAR.SUPPORT",
            "icon": "help",
            "routerPath": "/contact-support",
            "accessLevel": "authenticated"
        }
    ],
    "footerItems": [
        {
            "routerPath": "/about",
            "title": "FOOTER.ABOUT",
            "icon": "feedback",
            "accessLevel": "public"
        },
        {
            "routerPath": "/terms-and-conditions",
            "title": "FOOTER.TERMS-OF-SERVICE",
            "accessLevel": "public"
        },
        {
            "routerPath": "/glossary",
            "title": "FOOTER.GLOSSARY",
            "accessLevel": "public"
        },
        {
            "routerPath": "/user-guide",
            "title": "FOOTER.GUIDE",
            "accessLevel": "public"
        },
        {
            "routerPath": "/contact-support",
            "title": "FOOTER.CONTACT-SUPPORT",
            "accessLevel": "authenticated"
        }
    ]
}

Variable	Description	Required	Default Value	Example
title	Page title	Yes	-	page-title
routerPath	Internal path to the page	Yes¹	-	/<relative-route>
externalUrl	URL that leads to external view	Yes²	-	http://<base-route>/<route>
accessLevel	Access level of users allowed to view page	Yes	-	authenticated
icon	Sidebar menu material symbol icon that appears next to the title	No	-	feedback

¹ Required if not using externalUrl ² Required if not using routerPath

Authorization providers

authProviders sets the icon shown next to each email address on the profile page, by the identity provider the user signed in with through Keycloak. Providers that are not listed get the default icon.

Default:

"authProviders": {
    "defaultAuthProvider": {
        "name": "Default",
        "providerClass": "defaultIcon"
    },
    "authProviders": [
        {
            "name": "google",
            "providerClass": "googleIcon",
            "cultures": ["en"]
        },
        {
            "name": "facebook",
            "providerClass": "facebookIcon",
            "cultures": ["en"]
        }
    ]
}

Variable	Description	Required	Default Value	Example
name	Alias of the identity provider in Keycloak.	Yes	-	google
providerClass	Style class of the icon.	Yes	-	googleIcon
cultures	Languages, as ISO 639 codes, in which the icon is shown.	Yes	-	["en"]

UserWay

UserWay is an accessibility widget. It is loaded when an account id is set, with USERWAY_ID or here.

"userWay": {
    "id": "<userway-account-id>"
}

Variable	Description	Required	Default Value	Example
id	Account id of the UserWay widget.	No	-	<userway-account-id>

Theme

primaryColor and cssOverride are the installation's defaults, also set by PRIMARY_COLOR and CSS_OVERRIDES. Each organisation can replace them on its Branding page, which also lists the style variables. cssOverride is a JSON object written as a string:

"theme": {
    "primaryColor": "#1e6b52",
    "cssOverride": "{\"--mat-sys-primary\": \"#1e6b52\", \"--link-color\": \"#1F57C3\"}"
}

---

See also

• Backend configuration - The API service
• Keycloak setup - The webapp client and its scopes
• Infrastructure - The .env file of the Docker example
• Branding - The main colour, logo, and style variables of an organisation
• Notification Service - Email notification service
• Annotation Service - Annotation service overview