Installation

Table of Contents

Why Kubernetes?

Kubernetes is an open-source container-orchestration system for automating application deployment, scaling, and management. It replaces many manual tasks that have typically been performed by the operations teams, thereby improving uptime, reliability and reproducability of deployments. As already mentioned in the Recommended Deployment section, we recommend Kubernetes as a platform for running Gentics Content Management Platform in production.

Gentics provides both the container images and the necessary Kubernetes resource configuration (as Helm charts) for Gentics CMS and Gentics Mesh. Depending on your contract, images and resource configuration for Gentics Portal will either be provided by Gentics or created by yourself.

Helm charts are our prefered way of packaging all configuration required by Kubernetes (e.g., which containers have to be started, network connectivity, storage, environment settings, …). To allow you to customize your deployment, we provide a documented “values” file for each component. It is suggested to maintain these files in source control.

Prerequisites

The following documentation expects that you already performed the following steps:

This guide expects that your already have a running Kubernetes cluster. If you don’t have one yet, you can either follow the Kubernetes Getting Started Guide or use any compatible solution, e.g. Red Hat Openshift, Google Kubernetes Engine, Amazon Elastic Kubernetes Service, Azure Kubernetes Service, Rancher, etc. This guide focuses on the open source version of Kubernetes — YMMV.
Decide which persistent storage is to be used for shared persistent data, and for direct I/O data. Typically, NFS is used for the former, and iSCSI for the latter. Please review your options in the Kubernetes Storage Concepts, and check with your infrastructure provider which solutions is the best fit. Also, make sure you have read our Recommended Deployment section on storage.
Kubernetes uses namespaces to separate applications and deployment stages. Therefore, it is possible to deploy Gentics Content Management Platform multiple times on a single cluster. Please make sure you specify the correct namespace at all times. Refer to the namespaces walkthrough guide and create the necessary namespace(s).
Please make sure that the required network connectivity between the applications and components is guaranteed. This is especially important if you spread the components over multiple namespaces, plan to define NetworkPolicy resources, or have a mixed Kubernetes/non-Kubernetes deployment.
As we use Helm charts for installation, please install the Helm client on your local machine (no software needs to be installed on the servers or in the Kubernetes cluster). Follow the Installing Helm instructions.
Your Gentics technical customer consultant will provide you with a pull secret that allows your Kubernetes cluster to authenticate to the Gentics docker registry and download proprietary software images. Once you created the namespace, create a docker secret in the correct namespace. For convenience, you can now configure the service account to use it, so you don’t have to specify it in every _values.yaml.
You will also receive an API key for accessing our commercial Helm charts. Please add the Gentics Helm repository to your installation:
```
helm repo add --username USERNAME --password API_KEY gentics \
  https://repo.apa-it.at/artifactory/gtx-helm/
```
For some components, we make use of Helm charts provided by the third parties Elastic, Bitnami and codecentric. To use them, please register the corresponding open source Helm repositories:
```
helm repo add elastic https://helm.elastic.co
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add codecentric https://codecentric.github.io/helm-charts
```

Finally, update the repository information of your Helm client by running:
```
helm repo update
```

Install MariaDB

If you have an existing MariaDB installation, you can skip this step.
Please decide whether you need a clustered or single instance installation of MariaDB, taking our Recommended Deployment into account.

Single instance MariaDB

Check the default values of the chart:
```
helm show values bitnami/mariadb
```
Create a values.yaml containing all values that you want to override. Make sure you add this file to your version control to keep track of changes. Please refer to the MariaDB Helm chart documentation for configuration options. Take special interest in the values rootUser, db, master.persistence, master.config, replication, and slave.persistence. You need to make sure that the config file you provide matches both the requirements of the Helm chart (e.g. when it comes to paths) and the database settings required by Gentics CMS.

Install the MariaDB Helm chart:

helm -n NAMESPACE upgrade -i -f mariadb/values.yaml \
  mariadb bitnami/mariadb

MariaDB Galera cluster

Follow the same procedure as for a single instance MariaDB, but use the Helm chart bitnami/mariadb-galera instead. Please refer to the MariaDB Galera cluster Helm chart documentation for configuration options. Take special interest in the values rootUser, db, galera, mariadbConfiguration and persistence.

Install Keycloak

If you have an existing Keycloak installation, or don’t plan to use single sign-on, you can skip this step.

Check the default values of the chart:

Check the default values of the chart:
```
helm show values codecentric/keycloak
```
Create a values.yaml containing all values that you want to override. Make sure you add this file to your version control to keep track of changes. Please refer to the Keycloak Helm chart documentation for configuration options. Take special interest in the value keycloak.password.

Install the Keycloak Helm chart:

helm -n NAMESPACE upgrade -i -f keycloak/values.yaml \
  keycloak codecentric/keycloak

Once Keycloak is up and running, log in using the chosen password and create two realms: one for the Gentics Portal (that will hold all users that are allowed to log into the website), and one for Gentics CMS (that will hold all users that are allowed to log into Gentics CMS). Please refer to the steps outlined in the Docker Installation documentation for a detailed description.

Install Elasticsearch

If you have an existing Elasticsearch installation or don’t plan to use search features, you can skip this step.

Check the default values of the chart:
```
helm show values elastic/elasticsearch
```
Create a values.yaml containing all values that you want to override. Make sure you add this file to your version control to keep track of changes. Please refer to the Elasticsearch 6.8 Helm chart documentation for configuration options. Take special interest in the values replicas, imageTag, and persistence. Make sure that the Elasticsearch version you are using is within the supported range of Gentics CMS and Gentics Mesh.

Install the Elasticsearch 6.8 Helm chart:

helm -n NAMESPACE upgrade -i -f elasticsearch/values.yaml \
  elasticsearch elastic/elasticsearch --version 6.8

If you plan on using the word decompounder for German, you need to create an extraVolume and mount it under /usr/share/elasticsearch/config/analysis/. Then, follow the Gentics CMS Elasticsearch guide to download the required files and copy them onto this volume.

Install Gentics Mesh

Check the default values of the chart:
```
helm show values gentics/gentics-mesh
```
Create a values.yaml containing all values that you want to override. Make sure you add this file to your version control to keep track of changes. Take special interest in the values replicaCount, persistence, keystore.password, backup.enabled, credentials.initialAdminPassword Set the Elasticsearch base URL at elasticsearch.url. Set the Keycloak public key (as a JSON encoded string) at config.publicKeys.
First the initial master database needs to be setup. This will automatically be handled by the Helm chart when replicaCount=1. Thus, install the Gentics Mesh Helm chart with:
```
helm -n NAMESPACE upgrade -i --wait -f gentics-mesh/values.yaml \
  --set "replicaCount=1,backup.enabled=false" \
  gentics-mesh gentics/gentics-mesh
```

Once the database is setup you can start the full cluster.

helm -n NAMESPACE upgrade -f gentics-mesh/values.yaml \
  gentics-mesh gentics/gentics-mesh

Install Gentics CMS

Check the default values of the chart:
```
helm show values gentics/cms
```
Create a values.yaml containing all values that you want to override. Make sure you add this file to your version control to keep track of changes. Take special interest in the values persistence, config.cms and backup. Set the database values to point to your MariaDB installation. Set licensekey to the value you received from your Gentics technical customer consultant. Set the values in keycloak to match your Keycloak installation.

Install the Gentics CMS Helm chart:

helm -n NAMESPACE upgrade -i -f gentics-cms/values.yaml \
  gentics-cms gentics/cms

Once Gentics CMS in fully started, you can proceed with configuring the Gentics Mesh Content Repository in the user interface, following the instructions in the documentation. When completed, check and repair the content repository, and publish all objects.

Install Gentics Portal

As the Gentics Portal | php deployment is always tailor-made for each project, you will receive detailed installation instructions during the project setup phase.

Check if you would like to use pre-defined PVs, and set them in your values.yaml
Generate your API key as instructed by the Mesh chart, and set it in your values.yaml

Install the Gentics Portal | php Helm chart:

helm -n NAMESPACE upgrade -i -f gentics-portal/values.yaml \
  gentics-portal gentics/gentics-portal-php