Administration Guide

Software Stack

Component Type Version

OrientDB

Graph Database

2.2.x

Ferma

OGM

2.2.x

Elasticsearch

Search Engine

2.4.x

Vert.x

Core Framework

3.4.x

Hazelcast

In-Memory Data Grid

3.5.x

https://google.github.io/dagger/

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 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 Oracle Java Runtime 1.8.0_40 or newer. 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.

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
or
docker run -v /opt/data/:/mesh/data -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 /opt/data/:/mesh/data -p 8080:8080 gentics/mesh

Installation Directory

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

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

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 and the Elasticsearch index are stored within the graphdb and searchindex folders, respectively. 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.

System Requirements

Server Requirements

Gentics Mesh comes with OrientDB, an embedded graph database and Elasticsearch. There are no external dependencies besides Oracle Java Runtime 1.8.0_40 or newer.

System Configuration

The max 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
tempDirectory: "/opt/mesh/data/tmp"
httpServer:
  port: 8080
  corsAllowedOriginPattern: ""
  corsAllowCredentials: false
  enableCors: false
cluster:
  enabled: false
  vertxPort: 0
storage:
  directory: "data/graphdb"
  backupDirectory: "data/backup"
  exportDirectory: "data/export"
  startServer: false
  parameters: {}
search:
  directory: "data/searchindex"
  httpEnabled: false
  transportPort: "9300-9400"
  parameters: {}
upload:
  byteLimit: 262144000
  directory: "data/binaryFiles"
  tempDirectory: "/opt/mesh/data/tmp/temp-uploads"
security:
  tokenExpirationTime: 3600
  keystorePassword: "TxYmUt3wtYnx"
  keystorePath: "config/keystore.jceks"
  algorithm: "HS256"
  enableAnonymousAccess: true
image:
  imageCacheDirectory: "data/binaryImageCache"
  maxWidth: 2048
  maxHeight: 2048

General Settings

Configuration Type Description

clusterMode

Flag

The internal hazelcast in-memory data grid will be enabled if this flag is set to true.

updateCheck

Flag

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

defaultPageSize

Number

Default page size.

defaultLanguage

String

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

Path to the main temporary filesystem directory.

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 Description

httpServerOptions.port

Number

HTTP Port number.

httpServerOptions.ssl

Boolean

Enable or disable SSL support.

httpServerOptions.corsAllowedOriginPattern

RegEx

Regex which will validate the origin CORS header.

httpServerOptions.enableCors

Boolean

Enable CORS support.

httpServerOptions.certPath

Path

SSL certificate path.

httpServerOptions.keyPath

Path

SSL key path.

Cluster Options

Configuration Type Description

cluster.enabled

Path

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

Boolean

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

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 Description

storageOptions.directory

Path

Path to the graph database storage location.

storageOptions.backupDirectory

Path

Backup directory.

storageOptions.exportDirectory

Path

Export directory.

storageOptions.startServer

Boolean

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.

storageOptions.parameters

JSON

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

Search Options

Configuration Type Description

search.directory

Path

Path to the elasticsearch storage location.

search.httpEnabled

Boolean

Enable the elasticsearch http endpoint.

search.transportPort

String

Range for the binary transport ports

Upload Options

Configuration Type Description

uploadOptions.byteLimit

Number

Upload limit in bytes.

uploadOptions.directory

Path

Filesystem directory for uploaded binary data.

uploadOptions.tempDirectory

Path

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

Security Options

Configuration Type Description

security.tokenExpirationTime

Number

The JWT expiration timeout.

security.keystorePath

Path

Path to Java keystore file.

security.keystorePassword

String

Password for the Java keystore file.

security.algorithm

String

Hashing algorithm used to sign, verify and generate tokens.

security.enableAnonymousAccess

Boolean

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 graph and Elasticsearch database cache settings.

Backup & Recovery

The /api/v1/admin/graphdb/backup and /api/v1/admin/graphdb/restore endpoints can be used to create and restore backups. Please note that invoking these endpoints will block all execution and request processing.

The graph database backup process will write a backup file to the configured backup location (see [Storage Location]). It is advised to restart Gentics Mesh once a backup has been restored.

License