Configuration

This section describes all the configuration options of Gentics Portal | java.

Configuration file

The portal configuration is loaded from the config/server.yml file, which has to be a valid YAML file.

The default configuration is available at the end of this section.

There are default values for most entries but the following settings must be explicitly set for every project:

Overriding settings

While it is advisable to manage the portal configuration for a project in a version control system, it is often necessary to overwrite some settings for a local development setup, or because of project staging.

Local config file

All settings in config/server.local.yml will override (or extend) the values specified in the main configuration file. Note that list values, are not merged but completely overwritten.

Environment variables

Many settings can be overwritten by setting environment variables. What settings can be specified this way, and the names of the environment variables are listed in this table.

Settings

This section contains all available settings for Gentics Portal | java.

General

In the general section setting the meshProject, portalAPIKey and serverUrl is mandatory, for portal to start.

While configuring the startPage is not mandatory, the portal cannot serve / without the setting (requests for valid paths will be fine).

Variable Type Default value Description

meshProject

String

Mandatory

Name of the Mesh project.

serverUrl

URL

Mandatory

The URL used for link resolving.

autoDeleteUploads

boolean

Whether to automatically delete uploaded files when the request is handled.

breadcrumbsLevel

int

0 (unlimited)

The maximum number of breadcrumb entries displayed (beginning at the end).

cookieHintPage

String

Path to the cookie hint page.

defaultLanguage

String

en

The default language the portal assumes when it cannot infer the desired language from the request.

folderTemplateName

String

null

The name of the folder index template to use when listing contents of folders. If no template is specified, requesting a folder will result in a 404 response.

i18nPath

String

data/i18n

Path to YAML resource bundles

implementationVersion

String

null

The implementation version of the branch to use. When this is null, branches are not restricted by implementation versions.

licenseKey

String

The license key

licenseKeyPath

String

license.key

Path to the license key file

meshSchemaPrefix

String

null

Prefix of schemas in Mesh, if different from the project name. When this is null, the name of the Mesh project is used as the prefix. When using the 'Project per Node' setting in Gentics CMS, make sure that the prefix is different from the projectname.

networkTimeout

int

30

Timeout for network requests (in- and outbound) in seconds

queryPath

String

data/queries

Path to files containing graphql queries.

serverHost

String

0.0.0.0

The host IP address the portal binds to. Note that by default the portal will bind to all interfaces. When a reverse proxy is used, it is advised to only bind to 127.0.0.1.

serverPort

int

3000

The port the portal runs on. If this is different then the port in the serverUrl, a reverse proxy will be needed to resolve links correctly

startPage

String

Path to the start page. A path to any language is enough, language fallback will be done automatically. While not mandatory, the portal cannot serve the path / when this is not set correctly.

templatesPath

String

data/templates

Path to handlebar templates.

uploadDir

String

data/uploads

Path to a custom directories for temporary storing uploaded files.

Authentication

Note that authentication must be explicitly enabled by initializing an implementation of AuthenticationBaseHandler in the projects BootstrapInitializer (see also the authentication documentation).

Variable Type Default value Description

authentication.insecureSsl

boolean

false

Flag to allow insecure SSL connections to the OAuth2 server.

authentication.keycloak

KeycloakOptions

Keycloak specific authentication options

authentication.loginEndpoint

String

/auth/login

Path to the API endpoint that can be called to start login procedure.

authentication.loginRedirect

LoginRedirectOptions

Configuration for redirects after a successful login

authentication.logoutEndpoint

String

/auth/logout

Path to the API endpoint that can be called to start logout procedure.

authentication.logoutRedirect

String

/

Path to which the user will be redirected after logout. The default is to redirect to /

authentication.protectedEndpoints

List<EndpointOptions>

List of endpoints that are protected.

authentication.redirectCookieMaxAge

int

-1 (session cookie)

Maximum age of the authentication redirect cookie in seconds, or -1 for session cookies.

authentication.singleSignOut

SingleSignOutOptions

Single sign out configuration

authentication.useSessionCookies

boolean

false

Ignore the max age from original authentication cookies and create session cookies instead

authentication.useUnauthorizedRedirect

boolean

false

Whether to redirect anonymous requests to protected resources to the 401 error page

Keycloak

Missing settings will be taken from the …​/config/keycloak.json if it is available.

Variable Type Default value Description

authentication.keycloak.clientId

String

Mandatory

The client ID the portal should use

authentication.keycloak.realmUrl

String

Mandatory

The URL to the Keycloak realm this portal uses

authentication.keycloak.callbackPath

String

/auth/callback

The path to the OAuth2 callback endpoint

authentication.keycloak.clientSecret

String

The client secret taken from the configuration of the Keycloak realm

authentication.keycloak.retryPeriodSeconds

int

If set to greater than zero, the Keycloak connection initialization will try to start again, if Keycloak server is unreachable. If zero, the portal is shut down. If less than zero, the old behavior (instant fail) is applied

authentication.keycloak.rpInitiatedLogout

boolean

false

Whether the portal should redirect to Keycloaks "end_session_endpoint" on a logout request

Endpoints

There are no mandatory fields, but endpoint definitions without any permissions, or an invalid path (e.g. an * that is not at the end of the path) will be ignored. See the detailed authentication documentation for examples.

Variable Type Default value Description

authentication.protectedEndpoints.mode

ALL, ANY

ANY

Mode for checking permissions. ALL means that user needs to have all roles, ANY means that user needs to have at least one role.

authentication.protectedEndpoints.path

String

The path to protect. The path may end with an * to also catch paths which start with this value.

authentication.protectedEndpoints.permissions

List<String>

List of required role names.

Single sign out

All single sign out settings have usable default values.

Variable Type Default value Description

authentication.singleSignOut.externalPortals

List<String>

List of all URLs of external portals

authentication.singleSignOut.singleSignOutPath

String

/auth/logoutAll

Endpoint for starting single sign out.

Caching

All caching settings have usable default values.

Variable Type Default value Description

caching.binaryMaxAge

int

86400 seconds (1 day)

The max-age cache-control setting for binaries loaded from Mesh.

caching.customParameters

List<String>

Custom values from the routing context to be added to content cache keys.

caching.diskCacheConfig

String

config/cache.ccf

Path of the JCS configuration file.

caching.diskCacheRegionName

String

content

Name of the disk cache region to be used for the caching handler. The in-memory cache solution will be used when no region name has been specified.

caching.enabled

boolean

true

Enable or disable caching.

caching.expireTime

int

60

The time after which elements in the cache expire when they are not accessed.

caching.maximumSize

int

256

The maximum number of elements stored in a cache.

Compatibility

All compatibility settings are disabled by default.

Variable Type Default value Description

compatibility.mapNodeResponse

boolean

true

Whether the NodeResponse to GraphQL response mapper should be applied for previews.

compatibility.preview

boolean

false

Whether to use preview modes for GCMS versions older than 5.34.x.

Data provider

All data provider options have usable default values.

Variable Type Default value Description

dataProvider.meshData

Map<String, List<String>>

Map of data keys → webroot paths of Mesh content to provide

dataProvider.preventStartupOnError

boolean

false

Flag to prevent startup of the portal in case of errors during loading the configured data.

dataProvider.refreshTime

int

60

Refresh interval in seconds.

dataProvider.retryOnError

boolean

true

Flag to retry loading data in case of errors.

dataProvider.webData

Map<String, WebDataOptions>

Map of data keys → web data to provide

Web data

Variable Type Default value Description

dataProvider.webData.url

String

Mandatory

URL of the web page to load.

dataProvider.webData.format

JSON, RAW

RAW

Format of the loaded web page. RAW means the loaded data is interpreted as text. When the format is JSON, the loaded data will be parsed into a Vert.x JsonObject.

dataProvider.webData.options

Map<String, String>

Options for the post processor.

dataProvider.webData.postProcessor

String

null

Fully qualified class name of an optional post processor implementation, which must implement the interface DataProviderPostProcessor.

Mesh

The apiKey should be configured in a server.local.yml file, to prevent storing the API key in a version control system.

Variable Type Default value Description

mesh.apiKey

String

Mandatory

API key for accessing Mesh as admin user.

mesh.authenticationMode

BOTH, COOKIE, HEADER

Whether to send the API token via authentication header, cookie, or both (default: both)

mesh.cookieForwardWhitelist

Set<String>

Names of cookies which can be forwarded to Mesh by plugin proxy requests (default: forms-data, forms-voted).

mesh.eventbus

EventbusOptions

Eventbus Configuration

mesh.host

String

localhost

Mesh host.

mesh.maxRequests

int

64

Set the maximum number of requests to execute concurrently. Above this requests queue in memory, waiting for the running calls to complete.

mesh.maxRequestsPerHost

int

64

Set the maximum number of requests for each host to execute concurrently. Above this requests queue in memory, waiting for the running calls to complete.

mesh.monitoringPort

int

8081

The port of the monitoring verticle.

mesh.port

int

8080

Mesh port.

mesh.proxyHeaderWhitelist

Set<String>

Accept, Authorization, Content-Encoding, Content-Length, Content-Type, Cookie

Whitelist for HTTP headers which may be forwarded to Mesh plugins. Note that the default values are always allowed and cannot be removed.

mesh.requiredPlugins

List<String>

(none)

List of Mesh plugins which must be present for this portal

mesh.ssl

boolean

false

Mesh SSL flag.

mesh.writeQueueMaxSize

int

8192

Set the maximum number of bytes stored in the write queue when forwarding incoming requests to Mesh using the okHttp Client.

Eventbus

All eventbus settings have usable default values.

Variable Type Default value Description

mesh.eventbus.pingInterval

int

100

Eventbus ping interval in ms.

mesh.eventbus.retryTimeout

int

5000

Eventbus retry timeout in ms.

Monitoring

All monitoring settings have usable default values.

Variable Type Default value Description

monitoring.conservativePortalState

boolean

false

Whether the portal state should change to NETWORK_ERROR as soon as a GraphQL request to Mesh fails with a network error.

monitoring.enabled

boolean

false

Whether the monitoring server should be enabled.

monitoring.host

String

127.0.0.1

The host which is used for the monitoring server.

monitoring.ignoreMeshReady

boolean

true

Whether to ignore the Mesh ready status for the portal ready check.

monitoring.jmxEnabled

boolean

false

Whether JMX should be enabled

monitoring.livePath

String

gpj.live

Path to the file which tracks liveness of the portal

monitoring.liveUpdateInterval

int

10

Set the interval in seconds for updating the modified time of the live file

monitoring.maxTimeouts

int

10

Maximum number of timeouts of the MeshRestClient before conservativePortalState will cause a state change to NETWORK_ERROR.

monitoring.port

int

3001

The port which is used for the monitoring server.

monitoring.startupCheckMode

OFF, ABORT, UNREADY

ABORT

How to handle failing start-up checks.

Navigation

All navigation settings have usable default values.

Redirects

While there are no mandatory redirect settings, it is highly recommended to at least define redirects for the HTTP status codes 404 Not Found and 500 Internal Server Error (and 403 Forbidden if authentication is enabled). Otherwise these errors will just result in an empty response.

Variable Type Default value Description

redirects.custom

CustomRedirectOptions

Optional custom redirects.

redirects.statusPages

Map<String, String>

Map of status pages. Keys are HTTP response status codes, and values are the webroot paths of the error respective pages. Language fallback will be done automatically.

Custom redirects

See the documentation for the custom redirects feature for a detailed description about the source and helperClass settings.

Variable Type Default value Description

redirects.custom.helperClass

String

Mandatory

Fully qualified class name of helper implementation, which must implement RedirectHelper.

redirects.custom.source

String

Mandatory

Source for custom redirects. Use prefix 'dataProvider:' to use data from the data provider.

redirects.custom.helperConfig

Map<String, String>

Configuration options for helper class.

redirects.custom.permanentRedirects

boolean

false

Flag to use "301 Moved Permanently" responses instead of "303 See Other".

redirects.custom.reload

boolean

false

Flag to reload the redirects source for every request.

Security

Variable Type Default value Description

security.additionalResponseHeaders

Map<String, String>

No additional headers

Additional HTTP headers added to each response

security.allowedIps

Set<String>

Empty (no IPs allowed)

Allowed IPs which can access backend API endpoints of the portal

security.apiKey

String

None

The API key required by some backend API endpoints

security.cookieSameSitePolicy

None, Strict, Lax

STRICT

The SameSite policy to use for cookies (NONE, LAX or STRICT)

security.encryptCookies

boolean

false

Whether to encrypt the authentication cookies

security.encryptionMode

DISABLED, PASSWORD_ONLY_KEY, AUTO_GENERATED_KEY

DISABLED

How keys for encryption are generated. DISABLED means no encryption, PASSWORD_ONLY_KEY uses the configured password, AUTO_GENERATED_KEY creates a secret key during portal startup.

security.encryptionPassword

String

(empty)

The password to use for encryption. Only used when encryptionMode is set to PASSWORD_ONLY_KEY.

security.useHostCookiePrefix

boolean

false

Whether secure cookie names will be prefixed with "__Host-"

Static handler

All static handler settings have usable default values.

Variable Type Default value Description

static.caching

boolean

false

Flag to turn on caching of static files.

static.maxAge

long

86400s (one day)

Maximum age in seconds for caching of static files.

static.path

String

data/static

Path to static files.

Vert.x

All Vert.x settings have usable default values.

Variable Type Default value Description

vertx.eventPoolSize

int

Number of CPUs times two

The thread pool size for standard verticles

vertx.workerPoolSize

int

20

The thread pool size for worker verticles

Search

All search handler settings have usable default values.

Variable Type Default value Description

search.enabled

boolean

false

Whether the search handler should be used.

search.endpoint

String

/search

The endpoint for the search handler. Custom searches can be made by appending the custom query name as a path segment.

search.paginationEllipsis

String

…​

The string to use for the ellipsis when there are more pages as can be displayed in the pagination.

search.paginationMaxPages

int

6

The maximum number of links in the pagination.

search.paginationNext

String

>

The string to use for the "next" link in the pagination.

search.paginationPrevious

String

<

The string to use for the "previous" link in the pagination.

search.querySize

int

10

The number of hits returned in a single result page. This must be the same in the configuration of the search plugin, or the results will be undefined.

search.template

String

searchresults

The name of the handlebars template to render results. May contain directory segments, and the .hbs extension is optional.

Environment variables

The following environment variables can be used to override configuration settings.

Variable Field Description

Custom options

There are two possibilities to provide project specific settings for a portal: loading a custom configuration file, or configuring a custom options map in the server.yml.

Custom configuration file

To avoid polluting the server configuration, this is the recommended way to load project specific settings.

  1. Create a custom configuration class which extends com.gentics.mesh.portal.api.Config (assume it is called ProjectConfig)

  2. Create a YAML file corresponding to your ProjectConfig and place it in the config directory of the portal (assume the file is called project.yml)

  3. Load the custom configuration by calling ConfigUtil#loadConfig() which will return an instance of ProjectConfig with the settings from project.yml.

  4. Optionally call loadConfig() again, with a local override file

Example for loading project specific configuration
// Load base configuration.
ProjectConfig config = ConfigUtil.loadConfig("project.yml", null, ProjectConfig.class);

// Load local overrides.
config = ConfigUtil.loadConfig("project.local.yml", config, ProjectConfig.class);

When the project specific configuration is very simple it might also suffice to use ConfigUtil#loadJson(String filename) to load a JSON file into a Vert.x JsonObject.

Custom options map

Note that using a custom options map is not recommended.

The configMap can hold a custom class with the specified values.

Variable Type Default value Description

customConfigMap.configMap

Map<String, Object>

Map of custom configuration options.

The following configuration will result in an entry customConfig of type CustomConfig where the String field setting1 has the value "value1":

customConfigMap:
  configMap:
    key1:  !&lt;com.gentics.mesh.portal.config.CustomConfig&gt;
      setting1: "value1"

Default configuration

This is the complete default configuration.

Using this file as is will not work, because the Mesh and Portal API keys, as well as the Mesh project and the server URL are missing.
Default server.yml
---
portalAPIKey: "64d751ed7fb844c1904169c0405e66b0"
meshProject: "demo"
serverUrl: "https://demo"
serverPort: 3000
serverHost: "0.0.0.0"
templatesPath: "data/templates"
queryPath: "data/queries"
i18nPath: "data/i18n"
breadcrumbsLevel: 0
startPage: ""
cookieHintPage: ""
autoDeleteUploads: false
uploadDir: "data/uploads"
licenseKeyPath: "license.key"
defaultLanguage: "en"
networkTimeout: 30
additionalResponseHeaders: {}
checkedQueries: []
mesh:
  host: "localhost"
  port: 8080
  monitoringPort: 8081
  ssl: false
  apiKey: "3f2e001515f44e96b3a1b9c35e05af73"
  requiredPlugins: []
  networkTimeout: 30
  proxyHeaderWhitelist:
  - "Authorization"
  - "Cookie"
  - "Accept"
  - "Content-Encoding"
  - "Accept-Encoding"
  - "Content-Length"
  - "Content-Type"
  maxRequests: 64
  maxRequestsPerHost: 64
  writeQueueMaxSize: 8192
  cookieForwardWhitelist:
  - "forms-voted"
  - "forms-data"
  authenticationMode: "BOTH"
  webrootFieldAvailable: false
  eventbus:
    pingInterval: 100
    retryTimeout: 5000
vertx:
  workerPoolSize: 20
  eventPoolSize: 64
  developmentMode: false
dataProvider:
  refreshTime: 60
  preventStartupOnError: false
  retryOnError: true
  meshData: {}
  webData: {}
mail:
  hostname: "localhost"
  port: 25
  ssl: false
  trustAll: false
  maxPoolSize: 10
  keepAlive: true
redirects:
  statusPages: {}
security:
  allowedIps: []
  additionalResponseHeaders: {}
  useHostCookiePrefix: false
  encryptCookies: false
  encryptionMode: "DISABLED"
  cookieSameSitePolicy: "STRICT"
authentication:
  loginEndpoint: "/auth/login"
  logoutEndpoint: "/auth/logout"
  insecureSsl: false
  logoutRedirect: "/"
  redirectCookieMaxAge: -1
  useUnauthorizedRedirect: false
  redirectCookieSameSiteStrict: true
  useSessionCookies: false
  maxTemporaryEntries: 0
  protectedEndpoints: []
  keycloak:
    callbackPath: "/auth/callback"
    rpInitiatedLogout: false
    retryPeriodSeconds: 60
  singleSignOut:
    externalPortals: []
    singleSignOutPath: "/auth/logoutAll"
  loginRedirect:
    path: "/auth/loggedin"
    defaultRedirect: "/"
    cmsPage: false
proxy:
  active: false
customConfigMap:
  configMap: {}
static:
  path: "data/static"
  caching: false
  maxAge: 86400
navigation:
  breadcrumbsLevel: 0
  sortOrderField: "navsortorder"
  hiddenField: "navhidden"
  expireTime: 15
caching:
  enabled: true
  maximumSize: 256
  expireTime: 60
  customParameters: []
  diskCacheConfig: "config/cache.ccf"
  diskCacheRegionName: "content"
  binaryMaxAge: 86400
monitoring:
  enabled: false
  ignoreMeshReady: true
  jmxEnabled: false
  port: 3001
  host: "127.0.0.1"
  conservativePortalState: false
  maxTimeouts: 10
  startupCheckMode: "ABORT"
  livePath: "gpj.live"
  liveUpdateInterval: 10
compatibility:
  preview: false
  mapNodeResponse: true
search:
  enabled: false
  template: "searchresults"
  endpoint: "/search"
  querySize: 10
  paginationMaxPages: 6
  paginationPrevious: "<"
  paginationEllipsis: "..."
  paginationNext: ">"

Imprint | Made in Vienna - the most livable city in the world