Installing the Gentics Content Management Platform using Docker

Why Containers?

A container is a standard unit of software that packages up code and all its dependencies so the application runs quickly and reliably, and can be moved from one computing environment to another.

The Gentics Content Management Platform consists of multiple services. Their setup and composition can be prepared and reused using docker containers.

This will speed up setup as well as maintenance and will allow you to prepare local development environments.

Example Setup

To further improve the ease of use of docker containers we encourage the use of docker-compose to manage multiple containers.

Example docker-compose stack:

Servicename	Purpose	URL
Gentics CMS	Content Management	http://localhost
Gentics Mesh	Storage for Content Delivery	http://localhost:8200
Gentics Portal	Delivery	http://localhost:8000
Keycloak	Authentication	http://localhost:8080
Elasticsearch	Search	http://localhost:9200
MariaDB	Backend content storage and authentication storage	http://localhost:3306

Servicename

Purpose

URL

Gentics CMS

Content Management

http://localhost

Gentics Mesh

Storage for Content Delivery

http://localhost:8200

Gentics Portal

Delivery

http://localhost:8000

Keycloak

Authentication

http://localhost:8080

Elasticsearch

http://localhost:9200

MariaDB

Backend content storage and authentication storage

http://localhost:3306

The docker-compose.yml is the main configuration file for the docker setup.

A common use case is to have docker-compose.override.yml files that contain stage specific configuration.

docker-compose.yml

version: "3"
services:
  # name of the service
  # The CMS service will run Genitcs CMS on localhost:80 to allow editing and managing of our contents
  cms:
    # base image for the service
    image: docker.apa-it.at/gentics/cms:6.0.0
    # exposed ports to host
    # localhost:80 on the host environment will be bound to localhost:80 from inside of the container
    # note that the ports property is an array and can be exended
    ports:
      - '80:80'
    # which files should be added or replaced from the base image
    # use this to add your custom implementation and configuration
    volumes:
      # allow adding multiple cms configuration files
      # syntax of these files is php
      # https://www.gentics.com/Content.Node/cmp8/guides-oss/feature_overview.html
      - ./cms/cms-conf:/cms/conf
      # Gentics CMS DevTool packages see
      # https://www.gentics.com/Content.Node/cmp8/guides-oss/devtools_overview.html
      - ./cms/packages:/cms/packages
      # configuration files for Gentics CMS UI
      - ./cms/ui-conf:/cms/ui-conf
      # setup you service to persit its data in a named docker volume
      - cms_dbfiles:/cms/data/dbfiles

    # Setup environment variables for things not included in your config files
    # see https://www.gentics.com/Content.Node/cmp8/guides-oss/admin_docker.html#environment-variables
    environment:
      NODE_DB_USER: root
      NODE_DB_PASSWORD: ""
      NODE_DB_HOST: db
      NODE_USER_PASSWORD: node
      CONF_FILES: cms
      # Gentics CMS Licensekey
      # contact support@genitcs.com to get yours
      LICENSEKEY: TH1S-ISNO-TALI-CENS-EKEY
    # tell the cms service to wait for the db service before startup
    depends_on:
      - db

  # the `db` service will run an instance of MariaDB to store:
  # * CMS data
  # * Keycloak
  db:
    # a list of supported databases can be found here:
    # https://www.gentics.com/Content.Node/cmp8/guides-oss/gcn_compatibility_list.html#databases
    # this service uses the official mariadb image from dockerhub
    # https://hub.docker.com/_/mariadb
    image: mariadb:10.11
    command: --sql-mode=""
    volumes:
      # add an initial database dump to speed up the setup
      # this could also be a backup or snapshot of a specific development version
      - ./mariadb/.docker/cmssql-initdb:/docker-entrypoint-initdb.d
      # add a custom database configuration
      # a recommended configuration can be found in our installation guides:
      # https://www.gentics.com/Content.Node/cmp8/guides-oss/admin_install.html#database-server
      - ./mariadb/.docker/custom.cnf:/etc/mysql/conf.d/custom.cnf
      # persit storage of the database
      - cms_db_data:/var/lib/mysql
    environment:
      MYSQL_ALLOW_EMPTY_PASSWORD: "true"
      MYSQL_ROOT_PASSWORD: ""
    ports:
      - "3306:3306"

  # Gentics Mesh
  # Used for Content Delivery Storage and Search index setup
  mesh:
    image: docker.apa-it.at/gentics/mesh:2.0.0
    volumes:
      - mesh_graphdb:/graphdb
      - mesh_keystore:/keystore
      - mesh_uploads:/uploads
      - ./mesh/plugins/keycloak-plugin/storage:/plugins/keycloak/storage
    stop_grace_period: 5m
    ulimits:
      nofile:
        soft: 20000
        hard: 40000
    ports:
      - '8200:8080'
    environment:
      MESH_ELASTICSEARCH_URL: "http://elasticsearch:9200"
      MESH_ELASTICSEARCH_START_EMBEDDED: "false"
      MESH_UPDATECHECK: "false"
      MESH_AUTH_KEYSTORE_PASS: "changeme"
      MESH_INITIAL_ADMIN_PASSWORD: "admin"
      MESH_INITIAL_ADMIN_PASSWORD_FORCE_RESET: "false"
      MESH_GRAPH_TX_COMMIT_TIMEOUT: "30000"
      MESH_GRAPH_SYNC_WRITES_TIMEOUT: "60000"
      JAVA_TOOL_OPTIONS: "-Xms2g -Xmx2g -XX:MaxDirectMemorySize=212m -Dstorage.diskCache.bufferSize=212 -XX:+HeapDumpOnOutOfMemoryError"
      MESH_HTTP_SERVER_TOKENS: "false"

  # Gentics Portal | java
  portal:
    image: repo.example.com/your-portal-image:1.42
    ulimits:
      nofile:
        soft: 20000
        hard: 40000
    volumes:
      # project specific content delivery configuration
      - ./portal/data/queries:/portal/data/queries
      - ./portal/data/templates:/portal/data/templates
      # static frontend assets like stylesheets, javascript and design-images
      - ./cms/packages/reference/files:/portal/data/static/reference/files
      # setup scripts
      - ./portal/.docker/entrypoint.sh:/entrypoint.sh
      - ./portal/.docker/waitForMesh.sh:/portal/waitForMesh.sh
      - ./portal/.docker/mesh-gen-token.sh:/portal/mesh-gen-token.sh
      - ./portal/.docker/initRoles.sh:/portal/initRoles.sh
    # https://www.gentics.com/portal-java/docs/development/configuration/#environment-variables
    environment:
      MESH_HOST: "mesh"
      MESH_PORT: 8080
      MESH_PROJECT: "reference"
      SERVER_URL: "http://localhost:8000"
      SERVER_PORT: 8000
    ports:
      - '8000:8000'
    depends_on:
      - mesh

  keycloak:
    image: jboss/keycloak:19.0
    environment:
      KC_DB: mariadb
      KC_DB_URL: jdbc:mariadb://db/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: keycloak
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    ports:
      - '8080:8080'
    depends_on:
      - db
  elasticsearch:
    image: docker.apa-it.at/elasticsearch/elasticsearch-oss:6.8.2
    volumes:
      - esdata:/usr/share/elasticsearch/data
    environment:
      - discovery.type=single-node
      - bootstrap.memory_lock=true
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
    stop_grace_period: 5m
    ports:
      - '9200:9200'
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
      memlock:
        soft: -1
        hard: -1
  # add additional services as you need them
  # myService:
  #   image: ...

volumes:
  cms_db_data:
    driver: local
  cms_dbfiles:
    driver: local
  mesh_graphdb:
    driver: local
  mesh_keystore:
    driver: local
  mesh_uploads:
    driver: local
  esdata:
    driver: local

Usage

You can interact with your docker-compose stack from the command line. Here is a list of common commands to get you started:

start your stack / apply updates

docker-compose up --detach [servicename]

stop your stack

docker-compose stop

restart a particular service by name - example "cms"

docker-compose restart cms

show the last 1000 lines of the portal logfile and update on new entries

docker-compose logs --follow --tail=1000 portal

Find out more about how to setup and use docker-compose from docker-compose guides or in the command line with

docker-compose --help

docker-compose <command> --help

Setting up Keycloak in the Gentics Content Management Platform Stack

In order for Gentics Mesh, Gentics Portal and Gentics CMS to rely on Keycloak to handle permissions, some additional configuration has to be set up. For managing users and their token information please refer to the Keycloak guides.

Create the realm, client and users in Keycloak
- navigate to http://localhost:8080
- login with the credentials configured at the keycloak service in your docker-compose.yml
- hover over the realm name Master and click Add realm
- Name: EXTERNAL
- click ok
- make sure your new realm is selected
- navigate to Clients
- click create
- Client ID: portal
- on a publicly available system you will want to set the Valid Redirect URIs
see the Keycloak Server Administration Guide for more information
See the Gentics Portal | java documentation on how to generate the keycloak file for more details or follow these steps:
- create the file portal/.docker/keycloak.json
- get the public key from http://localhost:8080/auth/realms/EXTERNAL and place it this file
note that the host name needs to be reachable from outside and inside of a container.
- for local setups we use "auth-server-url": "http://keycloak:8080/auth",
- so setup an entry in /etc/hosts like
  
  127.0.0.1 keycloak
Copy and rename the docker-compose.example.yml to docker-compose.local.yml
See the Gentics Mesh documentation on how to setup Keycloak public keys for more info or follow these steps:
- Create the file mesh/.docker/public-keys.json
- Use the response from http://localhost:8080/auth/realms/EXTERNAL/protocol/openid-connect/certs as its content
restart the relevant services to use the new configuration

docker-compose restart portal mesh
once the portal is running, call http://<YOUR_PORTAL_HOST>:8000/api/initializeRoles
in Gentics CMS, execute “repair” on the Gentics Mesh Content Repository to use the roles from Gentics Mesh, and republish all content.

Health Checks

To automate your system status monitoring we offer ways to run health checks. The most basic check is to see if the service is running at all (meaning it did not exit with an error code).

docker-compose ps

A possible output could be:

    Name                   Command                  State            Ports
-------------------------------------------------------------------------------------------
cms_1           /bin/bash /entrypoint.sh         Up (healthy)    0.0.0.0:80->80/tcp (1)
db_1            docker-entrypoint.sh --sql ...   Up              0.0.0.0:3306->3306/tcp (2)
keycloak_1      /opt/jboss/tools/docker-en ...   Exit 0 (3)
mesh_1          java -Djna.tmpdir=/tmp/.jn ...   Exit 1 (3)
portal_1        /bin/bash /entrypoint.sh j ...   Exit 143 (3)

1	this servise is running — it has a docker health check configured
2	this service is running — it has no health check configured
3	this service is not running — it exited with an error code

Read more about docker health checks in the Docker guides.

However, this method only informs about the current process status. The application could still have issues, that result in it no longer being able to perform its task.

To improve, we can setup more precise health checks for the different services. In the following we will discuss how to setup these health checks for all Gentics services. For third party services please refer to their documentation.

Gentics CMS

The Gentics CMS Docker image comes with a Docker health check setup.

You can additionally run a GET request to http://<yourCMSHost>/rest/auth/globalprefix to ensure availability.

You can also set up JMX monitoring and use it as a basis for health checks.

Gentics Portal | java

It is advised to add a health check configuration to your docker-compose.yml to the portal service. Running a Netcat is sufficient to test availibility. More complex checks may be set up, but need to be adapted to the projects' API.

  portal:
    (...)
    healthcheck:
      test: ["CMD", "nc", "-z", "-v", "localhost", "8080"] (1)

1	Note that this port can be configured.

For more insights please refer to the Gentics Portal | java monitoring guide.

Gentics Portal | php

It is advised to add a health check configuration to your docker-compose.yml to the portal service. Running a Netcat is sufficient to test availibility. More complex checks may be set up, adapted to the projects' API.

  portal:
    (...)
    healthcheck:
      test: ["CMD", "nc", "-z", "-v", "localhost", "80"]

Gentics Mesh

You may use the REST API endpoint /health/live the retrieve health information.

Please refer to the Gentics Mesh monitoring guide for more information.

MariaDB

It is advised to add a health check configuration to your docker-compose.yml to the db service:

  db:
    image: mariadb:10.3
    (...)
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "--silent"]

Another option is to use mysqlcheck.

Keycloak

Please refer to the Keycloak documentation regarding the /oauth/health endpoint.

Elasticsearch

Please refer to the Elasticsearch documentation.

Installing the Gentics Content Management Platform using Docker