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:
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]
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 <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:
- 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:
- 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).
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"]
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.