Administration Guide

Software Stack

Component Type Version

OrientDB

Graph Database

3.0.x

Ferma

OGM

2.4.x

Elasticsearch

Search Engine

6.1.x

Vert.x

Core Framework

3.7.x

Hazelcast

In-Memory Data Grid

3.10.x

Dagger 2

Dependency Injection

2.11.x

You can find the components' current version numbers by querying the Gentics Mesh demo instance https://demo.getmesh.io/api/v2/ or your local instance http://localhost:8080/api/v2/.

Run with Docker

Alternatively you can start Gentics Mesh using Docker via:

The mesh-demo image contains Gentics Mesh together with demo content and our demo application.

docker run -p 8080:8080 gentics/mesh-demo

The mesh image contains an empty Gentics Mesh server without any demo content.

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

Volumes / Locations

Name Description Default Environment Setting

/uploads

Location for fileuploads

MESH_BINARY_DIR=/uploads

/graphdb

Location for the graph database data

MESH_GRAPH_DB_DIRECTORY=/graphdb

/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

/backups

Backup data location

MESH_GRAPH_BACKUP_DIRECTORY=/backups

/plugins

Plugin data and configuration location

MESH_PLUGIN_DIR=/plugins

/mesh/data

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

-

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

Good news: there is no dedicated installation procedure for Gentics Mesh!

All you need is to download the Gentics Mesh JAR file and start by executing

java -jar mesh-demo-X.X.X.jar

Gentics Mesh comes with OrientDB, an embedded graph database, and Elasticsearch. There are no external dependencies besides Java Runtime 11. On first startup, Gentics Mesh will create the data folder and subfolders, set a password for the keystore file and provide the configuration files mesh.yml and mesh-ui-config.js. 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.
 -embeddedElasticsearch <flag>    Flag which can be used to disable the
                                  embedded Elasticsearch server.
 -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
   graphdb                    # Main Graph Database storage which contains all contents
   tmp                        # Temporary directory
config
   mesh.yml                   # Main Gentics Mesh configuration
   automatic-backup.json      # OrientDB Automatic Backup configuration
   default-distributed-db-config.json # Default configuration for new Cluster Nodes
   hazelcast.xml              # Hazelcast cluster configuration
   keystore.jceks             # Gentics Mesh keystore used to generate and validate JWT's
   logback.xml                # Logging configuration file
   orientdb-server-config.xml # OrientDB Cluster Server configuration
   security.json              # OrientDB security configuration
   mesh-ui-config.js          # Configuration of the Mesh UI

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.

  2. User interface related settings can be changed in mesh-ui-config.js.

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. The OrientDB graph data is stored within the graphdb folder. 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

Gentics Mesh comes with OrientDB, an embedded graph database. There are no external dependencies besides Java Runtime 11.

Production servers must be run on Linux. Windows is not supported. You can however run Gentics Mesh on Windows via Docker Windows.

GraphDB Storage Requirements

The underlying storage filesystem for the Graph Database must support DirectIO.

Filesystem Supported

Ext4

Yes

XFS

Yes

NFS

No

GlusterFS

No

Ceph

No

ZFS

No

Amazon EFS

No

Amazon EBS

Yes

Storage solutions which provide one of the supported filesystems by the means of iSCSI or Fiberchannel are supported.

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.

System Configuration

The maximum open file limit on Linux has to be raised on most Linux systems since the embedded graph database and Elasticsearch server often exceed the amount of concurrent open files.

The limits need to be configured specific to your execution environment.

  • Docker: Limits can be specified during startup or inside the docker-compose.yaml.

  • Systemd: Limits can be specified within the startup service file.

  • K8S/Openshift: Limits need to be configured in the deployments. The commercial helm chart already includes these.

  • sysvinit: The limits can be configured in the /etc/security/limits.conf

Edit /etc/security/limits.conf and add these two lines:

mesh   soft    nofile  60000
mesh   hard    nofile  60000

Edit /etc/pam.d/su and uncomment or add the following line:

session    required   pam_limits.so
This change may require a logout and login.

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

MESH_CLUSTER_COORDINATOR_MODE

Override the cluster coordinator mode.

MESH_HTTP_CORS_ENABLE

Override the configured CORS enable flag.

MESH_GRAPH_STARTSERVER

Override the graph database server flag.

MESH_HTTP_SSL_ENABLE

Override the configured https server flag.

MESH_GRAPH_TX_RETRY_LIMIT

Override the transaction retry limit. Default: 10

MESH_HTTP_VERTICLE_AMOUNT

Override the http verticle amount.

MESH_CLUSTER_NETWORK_HOST

Override the cluster network host.

MESH_PLUGIN_TIMEOUT

Override the configured plugin timeout.

MESH_LOCK_PATH

Path to the mesh lock file.

MESH_PLUGIN_DIR

Override the configured plugin directory.

MESH_MONITORING_HTTP_HOST

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

MESH_VERTX_WORKER_POOL_SIZE

Override the configured Vert.x worker pool size.

MESH_CLUSTER_COORDINATOR_REGEX

Override the cluster coordinator regex.

MESH_HTTP_SSL_CERT_PATH

Override the configured SSL enable flag.

MESH_CONTENT_AUTO_PURGE

Override the content versioning flag

MESH_BINARY_DOCUMENT_PARSER_LIMIT

Override the configured parser limit.

MESH_HTTP_HOST

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

MESH_AUTH_TOKEN_EXP

Override the configured JWT expiration time.

MESH_IMAGE_MAX_HEIGHT

Override the max height for image resize operations.

MESH_ELASTICSEARCH_MAPPING_MODE

Override the search mapping mode.

MESH_DEBUGINFO_LOG_FOLDER

Override the path to the debug info log folder

MESH_ELASTICSEARCH_HOSTNAME_VERIFICATION

Override the configured hostname verification flag.

MESH_ELASTICSEARCH_WAIT_FOR_IDLE

Override the search idle wait flag.

MESH_CLUSTER_VERTX_PORT

Override the vert.x eventbus server port.

MESH_GRAPH_SYNC_WRITES

Override the graph database sync writes flag.

MESH_HTTP_CORS_ALLOW_CREDENTIALS

Override the configured CORS allowed credentials flag.

MESH_CLUSTER_COORDINATOR_TOPOLOGY

Override the cluster coordinator topology management mode.

MESH_INITIAL_ADMIN_PASSWORD_FORCE_RESET

Control whether a forced password reset should be triggered when creating the initial admin user. Default: true

MESH_GRAPH_SYNC_WRITES_TIMEOUT

Override the graph database sync write timeout.

MESH_ELASTICSEARCH_STARTUP_TIMEOUT

Override the configured elasticsearch server timeout.

MESH_AUTH_PUBLIC_KEYS_PATH

Override the configured public keys file path.

MESH_LANGUAGES_FILE_PATH

Override the path to the optional languages file

MESH_ELASTICSEARCH_PREFIX

Override the configured elasticsearch prefix.

MESH_HTTP_PORT

Override the configured server http port.

MESH_ELASTICSEARCH_SYNC_BATCH_SIZE

Override the search sync batch size

MESH_MONITORING_JVM_METRICS_ENABLED

Override the configured JVM metrics enabled flag.

MESH_CLUSTER_TOPOLOGY_LOCK_DELAY

Override the cluster topology lock delay in ms.

MESH_BINARY_DOCUMENT_PARSER

Override the document parser enabled flag.

MESH_AUTH_KEYSTORE_PASS

Override the configured keystore password.

MESH_CACHE_PATH_SIZE

Override the path cache size.

MESH_GRAPH_EXPORT_DIRECTORY

Override the graph database export directory.

MESH_HTTP_SSL_CLIENT_AUTH_MODE

Override the configured client certificate handling mode.

MESH_ELASTICSEARCH_CERT_PATH

Override the configured trusted server certificate.

MESH_ELASTICSEARCH_PASSWORD

Override the configured Elasticsearch connection password.

MESH_HTTP_ENABLE

Override the configured http server flag.

MESH_BINARY_UPLOAD_LIMIT

Override the configured binary byte upload limit.

MESH_MONITORING_HTTP_PORT

Override the configured monitoring server http port.

MESH_ELASTICSEARCH_COMPLIANCE_MODE

Override the search compliance mode.

MESH_HTTP_SSL_KEY_PATH

Override the configured SSL enable flag.

MESH_TEMP_DIR

Override the configured temp directory.

MESH_MONITORING_ENABLED

Override the configured monitoring enabled flag.

MESH_DEBUGINFO_LOG_ENABLED

Enables the debug info log

MESH_IMAGE_CACHE_DIRECTORY

Override the path for image cache directory.

MESH_ELASTICSEARCH_URL

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

MESH_ELASTICSEARCH_BULK_LENGTH_LIMIT

Override the batch bulk length limit. Default: 5000000

MESH_ELASTICSEARCH_RETRY_LIMIT

Override the retry limit.

MESH_HTTP_SSL_TRUSTED_CERTS

Override the configured trusted SSL certificates.

MESH_ELASTICSEARCH_INCLUDE_BINARY_FIELDS

Override the search include binary fields flag.

MESH_GRAPH_TX_RETRY_DELAY

Override the transaction retry delay. Default: 10

MESH_BINARY_DIR

Override the configured binary data directory.

MESH_DEBUGINFO_LOG_FILE_SIZE

Override the log file size

MESH_UPDATECHECK

Override the configured updatecheck flag.

MESH_AUTH_JWT_ALGO

Override the configured algorithm which is used to sign the JWT.

MESH_ELASTICSEARCH_START_EMBEDDED

Override the start embedded elasticsearch server flag.

MESH_ELASTICSEARCH_BULK_LIMIT

Override the batch bulk limit. Default: 100

MESH_ELASTICSEARCH_RETRY_INTERVAL

Override the retry interval.

MESH_ELASTICSEARCH_USERNAME

Override the configured Elasticsearch connection username.

MESH_ELASTICSEARCH_EVENT_BUFFER_SIZE

Override the configured event buffer size.

MESH_CLUSTER_TOPOLOGY_LOCK_TIMEOUT

Override the cluster topology lock timeout in ms.

MESH_GRAPH_BACKUP_DIRECTORY

Override the graph database backup directory.

MESH_HTTP_CORS_ORIGIN_PATTERN

Override the configured CORS allowed origin pattern.

MESH_DEFAULT_LANG

Override the configured default language.

MESH_GRAPH_TX_COMMIT_TIMEOUT

Override the transaction commit timeout. Default: 0

MESH_IMAGE_RESAMPLE_FILTER

Override the sample filter for image resize operations.

MESH_CLUSTER_NAME

Override the cluster name.

MESH_MAX_PURGE_BATCH_SIZE

Override the maximum purge batch size.

MESH_ELASTICSEARCH_BULK_DEBOUNCE_TIME

Override the bulk debounce time.

MESH_ELASTICSEARCH_CA_PATH

Override the configured common authority certificate path.

MESH_ELASTICSEARCH_TIMEOUT

Override the configured elasticsearch server timeout.

MESH_VERTX_EVENT_POOL_SIZE

Override the configured Vert.x event pool size.

MESH_IMAGE_MAX_WIDTH

Override the max width for image resize operations.

MESH_HTTPS_PORT

Override the configured server https port.

MESH_AUTH_ANONYMOUS_ENABLED

Override the configured anonymous enabled flag.

MESH_DEBUGINFO_LOG_PATTERN

Override the log pattern

MESH_CLUSTER_INIT

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

MESH_BINARY_UPLOAD_TEMP_DIR

Override the configured upload temporary directory.

MESH_GRAPH_DB_DIRECTORY

Override the graph database storage directory.

MESH_HTTP_SERVER_TOKENS

Override the http server tokens flag.

MESH_NODE_NAME

Override the configured node name.

MESH_IMAGE_JPEG_QUALITY

Override the JPEG quality for image resize operations.

MESH_START_IN_READ_ONLY

Override the read only mode flag.

MESH_INITIAL_ADMIN_PASSWORD

Password which will be used during initial admin user creation.

MESH_CLUSTER_ENABLED

Override cluster enabled flag.

MESH_ELASTICSEARCH_IDLE_DEBOUNCE_TIME

Override the idle debounce time.

MESH_BINARY_METADATA_WHITELIST

Override the metadata whitelist

MESH_AUTH_KEYSTORE_PATH

Override the configured keystore path.

Configuration & Settings

All settings can be found in the main mesh.yml configuration file, that contains various settings for configuring HTTP & SSL, the graph database, and file upload. The settings for the Gentics Mesh user interface can be found in mesh-ui-config.js.

Both files are located directly in the installation directory.

---
defaultMaxDepth: 10
defaultLanguage: "en"
languagesFilePath: null
updateCheck: true
vertxOptions:
  workerPoolSize: 20
  eventPoolSize: 16
tempDirectory: "/opt/mesh/data/tmp"
pluginDirectory: "plugins"
pluginTimeout: 120
nodeName: null
startInReadOnly: false
versionPurgeMaxBatchSize: 10
httpServer:
  port: 8080
  sslPort: 8443
  host: "0.0.0.0"
  corsAllowedOriginPattern: ""
  corsAllowCredentials: false
  enableCors: false
  http: true
  ssl: false
  certPath: "config/cert.pem"
  keyPath: "config/key.pem"
  clientAuthMode: "NONE"
  trustedCertPaths: []
  verticleAmount: 16
  serverTokens: true
monitoring:
  enabled: true
  port: 8081
  host: "127.0.0.1"
  jvmMetricsEnabled: true
cluster:
  networkHost: null
  enabled: false
  clusterName: null
  vertxPort: 4848
  coordinatorMode: "DISABLED"
  coordinatorRegex: null
  topologyLockTimeout: 0
  topologyLockDelay: 20000
  coordinatorTopology: "UNMANAGED"
storage:
  directory: "data/graphdb"
  backupDirectory: "data/backup"
  exportDirectory: "data/export"
  startServer: false
  synchronizeWrites: true
  synchronizeWritesTimeout: 60000
  txRetryDelay: 10
  txRetryLimit: 10
  txCommitTimeout: 0
  parameters: {}
search:
  url: "http://localhost:9200"
  username: null
  password: null
  certPath: null
  caPath: null
  hostnameVerification: true
  timeout: 60000
  startupTimeout: 45
  startEmbedded: true
  embeddedArguments: "-Xms1g -Xmx1g -XX:+UseConcMarkSweepGC -XX:CMSInitiatingOccupancyFraction=75\
    \ -XX:+UseCMSInitiatingOccupancyOnly -XX:+AlwaysPreTouch -client -Xss1m -Djava.awt.headless=true\
    \ -Dfile.encoding=UTF-8 -Djna.nosys=true -XX:-OmitStackTraceInFastThrow -Dio.netty.noUnsafe=true\
    \ -Dio.netty.noKeySetOptimization=true -Dio.netty.recycler.maxCapacityPerThread=0\
    \ -Dlog4j.shutdownHookEnabled=false -Dlog4j2.disable.jmx=true -XX:+HeapDumpOnOutOfMemoryError"
  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
upload:
  byteLimit: 262144000
  directory: "data/binaryFiles"
  tempDirectory: "/opt/mesh/data/tmp/temp-uploads"
  parserLimit: 40000
  parser: true
  metadataWhitelist: null
security:
  tokenExpirationTime: 3600
  keystorePassword: "<Your Password>"
  keystorePath: "config/keystore.jceks"
  algorithm: "HS256"
  enableAnonymousAccess: true
  publicKeysPath: "config/public-keys.json"
image:
  imageCacheDirectory: "data/binaryImageCache"
  maxWidth: 2048
  maxHeight: 2048
  jpegQuality: 0.95
  resampleFilter: "LANCZOS"
content:
  autoPurge: true
cache:
  pathCacheSize: 20000
debugInfo:
  logFolder: "debuginfo"
  logFileSize: "5MB"
  logEnabled: true
  logPattern: "%d{HH:mm:ss.SSS} [%meshName] %-5level [%thread] [%file:%line] - %msg%n"

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)"
    }
}
Please note that the contentLanguages property in the mesh-ui2-config.js file also needs to be updated in order to show the language in the UI.
The mesh-compose project contains a full example configuration which shows how to add a custom language.

HTTPS/SSL

Server Options

Property Mandatory Type Description

certPath

false

string

Flag which indicates whether SSL support be enabled.

clientAuthMode

false

string

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

corsAllowCredentials

false

boolean

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

corsAllowedOriginPattern

false

string

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

enableCors

false

boolean

Flag which indicates whether CORS handling should be enabled.

host

false

string

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

http

false

boolean

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

keyPath

false

string

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

port

false

integer

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

serverTokens

false

boolean

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

ssl

false

boolean

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

sslPort

false

integer

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

trustedCertPaths

false

array

Configure the trusted SSL certificates.

verticleAmount

false

integer

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

Cluster Options

Property Mandatory Type Description

clusterName

false

string

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

coordinatorMode

false

string

The coordinator mode will add an additional request controller plane which will internally process requests in-between cluster nodes. Default: DISABLED

coordinatorRegex

false

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.

coordinatorTopology

false

string

The coordinator topology setting controls whether the coordinator should manage the cluster topology. By default no cluster topology management will be done.

enabled

false

boolean

Flag to enable or disable the cluster mode.

networkHost

false

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.

topologyLockDelay

false

integer

Define the delay in ms for the topology lock. It will delay the lock after receiving the database online event. Default: 20000. A value of 0 will disable the delay mechanism.

topologyLockTimeout

false

integer

Define the timeout in ms for the topology lock. The topology lock will lock all transactions whenever the cluster topology changes. Default: 0. A value of 0 will disable the locking mechanism.

vertxPort

false

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

backupDirectory

true

string

Path to the graph database backup directory.

directory

true

string

Path to the graph database data directory.

exportDirectory

true

string

Path to the graph database export directory.

parameters

false

object

Additional set of graph database parameters.

startServer

true

boolean

Flag which indicates whether the graph database admin web server should be started. Default: false

synchronizeWrites

true

boolean

Flag which controls whether writes to the graph database should be synchronized. Default: true

synchronizeWritesTimeout

true

integer

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

txCommitTimeout

false

integer

The transaction commit timeout in milliseconds. A timeout value of zero means that transaction commit operations will never timeout.

txRetryDelay

false

integer

The delay in milliseconds when a transaction has to be retried.

txRetryLimit

false

integer

The limit for the tx retires.

OrientDB parameters

Configuration Type Default Description

ridBag.embeddedToSbtreeBonsaiThreshold

Number

2147483647

Configures the ridbag threshold for OrientDB. This setting controls how OrientDB manages the internal ridbag data structure. This setting will be ignored when run in clustered mode. See OrientDB documentation for more details.

Search Options

Property Mandatory Type Description

bulkDebounceTime

false

integer

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

bulkLengthLimit

false

integer

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

bulkLimit

false

integer

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

caPath

false

string

Path to the trusted common authority certificate (PEM format)

certPath

false

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

false

string

This setting controls the compliance mode for Elasticsearch. When set to ES_7 it will support Elasticsearch 7.x - In PRE_ES_7 mode it will support Elasticsearch 6.x - Default: PRE_ES_7

embeddedArguments

false

string

String of arguments which will be used for starting the Elasticsearch server instance

eventBufferSize

false

integer

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

hostnameVerification

false

boolean

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

idleDebounceTime

false

integer

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

includeBinaryFields

false

boolean

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

mappingMode

false

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

false

string

Password to be used for Elasticsearch authentication.

prefix

false

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

false

integer

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

retryLimit

false

integer

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

startEmbedded

false

boolean

Flag which indicates whether to deploy and start the included Elasticsearch server.

startupTimeout

false

integer

Timeout for Elasticsearch startup. Default: 45sec

syncBatchSize

false

integer

Configure the index sync batch size. Default: 50000

timeout

false

integer

Timeout for Elasticsearch operations. Default: 60000ms

url

false

string

Elasticsearch connection url to be used. Set this setting to null will disable the Elasticsearch support.

username

false

string

Username to be used for Elasticsearch authentication.

waitForIdle

false

boolean

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

Upload Options

Property Mandatory Type Description

byteLimit

false

integer

The upload size limit in bytes. Default: 250

directory

false

string

Path binary data storage directory. Fileuploads will be placed here.

metadataWhitelist

false

array

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

parser

false

boolean

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

parserLimit

false

integer

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

tempDirectory

false

string

Path to the file upload temporary directory. Inbound file uploads will be placed here before they are processed.

Security Options

Property Mandatory Type Description

algorithm

true

string

Algorithm which is used to verify and sign JWT.

enableAnonymousAccess

false

boolean

Flag which indicates whether anonymous access should be enabled.

keystorePassword

true

string

The Java keystore password for the keystore file.

keystorePath

true

string

Path to the java keystore file which will be used to store cryptographic keys.

publicKeysPath

false

string

Path to the public keys file which contains a list of additional JWK formatted public keys which will be used to verify JWTs.

tokenExpirationTime

true

integer

Time in minutes which an issued token stays valid.

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

false

boolean

Enable or disable the monitoring system. Default is: true

host

false

string

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

jvmMetricsEnabled

false

boolean

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

port

false

integer

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

Image Options

Property Mandatory Type Description

imageCacheDirectory

false

string

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

jpegQuality

false

number

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

maxHeight

false

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

false

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

resampleFilter

false

string

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

Cache Options

Property Mandatory Type Description

pathCacheSize

false

integer

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

Additionally it is possible to tweak the underlying OrientDB cache settings.

Debug Information Options

Property Mandatory Type Description

logEnabled

false

boolean

Enables the debug info log.

logFileSize

false

string

The maximum file size of a single log file.

logFolder

false

string

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

logPattern

false

string

The pattern used for each log line.

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.

-Dstorage.diskCache.bufferSize

Disk buffer size in megabytes used for the graph database. The disk cache will make use of direct memory that is independent of the above setting.

The total amount of required memory is the roughly sum of heap memory + direct memory + disk cache + (stack size * thread count) + 256 MB (OrientDB + 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:

  • Graph Database - The graph database contains the main content of Gentics Mesh. The DB can be backed up on demand via /api/v2/admin/graphdb/backup endpoint or via the OrientDB backup job using automatic-backup.json. This will automatically create a full backup. Note that both backup processes will block the application. The graph database backup process will write a backup file to the configured backup location (see [Storage Location]).

  • 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.

The POST /api/v2/admin/graphdb/restore endpoint can be used to restore created backups. The endpoint will utilize the latest backup found in the backup directory.

Invoking the backup/restore endpoints will block all execution and request processing. Reverse proxies may return a timeout error when the request takes too long.
The backup endpoint will only create a backup of the graph database. The other components need to be handled separately.
The restore operation can’t be executed on Mesh instances which have clustering enabled.

If you already run Gentics Mesh in a cluster you can start a dedicated backup instance which can run the backup process without interference of the other nodes.

Take a look at our docker-compose example for a documented setup.

Import & Export

The POST /api/v2/admin/graphdb/export and POST /api/v2/admin/graphdb/import endpoints can be used to generate Graph Database export files which are gzipped json files. A large database can be exported and reimported again to reduce the sparse file size.

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=-backup,consistencyCheck will exclude the database backup 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

  • default-distributed-db-config.xml

  • orientdb-server-config.xml

Consistency Check

Query name: consistencyCheck

Performs a consistency check and includes the result.

Database Backup

Query name: backup

Including this will cause the database to be in read only mode for the duration of the backup.

Performs a Graph database backup and includes the files.

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

Status

Query name: 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.

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

This list contains an overview over Gentics Mesh releases and the their database revisions. The database revision is different if the used Graph Database version was updated or if the database structure was altered due to an automatic change.

Version Database revision

1.7.4

7619dc72

1.7.5

7619dc72

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"
  } ]
}

Filesystem support

The filesystem ZFS (ZFS on Linux) does currently not support Direct IO on Linux.

When using ZFS it is thus required to turn off direct IO usage of OrientDB. Please use the -Dstorage.wal.allowDirectIO=false setting in this case.

The direct IO support will be included in ZFS 0.8

License