Gentics Logo

Infoportal

Installing the Gentics Content Management Platform using Docker

On this page you will learn how to setup your 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. 

Preparation

Please make sure that the required network connectivity between the applications and components is guaranteed. 

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

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.gentics.com/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.gentics.com/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.gentics.com/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. 

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 
db_1            docker-entrypoint.sh --sql ...   Up              0.0.0.0:3306->3306/tcp
keycloak_1      /opt/jboss/tools/docker-en ...   Exit 0 
mesh_1          java -Djna.tmpdir=/tmp/.jn ...   Exit 1 
portal_1        /bin/bash /entrypoint.sh j ...   Exit 143

this servise is running — it has a docker health check configured

this service is running — it has no health check configured

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"]


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.