Communication and Interfaces

This section covers the different software components that make up or are used by the Gentics Content Management Platform.

Component Overview

The information in this section is structured according to different software packages and is grouped into logical components. The following sections will first describe how these logical components communicate with each other on a higher level, followed by information about how the communication works within a logical component.

• CMS: This logical component is comprised of the Gentics CMS, the MariaDB database server, as well as the Elasticsearch instance. Gentics CMS consists of a backend and a frontend application; while the former runs on your servers, the latter is executed in the user’s browser.
• Content Repository: An instance of Gentics Mesh and the Elasticsearch instance used by it.
• Portal: An instance of either the Gentics Portal | php or Gentics Portal | java frontend portal.
• Keycloak: An instance of Keycloak and the relational database management system it uses.
• External applications: Everything not mentioned in one of the above components. The most common example of such an external application is probably a client side JavaScript application which loads dynamic content from the frontend portal. Other examples are project specific internal​^[1] scripts that make use of the APIs provided by Gentics CMS or Gentics Mesh with the goal to automate tasks. 

Note that Elasticsearch is mentioned in the CMS component as well as the Mesh component. Both use Elasticsearch to index data that needs to be searchable. The index names created by Gentics Mesh and the Gentics CMS are distinct, so it is possible to use the same Elasticsearch instance (or cluster) for both the Gentics CMS and Gentics Mesh (this depends on the requirements and restrictions of the project setup, e.g. network topology, availability, etc.).

Communication between Components

CMS 

Gentics CMS communicates with the Gentics Mesh Content Repository in order to publish content, and with Keycloak for authentication. All communication with Gentics Mesh and Keycloak takes place via their respective REST APIs over HTTP or HTTPS. Communication is always initiated by Gentics CMS.

• Communication with Gentics Mesh: Gentics CMS uses the Gentics Mesh Java Client which provides methods for the API endpoints of Gentics Mesh. Since neither Gentics CMS nor Gentics Mesh are publicly accessible in a typical setup, it is usually not necessary to configure HTTPS for the communication.
• Communication with Keycloak: Gentics CMS uses Keycloak’s Servlet Filter Adapter and JavaScript Adapter to support Single Sign On (SSO) following the OpenID Connect standard. Since Keycloak must be reachable by a user’s browser, all communication should be encrypted using HTTPS.

Portal Component

Gentics Portal communicates with Gentics Mesh to load content (published by Gentics CMS), and with Keycloak for authentication. All communication with Gentics Mesh and Keycloak is performed using their respective REST APIs over HTTP or HTTPS. Communication is always initiated by Gentics Portal to Gentics Mesh/Keycloak

• Communication with Gentics Mesh: Gentics Portal | java and Gentics Portal | php use the Gentics Mesh Java Client and Gentics Mesh PHP Client respectively which provide methods for the API endpoints of Gentics Mesh. In a typical setup, Gentics Mesh runs on a server that is reachable from Gentics Portal (and Gentics CMS) but not from anywhere else, so HTTPS is not necessary between Gentics Portal and Gentics Mesh.
• Communication with Keycloak: Gentics Portal handles authentication and authorization via OAuth2 and Keycloak. Authentication follows the Code Flow specification where an unauthenticated request from a browser is redirected to a Keycloak login screen. Upon providing the correct credentials, an authorization code is issued, which is supplied to Gentics Portal. The portal will then use this authorization code to obtain an access token directly from Keycloak. 
  

External Applications

The most common use case of external applications in a Gentics Content Management Platform project will be client side JavaScript applications, but project specific internal applications which automate tasks in Gentics CMS or Gentics Mesh are also possible.

• Communication with Gentics Portal: Special functionality is often implemented in a custom handler in one of the Gentics Portals. What these custom handlers deliver is highly dependent on the project but will usually be either rendered HTML or API endpoints akin to a REST service. Since Gentics Portal is publicly accessible, the communication should always be over HTTPS.
• Communication with Gentics CMS: Gentics CMS offers a comprehensive REST API to automate many tasks. There are libraries for Java and JavaScript to simplify the usage of this API. Communication should be performed using HTTPS whenever the connection uses public networks.
• Communication with Gentics Mesh: Since Gentics Mesh is a headless CMS, each and every functionality is available through its REST API. Since Gentics Mesh should not be accessible publicly, it is highly recommended that all access to Gentics Mesh goes through the Gentics Portal. As described above the Gentics Portals communicate with Gentics Mesh via its REST API over HTTPS.

Loading data from Gentics Mesh

Loading data from Gentics Mesh (in particular content published by Gentics CMS) is the main reason for the Gentics Portal to communicate with Gentics Mesh. While all the communication is via the Gentics Mesh’s REST API, there are two ways to load data stored in Gentics Mesh:

• load a single entity (called a node in Gentics Mesh) via its identifier (UUID) or its path, or
• load any number of entities by describing the desired entities using the querying language GraphQL

The first method has to be used for all write operations (creating, updating or deleting a node). For read operations, using this method can still be the best options, when the UUID (or the unique path) of the entity is already known, and there is only one entity to load.

For all other reading requests a GraphqQL query might be the better solution, since the query language offers a very flexible way to specify filters, load additional languages, select which parts of the node are of interest, or make use of parent/child relationships between nodes.

Both Gentics Portal | php and Gentics Portal | java use GraphQL heavily to load page contents or navigation information (among others).

Communication within single components

CMS Component

The Gentics CMS backend server uses the JDBC[2] driver and mysqli to communicate with the configured database, using TCP.

Communication with Elasticsearch takes place via Elasticsearch’s REST API over HTTP.

Content Repository

Like Gentics CMS, Gentics Mesh makes use of Elasticsearch’s REST API.

Keycloak

Keycloak uses TCP and JDBC to communicate with its configured database.

External Applications

External applications usually do not have to communicate with anything else but the Gentics CMS, Gentics Mesh and the Gentics Portal, which have been outlined above.

Network Connectivity Requirements

It is paramount that, before you start installing the software, the required network connectivity between the components of the Gentics Content Management Platform, the users and other applications is assured. The following list is meant to be a starting point for your network setup. The port numbers mentioned are the default ports; your setup might differ. If you deploy load balancers for certain components, you need to extend the list accordingly.

For monitoring, Gentics Mesh and Gentics Portal | java allow you to specify a separate port/IP address, while Gentics CMS allows to to configure an IP address whitelist that is allowed to access the monitoring endpoint.

Please also consider that your continuous integration pipeline will need to access all components of the Gentics Content Management Platform via HTTP/HTTPS and also needs access to the filesystem. 

---

1. Unlike the frontend portal, the CMS and Content Repository components are usually not accessible from the outside.
2. Java Database Connectivity