Administration Guide

Software Stack

Component Type Version

Hibernate

ORM

6.5.x

Elasticsearch

Search Engine

6.1.x

Vert.x

Core Framework

4.5.x

Hazelcast

Cluster management

3.12.x

Dagger 2

Dependency Injection

2.11.x

Run with Docker

Run empty demo container

The mesh image contains an empty Gentics Mesh server without any content. It, however, requires a tuning of a database storage, accessible from the image. In order to simplify things at the jumpstart, we have prepared a set of Docker images containing supported RDBMS drivers, among which is the one perfectly suitable for the demonstration purposes: mesh-sqldb, which contains a self-hosted, in-memory based HSQL database to play around with.

docker run -p 8080:8080 gentics/mesh-hsqldb
or
docker run \
 -v mesh-uploads:/uploads \
 -p 8080:8080 \
 gentics/mesh-hsqldb

Use MariaDB-connected container

Other variant for an easy, yet production ready start is to use mesh-mariadb image, providing along an external instance of MariaDB 10.3+ database as a data storage, and a JDBC driver, which can be downloaded from the official website and attached to the image via (possible read-only) volume. By default, the expected location of both of the JDBC driver and a Mesh database connector is /mesh/database/. Below is how a dedicated docker-compose setup may look like.

First, initialize an empty database in your MariaDB, as well as its user. Example setup:

export MYSQL_DATABASE=mymeshdb
export MYSQL_USER=meshdbuser
export MYSQL_PASSWORD=no_one_can_guess

Install the isolation level for the database on start with the startup parameter.

--transaction-isolation=READ-COMMITTED

Alternatively, this can be done via SQL:

SET GLOBAL TRANSACTION ISOLATION LEVEL READ COMMITTED;

Set the database and access permissions up.

CREATE DATABASE mymeshdb CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
GRANT ALL PRIVILEGES ON mymeshdb.* TO 'meshdbuser'@'%';

Include the following mesh container into your docker-compose.yml:

  mesh:
    image: gentics/mesh-mariadb
    volumes:
      - mesh-uploads:/uploads
      - /whatever/path/you/chose/for/the/mariadb-java-client-3.1.2.jar:/mesh/database/mariadb.jar
    ports:
      - '8080:8080'
    environment:
      MESH_DATABASE_ADDRESS: <host:port of a MariaDB. For instance, if the name of MariaDB container is `mariadb`, the content here will be `mariadb:3306`>
      MESH_JDBC_DATABASE_NAME: mymeshdb
      MESH_JDBC_CONNECTION_USERNAME: "meshdbuser"
      MESH_JDBC_CONNECTION_PASSWORD: "no_one_can_guess"
      MESH_INITIAL_ADMIN_PASSWORD: "admin"
      MESH_INITIAL_ADMIN_PASSWORD_FORCE_RESET: "false"
      MESH_BINARY_DIR: "/uploads"

Alternatively, the database configuration can be provided via mesh.yml config file.

storageOptions:
  retryLimit: 10
  retryDelayMillis: 2000
  databaseAddress: "mariadb:3306"
  databaseName: "mymeshdb"
  databaseConnectorClasspath: <path/to/downloaded/driver/and/connector>
  connectionUsername: "meshdbuser"
  connectionPassword: "no_one_can_guess"
  showSql: false
  formatSql: false
  hikariOptions:
    autocommit: false
    connectionTimeout: 10000
    idleTimeout: 600000
    maxLifetime: 1800000
    minimumIdleConnection: 10
    maxPoolSize: 10
    poolName: "MeshHikariCP"
    registerMBeans: false
    transactionIsolationLevel: null
    leakDetectionThreshold: 0
  synchronizeWrites: false
  synchronizeWritesTimeout: 6000

Please refer to the official MariaDB documentation for the database-specific topics.

Volumes / Locations

Name Description Default Environment Setting

/uploads

Location for fileuploads

MESH_BINARY_DIR=/uploads

/config

Location for configuration files

-

/keystore

Location for the main keystore file which contains the cryptographic keys which are used to sign the JWT.

MESH_AUTH_KEYSTORE_PATH=/keystore/keystore.jks

/plugins

Plugin data and configuration location

MESH_PLUGIN_DIR=/plugins

/mesh/data

Remaining data files (e.g. temp dirs, caches)

-

/mesh/database

Database driver and connector library location (e.g. temp dirs, caches)

MESH_DB_CONNECTOR_CLASSPATH=/mesh/database

Docker Compose

We also provide a ready to go docker-compose example stack for Gentics Mesh:

Single node setup with included Elasticsearch container:

Multi node clustering setup:

Run with JAR File

There is no dedicated installation procedure for Gentics Mesh. However, you will need to download a Gentics Mesh JAR and a database connector JAR file. An example of starting Mesh along with the HSQL in-memory mode database, assuming having both downloaded JARs in the same folder, looks as following:

For Unix/Linux/MacOS

java -cp mesh-database-connector-hsqldb-X.X.X.jar:mesh-server-X.X.X.jar com.gentics.mesh.server.ServerRunner

For Windows

java -cp mesh-database-connector-hsqldb-X.X.X.jar;mesh-server-X.X.X.jar com.gentics.mesh.server.ServerRunner

On first startup, Gentics Mesh will create the data folder and subfolders, set a password for the keystore file and provide the mesh.yml configuration file. See Installation Directory for a detailed discussion on Gentics Mesh files & folders.

Command Line Arguments

Various command line arguments can be used to override or supplement previously configured settings.

usage: mesh.jar
 -clusterName <name>              Override the cluster name. Setting a
                                  cluster name will also enable
                                  clustering.
 -disableElasticsearch            Flag which can be used to disable the
                                  Elasticsearch integration.
 -elasticsearchUrl <url>          Elasticsearch URL to be used.
 -help                            This output
 -httpPort <port>                 Override the configured server HTTP
                                  port.
 -initCluster                     Flag which can be used to initialise the
                                  first instance of a cluster. This is
                                  usually only used for testing or setup
                                  of fresh cluster instances.
 -nodeName <name>                 Override the configured node name.
 -resetAdminPassword <password>   Reset the admin password. It is advised
                                  to change the password once again after
                                  the reset has been performed. The
                                  command will also recreate the admin
                                  user if it can't be found in the system.

Installation Directory

On first startup, Gentics Mesh will create all files and folders.

data
   binaryFiles                # Folder for uploads
   binaryImageCache           # Folder for resized and cached images
   tmp                        # Temporary directory
config
   mesh.yml                   # Main Gentics Mesh configuration
   hazelcast.xml              # Hazelcast cluster configuration
   keystore.jceks             # Gentics Mesh keystore used to generate and validate JWT's
   logback.xml                # Logging configuration file

Gentics Mesh ships with two configuration files:

  1. The main configuration file mesh.yml contains all settings for configuring the Gentics Mesh server. All settings are explained in the Configuration & Settings section.

All data of your Gentics Mesh instance can be found in the respective subfolders of data.

The folder binaryFiles contains all media assets of your projects including images and other files. binaryImageCache keeps resized versions of requested images. tmp is used by Vert.x and other components e.g. for file uploads.

This folder structure is the default. All paths can be configured in the main configuration file mesh.yml.

The keystore file, by default, is named keystore.jceks. On first startup, a password for the keystore file is created randomly and stored in mesh.yml.

The elasticsearch folder contains the included Elasticsearch installation which will be started by default.

System Requirements

Server Requirements

There are no external dependencies besides Java Runtime 11.

Production servers must be run on Linux. Work on Windows is neither guaranteed nor eligible for support. Running Gentics Mesh on Windows is encouraged via Docker Windows.

Cluster Requirements

  • Each Gentics Mesh instance needs at least 1.5 GB heap memory.

  • A shared filesystem needs to be provided for the upload folder. This folder needs to be shared among all cluster instances. Using NFS is a typical choice for these folders.

Client Requirements

The Gentics Mesh user interface has been designed mobile-first and does not impose any specific requirements other than enabled JavaScript. It can be used with any "modern" browser, i.e. IE11+ and latest versions of Chrome, Firefox, and Safari.

Environment Variables

Environment variables will override settings within the mesh.yml.

Variable Description (and its YAML config field, if exists)

MESH_AUTH_ANONYMOUS_ENABLED

Override the configured anonymous enabled flag. (authenticationOptions.enableAnonymousAccess)

MESH_AUTH_JWT_ALGO

Override the configured algorithm which is used to sign the JWT. (authenticationOptions.algorithm)

MESH_AUTH_KEYSTORE_PASS

Override the configured keystore password. (authenticationOptions.keystorePassword)

MESH_AUTH_KEYSTORE_PATH

Override the configured keystore path. (authenticationOptions.keystorePath)

MESH_AUTH_PUBLIC_KEYS_PATH

Override the configured public keys file path. (authenticationOptions.publicKeysPath)

MESH_AUTH_TOKEN_EXP

Override the configured JWT expiration time. (authenticationOptions.tokenExpirationTime)

MESH_BINARY_CHECK_INTERVAL

Override the binary check interval (uploadOptions.checkInterval)

MESH_BINARY_DIR

Override the configured binary data directory. (uploadOptions.directory)

MESH_BINARY_DOCUMENT_PARSER

Override the document parser enabled flag. (uploadOptions.parser)

MESH_BINARY_DOCUMENT_PARSER_LIMIT

Override the configured parser limit. (uploadOptions.parserLimit)

MESH_BINARY_METADATA_WHITELIST

Override the metadata whitelist (uploadOptions.metadataWhitelist)

MESH_BINARY_UPLOAD_LIMIT

Override the configured binary byte upload limit. (uploadOptions.byteLimit)

MESH_BINARY_UPLOAD_TEMP_DIR

Override the configured upload temporary directory. (uploadOptions.tempDirectory)

MESH_CACHE_PATH_SIZE

Override the path cache size. (cacheConfig.pathCacheSize)

MESH_CLUSTERED_HIBERNATE_CACHE_HEAP_FREE

Override the minimum required free heap memory for the eviction policy of the hibernate cache when using clustering. (clusteredHibernateCacheHeapFree)

MESH_CLUSTER_COORDINATOR_REGEX

Override the cluster coordinator regex. (clusterOptions.coordinatorRegex)

MESH_CLUSTER_ENABLED

Override cluster enabled flag. (clusterOptions.enabled)

MESH_CLUSTER_INIT

Enable or disable the initial cluster database setup. This is useful for testing. (isInitCluster)

MESH_CLUSTER_NAME

Override the cluster name. (clusterOptions.clusterName)

MESH_CLUSTER_NETWORK_HOST

Override the cluster network host. (clusterOptions.networkHost)

MESH_CLUSTER_VERTX_PORT

Override the vert.x eventbus server port. (clusterOptions.vertxPort)

MESH_CONTENT_AUTO_PURGE

Override the content versioning flag (contentOptions.autoPurge)

MESH_CONTENT_BATCH_SIZE

Override the batch page size. (contentOptions.batchSize)

MESH_DATABASE_ADDRESS

Override the database address. (storageOptions.databaseAddress)

MESH_DB_CONNECTOR_CLASSPATH

Set the Mesh Database Connector classpath. (storageOptions.databaseConnectorClasspath)

MESH_DB_SQL_PARAMETERS_LIMIT

Limit the number of SQL parameters in selected lookup queries. Can be either `definedByDatabase` or `unlimited` or a custom number (greater than zero). (storageOptions.sqlParametersLimit)

MESH_DB_SYNC_WRITES

Override the database sync writes flag. (storageOptions.synchronizeWrites)

MESH_DB_SYNC_WRITES_TIMEOUT

Override the database sync write timeout. (storageOptions.synchronizeWritesTimeout)

MESH_DEBUGINFO_LOG_ENABLED

Enables the debug info log (debugInfoOptions.logEnabled)

MESH_DEBUGINFO_LOG_FILE_SIZE

Override the log file size (debugInfoOptions.logFileSize)

MESH_DEBUGINFO_LOG_FOLDER

Override the path to the debug info log folder (debugInfoOptions.logFolder)

MESH_DEBUGINFO_LOG_PATTERN

Override the log pattern (debugInfoOptions.logPattern)

MESH_DEFAULT_LANG

Override the configured default language. (defaultLanguage)

MESH_ELASTICSEARCH_BULK_DEBOUNCE_TIME

Override the bulk debounce time. (searchOptions.bulkDebounceTime)

MESH_ELASTICSEARCH_BULK_LENGTH_LIMIT

Override the batch bulk length limit. (searchOptions.bulkLengthLimit)

MESH_ELASTICSEARCH_BULK_LIMIT

Override the batch bulk limit. (searchOptions.bulkLimit)

MESH_ELASTICSEARCH_CA_PATH

Override the configured common authority certificate path. (searchOptions.caPath)

MESH_ELASTICSEARCH_CERT_PATH

Override the configured trusted server certificate. (searchOptions.certPath)

MESH_ELASTICSEARCH_COMPLIANCE_MODE

Override the search compliance mode. (searchOptions.complianceMode)

MESH_ELASTICSEARCH_EVENT_BUFFER_SIZE

Override the configured event buffer size. (searchOptions.eventBufferSize)

MESH_ELASTICSEARCH_HOSTNAME_VERIFICATION

Override the configured hostname verification flag. (searchOptions.hostnameVerification)

MESH_ELASTICSEARCH_IDLE_DEBOUNCE_TIME

Override the idle debounce time. (searchOptions.idleDebounceTime)

MESH_ELASTICSEARCH_INCLUDE_BINARY_FIELDS

Override the search include binary fields flag. (searchOptions.includeBinaryFields)

MESH_ELASTICSEARCH_INDEX_CHECK_INTERVAL

Override the interval for index checks (searchOptions.indexCheckInterval)

MESH_ELASTICSEARCH_INDEX_MAPPING_CACHE_TIMEOUT

Override the timeout for the cache if index mappings (searchOptions.indexMappingCacheTimeout)

MESH_ELASTICSEARCH_MAPPING_MODE

Override the search mapping mode. (searchOptions.mappingMode)

MESH_ELASTICSEARCH_PASSWORD

Override the configured Elasticsearch connection password. (searchOptions.password)

MESH_ELASTICSEARCH_PREFIX

Override the configured elasticsearch prefix. (searchOptions.prefix)

MESH_ELASTICSEARCH_RETRY_INTERVAL

Override the retry interval. (searchOptions.retryInterval)

MESH_ELASTICSEARCH_RETRY_LIMIT

Override the retry limit. (searchOptions.retryLimit)

MESH_ELASTICSEARCH_SYNC_BATCH_SIZE

Override the search sync batch size (searchOptions.syncBatchSize)

MESH_ELASTICSEARCH_SYNC_FETCH_BATCH_SIZE

Override the sync fetch batch size. (searchOptions.syncFetchBatchSize)

MESH_ELASTICSEARCH_TIMEOUT

Override the configured elasticsearch server timeout. (searchOptions.timeout)

MESH_ELASTICSEARCH_URL

Override the configured elasticsearch server url. The value can be set to null in order to disable the Elasticsearch support. (searchOptions.url)

MESH_ELASTICSEARCH_USERNAME

Override the configured Elasticsearch connection username. (searchOptions.username)

MESH_ELASTICSEARCH_WAIT_FOR_IDLE

Override the search idle wait flag. (searchOptions.waitForIdle)

MESH_FIELD_CONTAINER_CACHE_SIZE

Override the field container cache size. (fieldContainerCacheSize)

MESH_GRAPHQL_ASYNC_WAIT_TIMEOUT

Override the configured graphQl async wait timeout. (graphQLOptions.asyncWaitTimeout)

MESH_GRAPHQL_SCHEMA_CACHE_SIZE

Override the configured graphQl schema cache size. (graphQLOptions.schemaCacheSize)

MESH_GRAPHQL_SLOW_THRESHOLD

Override the configured slow graphQl query threshold. (graphQLOptions.slowThreshold)

MESH_HIBERNATE_FORMAT_SQL

Set whether the driver-specific SQL queries should be formatted while logged. (storageOptions.formatSql)

MESH_HIBERNATE_GENERATE_STATISTICS

Set whether hibernate should generate statistics. (storageOptions.generateStatistics)

MESH_HIBERNATE_JDBC_BATCH_SIZE

Set batch size. Recommended values are between 5 and 30 (storageOptions.jdbcBatchSize)

MESH_HIBERNATE_NATIVE_QUERY_FILTERING

Override the configured native query filtering. (storageOptions.nativeQueryFiltering)

MESH_HIBERNATE_QUERY_TIMEOUT

Query timeout for hibernate. (storageOptions.queryTimeout)

MESH_HIBERNATE_SECOND_LEVEL_CACHE_ENABLED

Set whether second-level cache should be enabled. (storageOptions.secondLevelCacheEnabled)

MESH_HIBERNATE_SHOW_SQL

Set whether the driver-specific SQL queries should be logged. (storageOptions.showSql)

MESH_HIBERNATE_SLOW_SQL_THRESHOLD

Slow SQL query threshold in milliseconds. (storageOptions.slowSqlThreshold)

MESH_HTTPS_PORT

Override the configured server https port. (httpServerOptions.sslPort)

MESH_HTTP_CORS_ALLOW_CREDENTIALS

Override the configured CORS allowed credentials flag. (httpServerOptions.corsAllowCredentials)

MESH_HTTP_CORS_ENABLE

Override the configured CORS enable flag. (httpServerOptions.enableCors)

MESH_HTTP_CORS_ORIGIN_PATTERN

Override the configured CORS allowed origin pattern. (httpServerOptions.corsAllowedOriginPattern)

MESH_HTTP_ENABLE

Override the configured http server flag. (httpServerOptions.http)

MESH_HTTP_HOST

Override the configured http server host which is used to bind to. (httpServerOptions.host)

MESH_HTTP_MINIFY_JSON

Override the minify JSON flag. (httpServerOptions.minifyJson)

MESH_HTTP_PORT

Override the configured server http port. (httpServerOptions.port)

MESH_HTTP_SERVER_MAX_FORM_ATTRIBUTE_SIZE

Override the max form attribute size (httpServerOptions.maxFormAttributeSize)

MESH_HTTP_SERVER_TOKENS

Override the http server tokens flag. (httpServerOptions.serverTokens)

MESH_HTTP_SSL_CERT_PATH

Override the configured SSL enable flag. (httpServerOptions.certPath)

MESH_HTTP_SSL_CLIENT_AUTH_MODE

Override the configured client certificate handling mode. (httpServerOptions.clientAuthMode)

MESH_HTTP_SSL_ENABLE

Override the configured https server flag. (httpServerOptions.ssl)

MESH_HTTP_SSL_KEY_PATH

Override the configured SSL enable flag. (httpServerOptions.keyPath)

MESH_HTTP_SSL_TRUSTED_CERTS

Override the configured trusted SSL certificates. (httpServerOptions.trustedCertPaths)

MESH_HTTP_USE_ALPN

Override the configured ALPN usage flag. (httpServerOptions.useAlpn)

MESH_HTTP_VERTICLE_AMOUNT

Override the http verticle amount. (httpServerOptions.verticleAmount)

MESH_IMAGE_CACHE_CLEAN_INTERVAL

Overwrite the image cache max idle time. (imageOptions.imageCacheCleanInterval)

MESH_IMAGE_CACHE_DIRECTORY

Override the path for image cache directory. (imageOptions.imageCacheDirectory)

MESH_IMAGE_CACHE_TOUCH

Overwrite the image cache touch behaviour. (imageOptions.imageCacheTouch)

MESH_IMAGE_JPEG_QUALITY

Override the JPEG quality for image resize operations. (imageOptions.jpegQuality)

MESH_IMAGE_MANIPULATION_MODE

Override the image manipulation mode. (imageOptions.mode)

MESH_IMAGE_MAX_HEIGHT

Override the max height for image resize operations. (imageOptions.maxHeight)

MESH_IMAGE_MAX_WIDTH

Override the max width for image resize operations. (imageOptions.maxWidth)

MESH_IMAGE_RESAMPLE_FILTER

Override the sample filter for image resize operations. (imageOptions.resampleFilter)

MESH_INITIAL_ADMIN_PASSWORD

Password which will be used during initial admin user creation. (initialAdminPassword)

MESH_INITIAL_ADMIN_PASSWORD_FORCE_RESET

Control whether a forced password reset should be triggered when creating the initial admin user. (forceInitialAdminPasswordReset)

MESH_JDBC_CONNECTION_PASSWORD

Set the JDBC connection password. (storageOptions.connectionPassword)

MESH_JDBC_CONNECTION_URL_EXTRA_PARAMS

Add the default JDBC connection URL extra params. (storageOptions.connectionUrlExtraParams)

MESH_JDBC_CONNECTION_USERNAME

Set the JDBC connection username. (storageOptions.connectionUsername)

MESH_JDBC_DATABASE_NAME

Override the default database name. (storageOptions.databaseName)

MESH_JDBC_DIALECT_CLASS

Override the default JDBC dialect class. (storageOptions.dialectClass)

MESH_JDBC_DRIVER_CLASS

Override the default JDBC driver class. (storageOptions.driverClass)

MESH_JDBC_RETRY_LIMIT

Override the default transaction retry count. (storageOptions.retryLimit)

MESH_LANGUAGES_FILE_PATH

Override the path to the optional languages file (languagesFilePath)

MESH_LIST_FIELD_CACHE_SIZE

Override the list field cache size. (listFieldCacheSize)

MESH_LIVE_PATH

Path to the mesh live file. (livePath)

MESH_LOCK_PATH

Path to the mesh lock file. (lockPath)

MESH_MAX_MIGRATION_BATCH_SIZE

Override the maximum migration batch size (migrationMaxBatchSize)

MESH_MAX_PURGE_BATCH_SIZE

Override the maximum purge batch size. (versionPurgeMaxBatchSize)

MESH_MIGRATION_TRIGGER_INTERVAL

Override the migration trigger interval (migrationTriggerInterval)

MESH_MONITORING_ENABLED

Override the configured monitoring enabled flag. (monitoringOptions.enabled)

MESH_MONITORING_GC_LIMIT

Override the garbage collection limit in percent. (monitoringOptions.gcTimeLimit)

MESH_MONITORING_HTTP_HOST

Override the configured monitoring http server host which is used to bind to. (monitoringOptions.host)

MESH_MONITORING_HTTP_PORT

Override the configured monitoring server http port. (monitoringOptions.port)

MESH_MONITORING_JVM_METRICS_ENABLED

Override the configured JVM metrics enabled flag. (monitoringOptions.jvmMetricsEnabled)

MESH_MONITORING_MEMORY_LIMIT

Override the memory limit in percent. (monitoringOptions.memoryLimit)

MESH_NODE_NAME

Override the configured node name. (nodeName)

MESH_NON_CLUSTERED_HIBERNATE_CACHE_SIZE

Override the field container cache size. (nonClusteredHibernateCacheSize)

MESH_PLUGIN_DIR

Override the configured plugin directory. (pluginDirectory)

MESH_PLUGIN_TIMEOUT

Override the configured plugin timeout. (pluginTimeout)

MESH_PLUGIN_USE_HTTP2

Override the HTTP/2 usage flag for plugins. (pluginUseHttp2)

MESH_S3_BINARY_ACCESS_KEY_ID

Override the configured AWS S3 access key id. (s3options.accessKeyId)

MESH_S3_BINARY_BUCKET

Override the configured AWS S3 bucket. (s3options.bucket)

MESH_S3_BINARY_CACHE_BUCKET

Override the configured AWS S3 bucket. (s3cacheOptions.bucket)

MESH_S3_BINARY_CACHE_EXPIRATION_TIME_DOWNLOAD

Override the configured AWS S3 download time. (s3cacheOptions.expirationTimeDownload)

MESH_S3_BINARY_CACHE_REGION

Override the configured AWS S3 region. (s3cacheOptions.region)

MESH_S3_BINARY_ENABLED_KEY

Override cluster enabled flag. (s3options.enabled)

MESH_S3_BINARY_ENDPOINT

Override the configured AWS S3 custom endpoint. (s3options.endpoint)

MESH_S3_BINARY_EXPIRATION_TIME_DOWNLOAD

Override the configured AWS S3 download time. (s3options.expirationTimeDownload)

MESH_S3_BINARY_EXPIRATION_TIME_UPLOAD

Override the configured AWS S3 upload time. (s3options.expirationTimeUpload)

MESH_S3_BINARY_LINK_RESOLVER

Override the configured AWS S3 link resolver. (s3options.linkResolver)

MESH_S3_BINARY_METADATA_WHITELIST

Override the metadata whitelist (s3options.metadataWhitelist)

MESH_S3_BINARY_PARSER_LIMIT

Override the configured parser limit. (s3options.parserLimit)

MESH_S3_BINARY_REGION

Override the configured AWS S3 region. (s3options.region)

MESH_S3_BINARY_SECRET_ACCESS_KEY

Override the configured AWS S3 secret access key. (s3options.secretAccessKey)

MESH_S3_CORS_ALLOWED_HEADERS

Override the configured AWS S3 CORS allowed headers. (s3options.corsAllowedHeaders)

MESH_S3_CORS_ALLOWED_METHODS

Override the configured AWS S3 CORS allowed methods. (s3options.corsAllowedMethods)

MESH_S3_CORS_ALLOWED_ORIGINS

Override the configured AWS S3 CORS allowed origins. (s3options.corsAllowedOrigins)

MESH_STALE_TX_CHECK_INTERVAL

Overwrite the interval (in ms) for periodic check for stale transactions. (storageOptions.staleTxCheckInterval)

MESH_START_IN_READ_ONLY

Override the read only mode flag. (startInReadOnly)

MESH_STORAGE_DISK_QUOTA_CHECK_INTERVAL

Overwrite the disk quota check interval. (checkInterval)

MESH_STORAGE_DISK_QUOTA_READ_ONLY_THRESHOLD

Overwrite the disk quota ready only threshold. (readOnlyThreshold)

MESH_STORAGE_DISK_QUOTA_WARN_THRESHOLD

Overwrite the disk quota warn threshold. (warnThreshold)

MESH_TEMP_DIR

Override the configured temp directory. (tempDirectory)

MESH_TX_RETRY_DELAY_SECONDS

Override the default transaction retry delay interval. (storageOptions.retryDelayMillis)

MESH_UPDATECHECK

Override the configured updatecheck flag. (updateCheck)

MESH_VERTX_EVENT_BUS_CHECK_INTERVAL

Override the Vert.x eventBus check interval in ms. (eventBus.checkInterval)

MESH_VERTX_EVENT_BUS_ERROR_THRESHOLD

Override the Vert.x eventBus error threshold in ms. (eventBus.errorThreshold)

MESH_VERTX_EVENT_BUS_WARN_THRESHOLD

Override the Vert.x eventBus warn threshold in ms. (eventBus.warnThreshold)

MESH_VERTX_EVENT_POOL_SIZE

Override the configured Vert.x event pool size. (vertxOptions.eventPoolSize)

MESH_VERTX_ORDERED_BLOCKING_HANDLERS

Override the configured Vert.x blocking handlers ordering setting. (vertxOptions.orderedBlockingHandlers)

MESH_VERTX_WORKER_POOL_SIZE

Override the configured Vert.x worker pool size. (vertxOptions.workerPoolSize)

HIKARI_CP_AUTOCOMMIT

Override the HikariCP connection auto-commit behavior. (hikariOptions.autocommit)

HIKARI_CP_CONNECTION_TIMEOUT

Override the HikariCP connection timeout. (hikariOptions.connectionTimeout)

HIKARI_CP_IDLE_TIMEOUT

Override the HikariCP idle timeout. (hikariOptions.idleTimeout)

HIKARI_CP_LEAK_DETECTION_THRESHOLD

Override the HikariCP leak detection threshold. (hikariOptions.leakDetectionThreshold)

HIKARI_CP_MAX_LIFETIME

Override the HikariCP max lifetime. (hikariOptions.maxLifetime)

HIKARI_CP_MAX_POOL_SIZE

Override the HikariCP maximum pool size. (hikariOptions.maxPoolSize)

HIKARI_CP_MIN_IDLE_CONNECTION

Override the HikariCP minimum idle connections in the pool. (hikariOptions.minimumIdleConnection)

HIKARI_CP_POOL_NAME

Override the HikariCP name of the connection pool. (hikariOptions.poolName)

HIKARI_CP_REGISTER_MBEANS

Override the HikariCP Register JMX Management Beans. (hikariOptions.registerMBeans)

HIKARI_CP_TRANSACTION_ISOLATION_LEVEL

Override the HikariCP transaction isolation level. (hikariOptions.transactionIsolationLevel)

LICENSEKEY

The license key (licenseKey)

LICENSEKEY_PATH

Override the default licence key file path. (licenseKeyPath)

Configuration & Settings

All settings can be found in the main mesh.yml configuration file, that contains various settings for configuring HTTP & SSL, the database connection and configuration, and file upload.

Both files are located directly in the installation directory.

---
defaultMaxDepth: 10
defaultLanguage: "en"
languagesFilePath: null
updateCheck: true
vertxOptions:
  workerPoolSize: 20
  eventPoolSize: 2
  orderedBlockingHandlers: true
  eventBus:
    checkInterval: 30000
    warnThreshold: 60000
    errorThreshold: 120000
s3options:
  enabled: false
  bucket: null
  expirationTimeUpload: 60000
  expirationTimeDownload: 360000
  linkResolver: null
  metadataWhitelist: null
  parserLimit: 40000
  region: null
  secretAccessKey: null
  accessKeyId: null
  endpoint: null
  s3cacheOptions:
    bucket: null
    expirationTimeDownload: 360000
    expirationTimeUpload: 60000
    region: null
  corsAllowedHeaders:
  - "*"
  corsAllowedOrigins:
  - "*"
  corsAllowedMethods:
  - "GET"
  - "PUT"
  - "POST"
  - "DELETE"
tempDirectory: "/opt/mesh/data/tmp"
pluginDirectory: "plugins"
pluginTimeout: 120
nodeName: null
startInReadOnly: false
versionPurgeMaxBatchSize: 10
migrationMaxBatchSize: 50
migrationTriggerInterval: 60000
pluginUseHttp2: false
storageOptions:
  nativeQueryFiltering: "ON_DEMAND"
  retryLimit: 10
  retryDelayMillis: 2000
  driverClass: null
  dialectClass: null
  databaseAddress: null
  connectionUrlExtraParams: ""
  databaseName: "mesh"
  databaseConnectorClasspath: ""
  connectionUsername: "admin"
  connectionPassword: "admin"
  showSql: false
  formatSql: false
  hikariOptions:
    autocommit: false
    connectionTimeout: 10000
    idleTimeout: 600000
    maxLifetime: 1800000
    minimumIdleConnection: 20
    maxPoolSize: 20
    poolName: "MeshHikariCP"
    registerMBeans: false
    transactionIsolationLevel: null
    leakDetectionThreshold: 0
  synchronizeWrites: false
  synchronizeWritesTimeout: 60000
  secondLevelCacheEnabled: true
  generateStatistics: false
  queryTimeout: 0
  slowSqlThreshold: 60000
  jdbcBatchSize: 5
  sqlParametersLimit: "definedByDatabase"
  staleTxCheckInterval: 10000
licenseKeyPath: "license.key"
licenseKey: null
httpServer:
  port: 8080
  sslPort: 8443
  host: "0.0.0.0"
  corsAllowedOriginPattern: ""
  corsAllowCredentials: false
  useAlpn: false
  enableCors: false
  http: true
  ssl: false
  certPath: "config/cert.pem"
  keyPath: "config/key.pem"
  clientAuthMode: "NONE"
  trustedCertPaths: []
  verticleAmount: 2
  minifyJson: true
  maxFormAttributeSize: -1
  serverTokens: true
monitoring:
  enabled: true
  port: 8081
  host: "127.0.0.1"
  jvmMetricsEnabled: true
  memoryLimit: 95
  gcTimeLimit: 50
cluster:
  networkHost: null
  enabled: false
  clusterName: null
  vertxPort: 4848
  coordinatorRegex: null
search:
  url: "http://localhost:9200"
  username: null
  password: null
  certPath: null
  caPath: null
  hostnameVerification: true
  timeout: 60000
  prefix: "mesh-"
  bulkLimit: 100
  bulkLengthLimit: 5000000
  eventBufferSize: 1000
  bulkDebounceTime: 2000
  idleDebounceTime: 100
  retryInterval: 5000
  retryLimit: 3
  waitForIdle: true
  includeBinaryFields: true
  mappingMode: "DYNAMIC"
  complianceMode: "ES_6"
  syncBatchSize: 50000
  syncFetchBatchSize: 10000
  indexCheckInterval: 60000
  indexMappingCacheTimeout: 3600000
upload:
  byteLimit: 262144000
  directory: "data/binaryFiles"
  tempDirectory: "/opt/mesh/data/tmp/temp-uploads"
  parserLimit: 40000
  parser: true
  metadataWhitelist: null
  checkInterval: 60000
security:
  tokenExpirationTime: 3600
  keystorePassword: "<Your Password>"
  keystorePath: "config/keystore.jceks"
  algorithm: "HS256"
  enableAnonymousAccess: true
  publicKeysPath: "config/public-keys.json"
image:
  mode: "ON_DEMAND"
  imageCacheDirectory: "data/binaryImageCache"
  imageCacheCleanInterval: "PT0S"
  imageCacheMaxIdle: "PT1M"
  imageCacheTouch: false
  maxWidth: 2048
  maxHeight: 2048
  jpegQuality: 0.95
  resampleFilter: "LANCZOS"
content:
  autoPurge: true
  batchSize: 5000
cache:
  pathCacheSize: 20000
  fieldContainerCacheSize: "50_000"
  listFieldCacheSize: "50_000"
  clusteredHibernateCacheHeapFree: "10%"
  nonClusteredHibernateCacheSize: "50_000"
debugInfo:
  logFolder: "debuginfo"
  logFileSize: "5MB"
  logEnabled: true
  logPattern: "%d{HH:mm:ss.SSS} [%meshName] %-5level [%thread] [%file:%line] - %msg%n"
graphQL:
  slowThreshold: 60000
  asyncWaitTimeout: 120000
  schemaCacheSize: 1000

General Settings

Configuration Type Default Description

updateCheck

Flag

true

An update check to the Gentics Mesh update server will be invoked during startup if this flag is set to true.

defaultLanguage

String

en

Default language which serves as a fallback when no language has been specified within a request.

verticles

List

-

List of Vert.x java verticle classes which will be loaded during startup.

tempDirectory

Path

data/tmp

Path to the main temporary filesystem directory.

languagesFilePath

Path

-

Optional path to a JSON file containing additional languages.

startInReadOnly

Flag

false

If true, Gentics Mesh will be started in read only mode.

versionPurgeMaxBatchSize

Number

10

The maximum amount of node versions that are purged before the database transaction is committed.

Custom Language

By default Gentics Mesh already contains all ISO 639-1 (two letter) language codes. By using the languagesFilePath setting it is possible to provide a custom languages file which can include additional language definitions.

{
    "sq-KS": {
        "name": "Albanian (Kosovo)",
        "nativeName": "Shqip (Kosovo)"
    }
}
The mesh-compose project contains a full example configuration which shows how to add a custom language.

HTTPS/SSL

See HTTPs configuration.

Server Options

Property Mandatory Type Description

certPath

no

string

Flag which indicates whether SSL support be enabled. Default: config/cert.pem.

clientAuthMode

no

string

Configure the client certificate handling mode. Options: none, request, required. Default: NONE.

corsAllowCredentials

no

boolean

Flag which indicates whether credentials are allowed to be passed along using CORS requests. Default: false.

corsAllowedOriginPattern

no

string

Configured CORS allowed origin pattern. You can specify a regex to include multiple hosts if you want to do so.

enableCors

no

boolean

Flag which indicates whether CORS handling should be enabled. Default: false.

host

no

string

Configure the Gentics Mesh HTTP server host to bind to. Default: 0.0.0.0.

http

no

boolean

Flag which indicates whether http server should be enabled. Default: true.

keyPath

no

string

Path to the SSL private key. Default: config/key.pem.

maxFormAttributeSize

no

integer

Set the maximum size of a form attribute, set to -1 for unlimited. Default: -1.

minifyJson

no

boolean

Minify JSON responses to save the payload space. Default: true.

port

no

integer

Configure the Gentics Mesh HTTP server port. Default: 8080.

serverTokens

no

boolean

Set the http server tokens flag which controls whether the server should expose version information via headers, REST endpoints and GraphQL. Default: true.

ssl

no

boolean

Flag which indicates whether https server should be enabled. Default: false.

sslPort

no

integer

Configure the Gentics Mesh HTTPS server port. Default: 8443.

trustedCertPaths

no

array

Configure the trusted SSL certificates. Default: [].

useAlpn

no

boolean

Flag which indicates whether application-level protocol negotiation (aka ALPN) should be used. Normally HTTP/2 connections need this. Default: false.

verticleAmount

no

integer

Amount of rest API verticles to be deployed. Default: 2 * CPU Cores.

Cluster Options

Property Mandatory Type Description

clusterName

no

string

Name of the cluster. Only instances with a common cluster name will form a cluster.

coordinatorRegex

no

string

The coordinator regex can be used to control which nodes in the cluster are eligible to be elected in a coordinator master election. When left empty all database master nodes are eligible.

enabled

no

boolean

Flag to enable or disable the cluster mode. Default: false.

networkHost

no

string

IP or host which is used to announce and reach the instance in the cluster. Gentics Mesh will try to determine the IP automatically but you may use this setting to override this automatic IP handling.

vertxPort

no

integer

Port used by Vert.x for the eventbus server. Default: 4848.

Storage Options

By default all specified directories are relative to the installation directory.

Property Mandatory Type Description

connectionPassword

no

string

JDBC connection password. Default: admin.

connectionUrlExtraParams

no

string

JDBC connection URL extra parameters.

connectionUsername

no

string

JDBC connection username. Default: admin.

databaseAddress

no

string

Database address in HOST<:PORT> format.

databaseConnectorClasspath

no

string

Mesh Database Connector classpath. This can be a path to either a connector JAR file, or a folder structure containing all the necessary JARs. Symlinks are supported.

databaseName

no

string

Database name. Default: mesh.

dialectClass

no

string

Optional Hibernate dialect class name. User this to override the default database connector provided dialect class.

driverClass

no

string

Optional JDBC driver class name. Use this to override the default database connector provided driver class.

formatSql

no

boolean

Are actual SQL queries formatted during logging? Default: false.

generateStatistics

no

boolean

Enable generation of hibernate statistics Default: false.

hikariOptions

yes

object

HikariCP (connection pool) options.

hikariOptions.autocommit

no

boolean

This property controls the default auto-commit behavior of connections returned from the pool. It is a boolean value.

hikariOptions.connectionTimeout

no

integer

This property controls the maximum number of milliseconds that a client (that's you) will wait for a connection from the pool. If this time is exceeded without a connection becoming available, a SQLException will be thrown. Lowest acceptable connection timeout is 250 ms.

hikariOptions.idleTimeout

no

integer

This property controls the maximum amount of time that a connection is allowed to sit idle in the pool. This setting only applies when minimumIdle is defined to be less than maximumPoolSize. Idle connections will not be retired once the pool reaches minimumIdle connections. Whether a connection is retired as idle or not is subject to a maximum variation of +30 seconds, and average variation of +15 seconds. A connection will never be retired as idle before this timeout. A value of 0 means that idle connections are never removed from the pool. The minimum allowed value is 10000ms (10 seconds).

hikariOptions.leakDetectionThreshold

no

integer

This property controls the amount of time that a connection can be out of the pool before a message is logged indicating a possible connection leak. A value of 0 means leak detection is disabled. Lowest acceptable value for enabling leak detection is 2000 (2 seconds).

hikariOptions.maxLifetime

no

integer

This property controls the maximum lifetime of a connection in the pool. An in-use connection will never be retired, only when it is closed will it then be removed. On a connection-by-connection basis, minor negative attenuation is applied to avoid mass-extinction in the pool. We strongly recommend setting this value, and it should be several seconds shorter than any database or infrastructure imposed connection time limit. A value of 0 indicates no maximum lifetime (infinite lifetime), subject of course to the idleTimeout setting. The minimum allowed value is 30000ms (30 seconds).

hikariOptions.maxPoolSize

no

integer

This property controls the maximum size that the pool is allowed to reach, including both idle and in-use connections. Basically this value will determine the maximum number of actual connections to the database backend. A reasonable value for this is best determined by your execution environment. When the pool reaches this size, and no idle connections are available, calls to getConnection() will block for up to connectionTimeout milliseconds before timing out.

hikariOptions.minimumIdleConnection

no

integer

This property controls the minimum number of idle connections that HikariCP tries to maintain in the pool. If the idle connections dip below this value and total connections in the pool are less than maximumPoolSize, HikariCP will make a best effort to add additional connections quickly and efficiently. However, for maximum performance and responsiveness to spike demands, we recommend not setting this value and instead allowing HikariCP to act as a fixed size connection pool.

hikariOptions.poolName

no

string

This property represents a user-defined name for the connection pool and appears mainly in logging and JMX management consoles to identify pools and pool configurations.

hikariOptions.registerMBeans

no

boolean

This property controls whether or not JMX Management Beans (&quot;MBeans&quot;) are registered or not.

hikariOptions.transactionIsolationLevel

no

integer

This property controls the default transaction isolation level of connections returned from the pool. If this property is not specified, the default transaction isolation level defined by the JDBC driver is used. Only use this property if you have specific isolation requirements that are common for all queries. The value of this property is the constant name from the Connection class such as TRANSACTION_READ_COMMITTED, TRANSACTION_REPEATABLE_READ. Setting it to null defaults to isolation level defined in the JDBC driver.

jdbcBatchSize

no

integer

Hibernate JDBC Batch Size. Recommended values are between 5 and 30 Default: 5.

nativeQueryFiltering

no

string

Enables the native database level filtering for queries. Default: ON_DEMAND.

queryTimeout

no

integer

Global query timeout limit in milliseconds. A timeout value of zero means there is no query timeout. Default: 0.

retryDelayMillis

no

integer

Transaction wait interval between retries, in milliseconds. Default: 2000.

retryLimit

no

integer

Transaction retry count. Default: 10.

secondLevelCacheEnabled

no

boolean

Enable Hibernate second-level cache Default: true.

showSql

no

boolean

Are actual SQL queries logged? Default: false.

slowSqlThreshold

no

integer

Define a threshold in milliseconds, upon which a SQL query is considered slow and produces a log warning. Default: 60000.

sqlParametersLimit

no

string

SQL parameter number limit. Default: definedByDatabase.

staleTxCheckInterval

no

integer

Interval in ms for periodic check for stale transactions. Defaults to 10000 ms. Default: 10000.

synchronizeWrites

no

boolean

Flag which controls whether writes to the database should be synchronized. Setting this flag improves the stability of massive database updates, by the cost of overall performance. Default: false.

synchronizeWritesTimeout

no

integer

Set the timeout in milliseconds for the sync write lock. Default: 60000.

Disk Quota Check Options

Property Mandatory Type Description

checkInterval

no

integer

Check interval in ms. Setting this to 0 will disable the disk quota check. Default: 10000 ms.

readOnlyThreshold

no

string

Threshold for the disk quota ready only level. This can be set either as percentage (e.g. 10%) or as absolute disk space (e.g. 5G). If less than the defined disk space is available, Mesh will automatically be set to readonly. Default: 1G.

warnThreshold

no

string

Threshold for the disk quota warn level. This can be set either as percentage (e.g. 15%) or as absolute disk space (e.g. 10G). If less than the defined disk space is available, warnings will be logged. Default: 3G.

Search Options

Property Mandatory Type Description

bulkDebounceTime

no

integer

The maximum amount of time in milliseconds between two bulkable requests before they are sent. Default: 2000.

bulkLengthLimit

no

integer

Upper limit for the total encoded string length of the bulk requests. Default: 5000000.

bulkLimit

no

integer

Upper limit for the size of bulk requests. Default: 100.

caPath

no

string

Path to the trusted common authority certificate (PEM format)

certPath

no

string

Path to the trusted server certificate (PEM format). This setting can be used when the Elasticsearch server is using a self-signed certificate which would otherwise not be trusted.

complianceMode

no

string

This setting controls the compliance mode for Elasticsearch. Currently supported modes are ES_6, ES_7 and ES_8. Default: ES_6.

eventBufferSize

no

integer

Upper limit for mesh events that are to be mapped to elastic search requests. Default: 1000.

hostnameVerification

no

boolean

Flag which controls whether hostname verification should be enabled. Default: true.

idleDebounceTime

no

integer

The maximum amount of time in milliseconds between two successful requests before the idle event is emitted. Default: 100.

includeBinaryFields

no

boolean

If true, the content and metadata of binary fields will be included in the search index. Default: true.

indexCheckInterval

no

integer

Set the interval of index checks in ms. Default: 60000.

indexMappingCacheTimeout

no

integer

Set the timeout for the cache of index mappings in ms. Default: 3600000.

mappingMode

no

string

This setting controls the mapping mode of fields for Elasticsearch. When set to STRICT only fields which have a custom mapping will be added to Elasticsearch. Mode DYNAMIC will automatically use the Gentics Mesh default mappings which can be supplemented with custom mappings. Default: DYNAMIC.

password

no

string

Password to be used for Elasticsearch authentication.

prefix

no

string

Search server prefix for this installation. Choosing different prefixes for each Gentics Mesh instance will allow you to use a single Elasticsearch cluster for multiple Gentics Mesh instances. Default: mesh-.

retryInterval

no

integer

The time in milliseconds between retries of elastic search requests in case of a failure. Default: 5000.

retryLimit

no

integer

The amount of retries on a single request before the request is discarded. Default: 3.

syncBatchSize

no

integer

Configure the index sync batch size. Default: 50000.

syncFetchBatchSize

no

integer

Configure the batch size while fetching the index versions. Default: 10000.

timeout

no

integer

Timeout for Elasticsearch operations. Default: 60000.

url

no

string

Elasticsearch connection url to be used. Set this setting to null will disable the Elasticsearch support. Default: http://localhost:9200.

username

no

string

Username to be used for Elasticsearch authentication.

waitForIdle

no

boolean

If true, search endpoints wait for elasticsearch to be idle before sending a response. Default: true.

Upload Options

Property Mandatory Type Description

byteLimit

no

integer

The upload size limit in bytes. Default: 262144000 (250 MB).

checkInterval

no

integer

Interval in milliseconds for performing binary check requests for binary fields where a check service URL is defined. For values less than one the check is disabled. Default: 60000.

directory

no

string

Path binary data storage directory. Fileuploads will be placed here. Default: data/binaryFiles.

metadataWhitelist

no

array

If set, the parser will only extract metadata with the keys specified in the list.

parser

no

boolean

If true, the document parser will process uploads and extract metadata and contents. Default: true.

parserLimit

no

integer

The parser limit for uploaded documents (pdf, doc, docx). Default: 40000.

tempDirectory

no

string

Path to the file upload temporary directory. Inbound file uploads will be placed here before they are processed. Default: data/tmp/file-uploads.

Security Options

Property Mandatory Type Description

algorithm

yes

string

Algorithm which is used to verify and sign JWT. Default: HS256.

enableAnonymousAccess

no

boolean

Flag which indicates whether anonymous access should be enabled. Default: true.

keystorePassword

yes

string

The Java keystore password for the keystore file.

keystorePath

yes

string

Path to the java keystore file which will be used to store cryptographic keys. Default: config/keystore.jceks.

publicKeysPath

no

string

Path to the public keys file which contains a list of additional JWK formatted public keys which will be used to verify JWTs. Default: config/public-keys.json.

tokenExpirationTime

yes

integer

Time in minutes which an issued token stays valid. Default: 3600.

Public Keys

A file with additional public keys can be specified via the publicKeysPath property. The public keys from this file will be used to validate JWT’s which were not issued by Gentics Mesh. This is especially useful when using Gentics Mesh with external OIDC / OAuth2 providers.

The keys have to be specified in the JWK format.

{
    "keys": [
        {
            "kid": "lGX_LDchDZWZoUMcdn3cfTtPTUpp0ZIzHorijXn5igU",
            "kty": "RSA",
            "alg": "RS256",
            "use": "sig",
            "n": "m01o1DS-eTG7r7yZdtpkk_x9isOHfrFsF0KM1-zR0lFAVwb7BSK9fOZonUESZmPKEWZv9AOQgGKY6BAk_VOZqjZVEgpvgRCHpvguSYMF3ow8dyJSk1WMd7qp5Aq9wlc__L8eksNIh8-BxiptpfqVEyYTjsoJ2s87Cg3aVT6rhsU0KtGOE-xg00H4rI_6r_WjBt52Jgnu02P-nNhE8kVLsm1Dk9ZEvBVC55df51mpkAhzLKEOXAKLCXr9JEw73dhaGG6MJ9EGeFE5J4NKtcJlYS15IpEGk2B8A-BlE_Pc7c77R80HfH9EEV_GvLVYq0ZN_ei10uXkOj6ChA8JvSbkUQ",
            "e": "AQAB",
            "x5c": [
                "MIICmzCCAYMCBgFwH+cutjANBgkqhkiG9w0BAQsFADARMQ8wDQYDVQQDDAZtYXN0ZXIwHhcNMjAwMjA3MTM0NTA5WhcNMzAwMjA3MTM0NjQ5WjARMQ8wDQYDVQQDDAZtYXN0ZXIwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCbTWjUNL55MbuvvJl22mST/H2Kw4d+sWwXQozX7NHSUUBXBvsFIr185midQRJmY8oRZm/0A5CAYpjoECT9U5mqNlUSCm+BEIem+C5JgwXejDx3IlKTVYx3uqnkCr3CVz/8vx6Sw0iHz4HGKm2l+pUTJhOOygnazzsKDdpVPquGxTQq0Y4T7GDTQfisj/qv9aMG3nYmCe7TY/6c2ETyRUuybUOT1kS8FULnl1/nWamQCHMsoQ5cAosJev0kTDvd2FoYbown0QZ4UTkng0q1wmVhLXkikQaTYHwD4GUT89ztzvtHzQd8f0QRX8a8tVirRk396LXS5eQ6PoKEDwm9JuRRAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAG5FUbZ+O/D68KdDJEP3ozl1DaiB8d2ESdfY+VkUAbZQ8OCw2uIc1boWGMc1cgVEC0I3UgNf0yOWYb8B4TlkkSfKojgKzanJN+lZPD6kdxgSx97NnuasKQiSCSyxGX9Ho5HoiHPlcMCl8f0R2ODPQJfPPIqh6+2wxJLCPkkqNO3Nvp98IS/EV6L4VNtecZvS09BeUc4LxFKqlnAZwQ5E7oCUXDmDKWlpdIei0XErhEasvbOYfVdcZhgty0xLrn9wCG+0HAt1uxf8y00Sl80f5dcIoPKgyOHtTYQV3U22ZgATt2CJmHUJjku6ALjAPkMgIgnzWTZZV186T+I7aiYtBes="
            ],
            "x5t": "PxgAp5rbw5v52HdIC6jDlQxh37M",
            "x5t#S256": "AMquThnlmJHomcZV1zl89FMHyEl4QJHsqNf1QU8xK8M"
        }
    ]
}

Monitoring Options

Property Mandatory Type Description

enabled

no

boolean

Enable or disable the monitoring system. Default: true.

gcTimeLimit

no

integer

Limit time used for garbage collections percent, which will cause Mesh to become unhealthy. Default: 50.

host

no

string

Configure the Gentics Mesh monitoring HTTP server host to bind to. Default: 127.0.0.1.

jvmMetricsEnabled

no

boolean

Enable or disable the measuring of JVM metrics. Default: true.

memoryLimit

no

integer

Limit of used memory in percent, which will cause Mesh to become unhealthy. Default: 95.

port

no

integer

Configure the Gentics Mesh monitoring HTTP server port. Default: 8081.

Image Options

Property Mandatory Type Description

imageCacheCleanInterval

no

string

Image cache clean interval in ISO 8601 duration format. Setting this to PT0S will disable the image cache cleanup. Default: PT0S.

imageCacheDirectory

no

string

Configure the path for image cache directory. Default: data/binaryImageCache.

imageCacheMaxIdle

no

string

Image cache maximum idle time in ISO 8601 duration format. Default: PT1M.

imageCacheTouch

no

boolean

Whether the Image cache files should be touched when accessed. Default: false.

jpegQuality

no

number

Configure the quality of the output of JPEG images. Must be a value between inclusive 0 and inclusive 1. Default: 0.95.

maxHeight

no

integer

Configure the maximum allowed image resize height. Resizing is a memory intensive operation and thus this limit can help avoid memory issues. Default: 2048.

maxWidth

no

integer

Configure the maximum allowed image resize width. Resizing is a memory intensive operation and thus this limit can help avoid memory issues. Default: 2048.

mode

no

string

Configure the image manipulation mode. Default: ON_DEMAND.

resampleFilter

no

string

Configure the filter that is used when resizing images. Default: LANCZOS.

Cache Options

Property Mandatory Type Description

pathCacheSize

no

integer

Set the maximum size of the path cache. A value of 0 will disable the cache. Default: 20000.

Debug Information Options

Property Mandatory Type Description

logEnabled

no

boolean

Enables the debug info log. Default: true.

logFileSize

no

string

The maximum file size of a single log file. Default: 5MB.

logFolder

no

string

The path of the folder where the debug info log is stored. Default: debuginfo.

logPattern

no

string

The pattern used for each log line. For the detailed pattern format description please refer to the Logback documentation. Default: %d{HH:mm:ss.SSS} [%meshName] %-5level [%thread] [%file:%line] - %msg%n.

GraphQL Options

Property Mandatory Type Description

asyncWaitTimeout

no

integer

Threshold for waiting for asynchronous graphql queries, in milliseconds. Default: 120000.

schemaCacheSize

no

integer

Cache size for graphQl Schema instances. Setting this to 0 will disable the cache. Default: 1000.

slowThreshold

no

integer

Threshold for logging slow graphql queries, in milliseconds. Default: 60000.

S3 Storage Options

Property Mandatory Type Description

accessKeyId

no

string

AWS S3 access key id

bucket

no

string

AWS S3 bucket where binaries will be uploaded to and downloaded from

corsAllowedHeaders

no

array

AWS S3 setting for allowed headers for Cross-Origin Resource Sharing. Setting this to null will force default server values. Default: []*.

corsAllowedMethods

no

array

AWS S3 setting for allowed methods for Cross-Origin Resource Sharing. Setting this to null will force default server values. Default: [GET, PUT, POST, DELETE].

corsAllowedOrigins

no

array

AWS S3 setting for allowed origins for Cross-Origin Resource Sharing. Setting this to null will force default server values. Default: []*.

enabled

no

boolean

Flag to enable or disable the S3 engine. Default: false.

endpoint

no

string

AWS S3 custom endpoint

expirationTimeDownload

no

integer

After this time in milliseconds the AWS S3 URL used for download will expire. Default: 360000.

expirationTimeUpload

no

integer

After this time in milliseconds the AWS S3 URL used for upload will expire. Default: 60000.

linkResolver

no

string

Style of linkResolving:'s3' (default) resolved Links will render a pre-signed URL directly to S3 OR 'mesh' resolved Links will render a mesh-url

metadataWhitelist

no

array

If set, the parser will only extract metadata with the keys specified in the list.

parserLimit

no

integer

The parser limit for uploaded documents (pdf, doc, docx). Default: 40000.

region

no

string

AWS S3 region

s3cacheOptions

yes

object

S3 Cache Bucket Options.

s3cacheOptions.bucket

no

string

AWS S3 bucket where transformed/resized images will be uploaded to and downloaded from.

s3cacheOptions.expirationTimeDownload

no

integer

After this time in milliseconds the AWS S3 URL used for download of a transformed image will expire.

s3cacheOptions.region

no

string

AWS S3 region for transformed / resized images

secretAccessKey

no

string

AWS S3 secret access key
Property Mandatory Type Description

bucket

no

string

AWS S3 bucket where transformed/resized images will be uploaded to and downloaded from.

expirationTimeDownload

no

integer

After this time in milliseconds the AWS S3 URL used for download of a transformed image will expire. Default: 360000.

region

no

string

AWS S3 region for transformed / resized images

Memory Settings

Memory settings can be defined using the JAVA_TOOL_OPTIONS environment variable.

Setting Description

-Xmx

Maximum heap size of the Gentics Mesh Java process

-Xms

Initial heap size of the Gentics Mesh Java process

-Xss

Stack size. A larger stack size may be required when deleting deep datasets. The default value is 1MB.

-XX:MaxDirectMemorySize

Maximum direct memory limit. Direct memory is mostly used for IO buffers.

The total amount of required memory is the roughly sum of heap memory + direct memory + disk cache + (stack size * thread count) + 256 MB (JVM base memory).

Recommendations (Single Node)

The following numbers serve the purpose to roughly estimate the memory requirements for different sized projects in a non-clustered setup.

Node Count Memory Setting

0 to 100

-Xms128m -Xmx128m -XX:MaxDirectMemorySize=128m -Dstorage.diskCache.bufferSize=128

100 to 1_000

-Xms512m -Xmx512m -XX:MaxDirectMemorySize=128m -Dstorage.diskCache.bufferSize=256

1_000 to 10_000

-Xms786m -Xmx786m -XX:MaxDirectMemorySize=128m -Dstorage.diskCache.bufferSize=384

10_000 to 100_000

-Xms1250m -Xmx1250m -XX:MaxDirectMemorySize=128m -Dstorage.diskCache.bufferSize=512

100_000 to 1_000_000

-Xms2500m -Xmx2500m -XX:MaxDirectMemorySize=128m -Dstorage.diskCache.bufferSize=1024

Recommendations (Clustered Node)

The following numbers serve the purpose to roughly estimate the memory requirements for different sized projects in a clustered setup.

Node Count Memory Setting

0 to 100

-Xms1124m -Xmx1124m -Xss1m -XX:MaxDirectMemorySize=628m -Dstorage.diskCache.bufferSize=628

100 to 1_000

-Xms1512m -Xmx1512m -Xss2m -XX:MaxDirectMemorySize=856m -Dstorage.diskCache.bufferSize=856

1_000 to 10_000

-Xms1786m -Xmx1786m -Xss2m -XX:MaxDirectMemorySize=984m -Dstorage.diskCache.bufferSize=984

10_000 to 100_000

-Xms2250m -Xmx2250m -Xss2m -XX:MaxDirectMemorySize=1024m -Dstorage.diskCache.bufferSize=1024

100_000 to 1_000_000

-Xms3500m -Xmx3500m -Xss4m -XX:MaxDirectMemorySize=2048m -Dstorage.diskCache.bufferSize=2048

Admin Access

By default an admin user will be created during initial startup. The password of this user will be printed in the log. It is mandatory to update the admin password during the first login.

For demo installations the password is admin.

Additional admin users can be created by setting the admin flag the users.

The admin access can be restored via the use of the resetAdminPassword mesh server argument.

Backup & Recovery

There are currently fours components which can be included in a backup:

  • Database - The database contains the main content of Gentics Mesh. The backup process of a database depends on an actual RDBMS (MariaDB, HSQLDB etc…​) used, and is not a part of Gentics Mesh. In the case of MariaDB, please refer to the official backup/restore documentation. For all the other cases, a premium DB documentation is a good place to start looking.

  • Binary files - Binaries are currently stored in the filesystem and need to be backed up separately data/binaryFiles)

  • Elasticsearch Index - Optionally you can also backup the Elasticsearch index. The index can also be re-created anytime using the POST /api/v2/search/sync endpoint.

  • Configuration - The Gentics Mesh configuration files should be part of a backup. Especially the keystore.jks file is important since it contains the cryptographic keys which are needed to authenticate issued tokens which includes also the API key. The mesh.yaml file contains the autogenerated password for the keystore file. The keystore file and the password to open it are required by Gentics Mesh to authenticate tokens.

Debug Information

The debug info endpoint GET /api/v2/admin/debuginfo starts a zip download containing various useful data about the system.

The documentation below lists all files that are included in the zip.

Per default everything except the consistency check is included in the zip. You can use the ?include query parameter to include or exclude specific parts. For example /api/v2/admin/debuginfo?include=-log,consistencyCheck will exclude application logs and include the consistency checks.

Active Config

Query name: activeConfig

The effective configuration that is currently used in the system. This includes overrides by command line argument and environment variables.

Binary Disk Usage

Query name: binaryDiskUsage

The total file size of all stored binaries and cached images.

Configurations

Query name: config

The following files from the config folder:

  • mesh.yml

  • hazelcast.xml

  • logback.xml

Consistency Check

Query name: consistencyCheck

Performs a consistency check and includes the result.

Entities

Query name: entities

Includes the following entities as json:

  • All jobs

  • All Schemas

  • All Microschemas

  • All Projects

  • All Branches

Log

Query name: log

Includes the latest debug log output of Gentics Mesh. Check the debug info options for more options.

Migration Status

Query name: migrationStatus

Includes the schema migration status and mircoschema migration status for every branch of every project.

Plugins

Query name: plugins

Includes the currently deployed plugins.

Status

Query name: status

Includes the version, cluster status and elastic search status.

System Information

Query name: systemInfo

Contains the following informations about the system:

  • System load average

  • JVM memory usage

  • JVM arguments

  • Disk space usage (of the file system where Gentics Mesh is running)

Thread Dump

Query name: threadDump

A dump of all threads including all stack traces.

Read Only Mode

Gentics Mesh can be put into read only mode. In this mode, all requests that would change data (create, update, delete) are not allowed and return a `405ยด status code instead.

This is useful in cluster situations when having instances as replicas or when performing rolling updates.

Activating Read Only Mode

Read only mode can be activated in one of the following ways:

  • Setting the entry startInReadOnly to true in the configuration file before starting will start Gentics Mesh in read only mode.

  • Setting the environment variable MESH_START_IN_READ_ONLY to true before starting will start Gentics Mesh in read only mode.

  • Using the REST API. Changing read only mode in this way will take immediate effect.

Changelog

Update handling

Updating Gentics Mesh is very simple. You stop the current instance and start it again using the new version. A process is invoked which will check whether any automatic changes need to be applied.

Downgrading

Downgrading is possible but not recommended. You can however downgrade your Gentics Mesh instance if the database revision hash of the current database matches up with the revision which is required by the version which is being started. You can check your current database revision via the /api/v2 endpoint.

Database Revisions

The database revisions are automatically controlled by Liquibase. No user managed functionality is available.

Database Consistency

It is possible to verify the database integrity via the GET /api/v2/admin/consistency/check endpoint.

The response contains information about the found inconsistencies and whether they have a repair action.

{
  "outputTruncated" : false,
  "result" : "INCONSISTENT",
  "repairCount" : { },
  "inconsistencies" : [ {
    "description" : "A dangling field container has been found.",
    "severity" : "LOW",
    "elementUuid" : "c5ac82fa1a9c43b6ac82fa1a9ca3b61c",
    "repaired" : false,
    "repairAction" : "DELETE"
  } ]
}

The POST /api/v2/admin/consistency/repair endpoint can be used to invoke a check and repair of repairable inconsistencies.

The repaired property will be set to true if the inconsistency could be fixed.

{
  "outputTruncated" : false,
  "result" : "INCONSISTENT",
  "repairCount" : { },
  "inconsistencies" : [ {
    "description" : "A dangling field container has been found.",
    "severity" : "LOW",
    "elementUuid" : "c5ac82fa1a9c43b6ac82fa1a9ca3b61c",
    "repaired" : true,
    "repairAction" : "DELETE"
  } ]
}

License

Gentics Software GmbH & Gentics Software AG - www.gentics.com - Wien & Bern