Administration Guide

Software Stack

Component Type Version

OrientDB

Graph Database

2.2.x

Ferma

OGM

2.4.x

Elasticsearch

Search Engine

6.1.x

Vert.x

Core Framework

3.5.x

Hazelcast

In-Memory Data Grid

3.5.x

Dagger 2

Dependency Injection

2.6.x

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

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:

Environment Variables

Settings within the mesh.yml file can be override via these environment variables.

Variable Description

MESH_AUTH_OAUTH2_SERVER_CONF_CONFIDENTIAL_PORT

Override the configured OAuth2 confidential port.

MESH_AUTH_OAUTH2_SERVER_CONF_AUTH_SERVER_URL

Override the configured OAuth2 server URL.

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 SSL enable flag.

MESH_CLUSTER_NETWORK_HOST

Override the cluster network host.

MESH_LOCK_PATH

Path to the mesh lock file.

MESH_PLUGIN_DIR

Override the configured plugin directory.

MESH_VERTX_WORKER_POOL_SIZE

Override the configured Vert.x worker pool size.

MESH_HTTP_SSL_CERT_PATH

Override the configured SSL enable flag.

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_CLUSTER_VERTX_PORT

Override the vert.x eventbus server port.

MESH_HTTP_CORS_ALLOW_CREDENTIALS

Override the configured CORS allowed credentials flag.

MESH_ELASTICSEARCH_STARTUP_TIMEOUT

Override the configured elasticsearch server timeout.

MESH_AUTH_OAUTH2_MAPPER_SCRIPT_PATH

Override the configured OAuth2 mapper script 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_AUTH_KEYSTORE_PASS

Override the configured keystore password.

MESH_GRAPH_EXPORT_DIRECTORY

Override the graph database export directory.

MESH_AUTH_OAUTH2_SERVER_CONF_RESOURCE

Override the configured OAuth2 server resource name.

MESH_BINARY_UPLOAD_LIMIT

Override the configured binary byte upload limit.

MESH_HTTP_SSL_KEY_PATH

Override the configured SSL enable flag.

MESH_TEMP_DIR

Override the configured temp 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_BINARY_DIR

Override the configured binary data directory.

MESH_UPDATECHECK

Override the configured updatecheck flag.

MESH_ELASTICSEARCH_START_EMBEDDED

Override the start embedded elasticsearch server flag.

MESH_AUTH_JWT_ALGO

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

MESH_AUTH_OAUTH2_SERVER_CONF_AUTH_SSL_REQUIRED

Override the configured OAuth2 server SSL-required flag.

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_CLUSTER_NAME

Override the cluster name.

MESH_AUTH_OAUTH2_SERVER_CONF_REALM

Override the configured OAuth2 server realm.

MESH_ELASTICSEARCH_TIMEOUT

Override the configured elasticsearch server timeout.

MESH_IMAGE_MAX_WIDTH

Override the max width for image resize operations.

MESH_VERTX_EVENT_POOL_SIZE

Override the configured Vert.x event pool size.

MESH_AUTH_ANONYMOUS_ENABLED

Override the configured anonymous enabled flag.

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_AUTH_OAUTH2_MAPPER_SCRIPT_DEV_MODE

Override the configured OAuth2 mapper script development mode flag.

MESH_NODE_NAME

Override the configured node name.

MESH_CLUSTER_ENABLED

Override cluster enabled flag.

MESH_AUTH_OAUTH2_ENABLED

Override the configured OAuth2 enabled flag.

MESH_AUTH_KEYSTORE_PATH

Override the configured keystore path.

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

Installation Directory

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

 data
    binaryFiles
    binaryImageCache
    graphdb
    tmp
 config
    keystore.jceks
    default-distributed-db-config.json
    orientdb-server-config.xml
    security.json
    hazelcast.xml
    mesh-ui-config.js
    mesh.yml
elasticsearch

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 and Elasticsearch. There are no external dependencies besides Java Runtime 8.

System Configuration

The maxium 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.

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.

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"
updateCheck: true
vertxOptions:
  workerPoolSize: 20
  eventPoolSize: 16
tempDirectory: "/opt/mesh/data/tmp"
pluginDirectory: "plugins"
httpServer:
  port: 8080
  host: "0.0.0.0"
  corsAllowedOriginPattern: ""
  corsAllowCredentials: false
  enableCors: false
  ssl: false
  certPath: "config/cert.pem"
  keyPath: "config/key.pem"
cluster:
  enabled: false
  vertxPort: 0
storage:
  directory: "data/graphdb"
  backupDirectory: "data/backup"
  exportDirectory: "data/export"
  startServer: false
  parameters: {}
search:
  url: "http://localhost:9200"
  timeout: 8000
  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"
  bulkLimit: 2000
  prefix: "mesh-"
upload:
  byteLimit: 262144000
  directory: "data/binaryFiles"
  tempDirectory: "/opt/mesh/data/tmp/temp-uploads"
security:
  tokenExpirationTime: 3600
  keystorePassword: "<Your Password>"
  keystorePath: "config/keystore.jceks"
  algorithm: "HS256"
  enableAnonymousAccess: true
  oauth2:
    enabled: false
    config:
      realm: "master"
      authServerUrl: "http://localhost:3000/auth"
      sslRequired: "external"
      resource: "mesh"
      credentials:
        secret: "9b65c378-5b4c-4e25-b5a1-a53a381b5fb4"
      confidentialPort: 0
    mapperScriptPath: "config/mymapper.js"
    mapperScriptDevMode: true
image:
  imageCacheDirectory: "data/binaryImageCache"
  maxWidth: 2048
  maxHeight: 2048

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.

Example for custom languages file:

{
    "sq-KS": {
        "name": "Albanian (Kosovo)",
        "nativeName": "Shqip (Kosovo)"
    }
}

HTTPS/SSL

To enable HTTPS you have to specify the server key and the server certificate within the configuration.

For testing purposes you may want to create a self signed certificate like this:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 90 -nodes

Server Options

Configuration Type Default Description

httpServer.port

Number

8080

HTTP Port number.

httpServer.host

String

0.0.0.0

Host to bind mesh to

httpServer.ssl

Boolean

false

Enable or disable SSL support.

httpServer.corsAllowedOriginPattern

RegEx

-

Regex which will validate the origin CORS header.

httpServer.scorsAllowCredentials

Boolean

false

Enable CORS credential support.

httpServer.enableCors

Boolean

false

Enable CORS support.

httpServer.certPath

Path

-

SSL certificate path.

httpServer.keyPath

Path

-

SSL key path.

Cluster Options

Configuration Type Default Description

cluster.enabled

Path

false

This setting is optional and can be used to configure the network which the cluster daemons bind to. Gentics Mesh will try to determine the network automatically if no setting has been provided. The value of this setting will currently also be used to connect other instances to the configured instance. So make sure that the IP/Host can be reached from other potential instances in your network.

cluster.networkHost

String

-

Host which will be used to bind clustering related ports

cluster.clusterName

String

-

Name of the cluster which will be used to group multiple instances together. The setting is required when clustering is enabled. It can also be used to form a new cluster next to an existing cluster. Only instances with the same clusterName will be able to find eachother.

cluster.vertxPort

Number

0 (random)

The vertxPort setting is used by the Vert.x eventbus message service. By default vert.x will choose any free port and utilize it for the service.

nodeName

String

-

The node name is used to identify the instance in the cluster. The name must be unique to a single instance and should not be changed.

Storage Options

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

Configuration Type Default Description

storage.directory

Path

data/graphdb

Path to the graph database storage location.

storage.backupDirectory

Path

data/backup

Backup directory.

storage.exportDirectory

Path

data/export

Export directory.

storage.startServer

Boolean

false

Flag that indicates whether the graph database server component should be started. By default only an embedded graph database is used which does not start a graph server.

storage.parameters

JSON

-

Additional JSON parameters that will be passed on to the used graph database implementation.

Search Options

Configuration Type Default Description

search.url

String

http://localhost:9200

URL to the Elasticsearch server.

search.timeout

Number

3000

Timeout for interactions with the search server.

search.startEmbedded

Boolean

true

Flag that is used to enable or disable the automatic startup and handling of the embedded Elasticsearch server.

search.embeddedArguments

String

Default JVM Arguments

Set the JVM arguments for the embedded Elasticsearch server process.

Upload Options

Configuration Type Default Description

upload.byteLimit

Number

262144000 (250 MB)

Upload limit in bytes.

upload.directory

Path

data/binaryFiles

Filesystem directory for uploaded binary data.

upload.tempDirectory

Path

data/tmp/file-uploads

Temporary directory for uploaded binary data. Finished files will be moved to the upload directory.

Security Options

Configuration Type Default Description

security.tokenExpirationTime

Number

3600 (1h)

The JWT expiration timeout in seconds.

security.keystorePath

Path

config/keystore.jceks

Path to Java keystore file.

security.keystorePassword

String

-

Password for the Java keystore file.

security.algorithm

String

HS256

Hashing algorithm used to sign, verify and generate tokens.

security.enableAnonymousAccess

Boolean

true

Flag to be used to enable the anonymous access feature.

Cache Options

Gentics Mesh does not manage any cache structure but it is possible to tweak the underlying OrientDB cache settings.

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

-XX:MaxDirectMemorySize

Maximum direct memory limit. Direct memory is mostly used to buffer transactions of the Graph Database.

Recommendations

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

Node Count Memory Setting

0 to 100

-Xms128m -Xmx128m -XX:MaxDirectMemorySize=128m

100 to 1_000

-Xms512m -Xmx512m -XX:MaxDirectMemorySize=256m

1_000 to 10_000

-Xms786m -Xmx786m -XX:MaxDirectMemorySize=384m

10_000 to 100_000

-Xms1250m -Xmx1250m -XX:MaxDirectMemorySize=512m

100_000 to 1_000_000

-Xms2500m -Xmx2500m -XX:MaxDirectMemorySize=1024m

Backup & Recovery

There are currently three 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/v1/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 recreated anytime using the POST /api/v1/search/sync endpoint.

The /api/v1/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.

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.

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/v1 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

0.28.1

de7eb14f

0.28.2

de7eb14f

Database Consistency

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

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

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

The POST /api/v1/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.

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

License