Migration from CMP 7.x to CMP 8.x

With CMP 8.x the architecture of the CMS has been changed significally. Instead of the hybrid architecture of prior versions (with PHP code running in an Apache HTTP Server and Java code running in an Apache Tomcat Server), the CMS now consists of only a single .jar file, which will start an embedded HTTP Server.

For migration of an existing installation to CMP 8.x, at least the following steps will be necessary:

1 Migrate configuration

When starting CMS 6.0 it is important to define which configuration files to load via a comma separated list in either

  • Environment variable `CONF_FILES`, or
  • Java system property `com.gentics.contentnode.config.files`

Note that for every directory in this list, all .yml files in the directory will be loaded.

1.1 Transform to .yml file(s)

The format of the configuration files has been changed from PHP files to YML files.

To help with the migration, there is a tool in the CMS (also available in CMP 7.x), which converts the current configuration into a YML file. The tool must be used in a CMS running CMP 7.x:


/Node/bin/java.sh com.gentics.contentnode.tools.MigrateConfiguration -config "http://localhost/.Node/?do=24" -out /tmp/new_configuration.yml

It supports the following command line parameters:

Parameter Description
-config URL to get configuration
-out Filename for writing the migrated configuration

The written configuration file will only contain configuration settings, which are different from the current default settings.

The tool only re-writes the current configuration (collected from all PHP-style configuration files) in the new format, but will not do necessary changes in the configuration. This has to be done manually (see chapters below).

1.2 Manual transformation of configuration settings

1.2.1 Enabling of features

In the old PHP-style configuration, features were enabled like this:

/Node/etc/conf.d/*.conf

$FEATURE["wastebin"] = true;

In the new format, this is done with:

features.yml

feature:
  wastebin: true
1.2.2 Database Access

PHP-style:

/Node/etc/conf.d/*.conf

$SETTINGS["db"] = "<dbname>";
$SETTINGS["server"] = "<dbhost>:<dbport>";
$SETTINGS["login"] = "<dbuser>";
$SETTINGS["pw"] = "<dbpassword>";

New format and configuration parameters:

db.yml

db:
  settings:
    url: jdbc:mariadb://<dbhost>:<dbport>/<dbname>
    user: <dbuser>
    password: <dbpassword>
1.2.3 Other settings

Most other settings will be transformed in the following way:

PHP-style:

/Node/etc/conf.d/*.conf

$ALOHA_SETTINGS['plugins']['block']['rootTags'] = array('div', 'span', 'a');

New format:

aloha.yml

aloha_settings:
  plugins:
    block:
      rootTags:
        - "div"
        - "span"
        - "a"
1.2.3.1 Exceptions

There are two exception to the naming rule above:

  1. Settings in `$PUBLISH_LOAD_BALANCING` must be put under `config.loadbalancing`.
  2. Settings in `$VELOCITY_PROPERTIES` must be put under `velocity`.

PHP-style:

/Node/etc/conf.d/*.conf

$PUBLISH_LOAD_BALANCING["threadlimit"] = 2;

$VELOCITY_PROPERTIES["resource.loader"] = "string,file";

New format:

conf/*.yml

config
  loadbalancing:
    threadlimit: 2

velocity:
  resource.loader: "string,file"

1.3 Configuration changes

Some configuration parameters have been renamed or removed:

Parameter Change
cn_map_db_settings Removed
db.settings.login Renamed to db.settings.user
db.settings.pw Renamed to db.settings.password
filepath Removed
fileutils.class Removed
fileutils.encoding Removed
nodecopy_configfile Removed
nodepath Removed
selfupdate.updateFromLocal Removed
tidy_configuration Removed
ttm_skip_backup Removed
xnl_function Removed

1.4 Keycloak Integration

Keycloak integration is now done in the following steps

  1. Activate Feature
  2. Place keycloak.json as ui-conf/keycloak.json
  3. Optionally configure keycloak.user_created_callback
  4. Optionally configure keycloak.init_groups
keycloak.yml

feature:
  keycloak: true
keycloak:
  user_created_callback: your.companyname.custom.SsoUserCreated
  init_groups: |
    if(attr.roles.realm CONTAINSONEOF 'admin-user-role',
      [3],
      if(attr.roles.resource.gcms CONTAINSONEOF 'editor-user-role',
        [4],
        [5]
      )
    )

1.5 Property substitution

The new configuration files will now support property substitution in string values.

The general format for property substitution is ${key:property} where key defines substitution type, and property the property to be substituted:

Key Description Example Replacement
base64Encoder Replace with base64 encoded string ${base64Encoder:Hello World} SGVsbG8gV29ybGQ=
base64Decoder Replace with base64 decoded string ${base64Decoder:SGVsbG8gV29ybGQ=} Hello World
date Replace with current date ${date:yyyy-mm-dd} 2023-04-01
env Replace with value of environment variable ${env:USER} node
sys Replace with value of system property ${sys:user.name} node
urlEncoder Replace with URL encoded string ${urlEncoder:path with spaces} path<notextile><tt>with</tt></notextile>spaces
urlDecoder Replace with URL decoded string ${urlDecoder:path<notextile><tt>with</tt></notextile>spaces} path with spaces

1.6 Environment variables

The CMS now supports the following environment variables (some settings can also be set over Java System properties or in the CMS configuration):

1.6.1 HTTP_PORT
Description Http Port of the CMS
Env HTTP_PORT
System Property com.gentics.contentnode.http.port
Configuration server.port
Default 8080
1.6.2 HTTP2
Description Use HTTP/2 protocol version
Env HTTP2
System Property com.gentics.contentnode.http2
Configuration server.http2
Default 8080
1.6.3 CONF_PATH
Description Path to configuration files
Env CONF_PATH
System Property com.gentics.contentnode.config.path
Configuration
Default conf
1.6.4 DBFILES_PATH
Description Path to binary files
Env DBFILES_PATH
System Property com.gentics.contentnode.dbfiles.path
Configuration config.dbfiles
Default data/dbfiles
1.6.5 CONF_FILES
Description Comma separated list of configuration files or folders containing configuration files (relative to CONF_PATH)
Env CONF_FILES
System Property com.gentics.contentnode.config.files
Configuration
Default
1.6.6 LICENSEKEY
Description Path to license key file
Env LICENSEKEY
System Property com.gentics.contentnode.license-key.path
Configuration
Default
1.6.7 KEYS_PATH
Description Path to keys directory
Env KEYS_PATH
System Property com.gentics.contentnode.keys.path
Configuration
Default keys
1.6.8 CACHE_CONFIG_PATH
Description Path to cache.ccf
Env CACHE_CONFIG_PATH
System Property com.gentics.contentnode.cache.config.path
Configuration
Default CONF_PATH/cache.ccf
1.6.9 CACHE_PATH
Description Path to cache files
Env CACHE_PATH
System Property com.gentics.contentnode.cache.path
Configuration
Default cache
1.6.10 LOGS_PATH
Description Path to logs
Env LOGS_PATH
System Property com.gentics.contentnode.logs.path
Configuration
Default logs
1.6.11 PUBLISH_PATH
Description Path to statically published files
Env PUBLISH_PATH
System Property com.gentics.contentnode.publish.path
Configuration
Default publish
1.6.12 GIS_PATH
Description Path to statically published GIS files
Env GIS_PATH
System Property com.gentics.contentnode.gis.path
Configuration
Default PUBLISH_PATH/gis
1.6.13 PACKAGES_PATH
Description Path to the directory containing the devtool packages
Env PACKAGES_PATH
System Property com.gentics.contentnode.packages.path
Configuration
Default packages
1.6.14 CONTENT_PACKAGES_PATH
Description Path to the directory containing the content packages
Env CONTENT_PACKAGES_PATH
System Property com.gentics.contentnode.content_packages.path
Configuration
Default content-packages
1.6.15 SCHEDULER_COMNANDS_PATH
Description Path to the directory containing the scripts, that can be run by the scheduler
Env SCHEDULER_COMNANDS_PATH
System Property com.gentics.contentnode.scheduler_commands.path
Configuration
Default scheduler-commands
1.6.16 STATIC_SERVE_LIST
Description Comma separated list of directories that contain files, which should be served statically over HTTP
Env STATIC_SERVE_LIST
System Property com.gentics.contentnode.static_serve_list
Configuration
Default
1.6.17 UI_CONF_PATH
Description Path to UI configuration files
Env UI_CONF_PATH
System Property com.gentics.contentnode.ui.conf_path
Configuration ui.conf_path
Default ui-conf
1.6.18 TMP_PATH
Description Path to store temporary files
Env TMP_PATH
System Property com.gentics.contentnode.tmp_path
Configuration tmppath
Default System property java.io.tmpdir
1.6.19 NODE_USER_PASSWORD
Description Initial password for the CMS user ‘node’
Env NODE_USER_PASSWORD
System Property com.gentics.contentnode.node_user.password
Configuration
Default
1.6.20 NODE_DB_DRIVER_CLASS
Description Name of the JDBC Driver class for accessing the backend DB
Env NODE_DB_DRIVER_CLASS
System Property com.gentics.contentnode.db.driverClass
Configuration db.settings.driverClass
Default org.mariadb.jdbc.Driver
1.6.21 NODE_DB_HOST
Description Hostname of the backend DB
Env NODE_DB_HOST
System Property com.gentics.contentnode.db.host
Configuration db.settings.host
Default localhost
1.6.22 NODE_DB_PORT
Description Port of the backend DB
Env NODE_DB_PORT
System Property com.gentics.contentnode.db.port
Configuration db.settings.port
Default 3306
1.6.23 NODE_DB_USER
Description Username for accessing the backend DB
Env NODE_DB_USER
System Property com.gentics.contentnode.db.user
Configuration db.settings.user
Default
1.6.24 NODE_DB_PASSWORD
Description Password for accessing the backend DB
Env NODE_DB_PASSWORD
System Property com.gentics.contentnode.db.password
Configuration db.settings.password
Default
1.6.25 NODE_DB_NAME
Description Name of the backend DB
Env NODE_DB_NAME
System Property com.gentics.contentnode.db.name
Configuration db.settings.name
Default node_utf8
1.6.26 NODE_DB_PARAMETERS
Description Additional JDBC Parameters for accessing the backend DB
Env NODE_DB_PARAMETERS
System Property com.gentics.contentnode.db.parameters
Configuration db.settings.jdbcparameters
Default netTimeoutForStreamingResults=900
1.6.27 NODE_DB_URL
Description JDBC Connection URL for accessing the backend DB
Env NODE_DB_URL
System Property com.gentics.contentnode.db.url
Configuration db.settings.url
Default Will be constructed from NODE_DB_HOST, NODE_DB_PORT, NODE_DB_NAME and NODE_DB_PARAMETERS
1.6.28 NODE_DB_INIT_TIMEOUT
Description Timeout in ms for establishing initial connection to the backen DB, when the CMS is started
Env NODE_DB_INIT_TIMEOUT
System Property com.gentics.contentnode.db.init_timeout
Configuration
Default 60000
1.6.29 ALOHAEDITOR_PATH
Description Path to Aloha Editor (used only in development environments)
Env ALOHAEDITOR_PATH
System Property com.gentics.contentnode.alohaeditor.path
Configuration
Default
1.6.30 ALOHAEDITOR_PLUGINS_PATH
Description Path to Aloha Editor Plugins (used only in development environments)
Env ALOHAEDITOR_PLUGINS_PATH
System Property com.gentics.contentnode.alohaeditor.plugins.path
Configuration
Default
1.6.31 GCNJSAPI_PATH
Description Path to Gentics CMS JS API (used only in development environments)
Env GCNJSAPI_PATH
System Property com.gentics.contentnode.gcnjsapi.path
Configuration
Default

1.7 Disk based cache files

In order to have the cache place the files for disk based caches (normally for GIS and publish cache) at the configured location, it is mandatory to have the cache.ccf file contain the following lines:

cache.ccf

...
jcs.auxiliary.DC.attributes.DiskPath=${com.gentics.contentnode.cache.path}
...
jcs.auxiliary.PUB.attributes.DiskPath=${com.gentics.contentnode.cache.path}
...

2 Changes in directory structure

The directory structure has been flattened and made configurable. The new default values are considered relative to the execution directory of the CMS. If the CMS is running in a container, this will be relative to /cms.

Contents Old directory New default
Configuration files /Node/etc/conf.d conf
File nodelog.yml /Node/tomcat/conf/gentics conf
File cache.ccf /Node/tomcat/conf/gentics conf
UI Configuration files /Node/var/httpd/htdocs/customer-config ui-conf
File license.key /Node/tomcat/conf/gentics keys
Generated private key /Node/tomcat/conf/gentics keys
Uploaded binaries /Node/node/content/dbfiles data/dbfiles
Disk based cache for GIS /Node/tomcat/temp/jcs cache
Disk based cache for Publish Cache /Node/tomcat/temp/pub cache
Publish logs /Node/node/content/log logs
CMS logs /Node/tomcat/logs logs
Statically published content /Node/node/content/publish publish
Statically published GIS Images /Node/node/content/imagestore publish/gis
Devtool packages /Node/node/content/packages packages
Custom libraries /Node/tomcat/shared/lib/custom libs
Content packages /Node/node/content/content-packages content-packages
Scheduler scripts /Node/bin/scheduler-commands scheduler-commands

3 URL Changes

The default port of the CMS has been changed from 80 to 8080.

The URLs to various parts of the CMS have been changed (shortened), and some parts have been removed:

Description Old URL New URL
Old UI and PHP backend /.Node/... Removed
File Servlet /file/... Removed
Aloha Tag Servlet /alohatag/... Removed
Java Parser Invoker /JavaParserInvoker/... Removed
Tidy Servlet /tidy/... Removed
Gentics Image Store /GenticsImageStore/... /GenticsImageStore
Aloha Page Servlet /alohapage/... /alohaeditor/...
Aloha Editor /[build-timestamp]/alohaeditor/... /alohaeditor/[build-timestamp]/...
Gentics CMS JS API /[build-timestamp]/gcnjsapi/... /gcnjsapi/[build-timestamp]/...
REST API /rest/... /rest/...
JMX Monitoring API /jmx/... /jmx/...
Activation Service /activation /activation/...
Keycloak configuration /customer-config/config/keycloak.json /ui-conf/keycloak.json
UI Overrides /customer-config/config/ui-overrides.json /ui-conf/ui-overrides.json
Form Generator Overrides /customer-config/config/config-override.json /ui-conf/config-override.json
Form Editor configuration /customer-config/config/form-editor.json /ui-conf/form-editor.json
UI Custom Script /customer-config/scripts/index.js /ui-conf/index.js
Implementation tool /generic.html /tools/generic.html
Implementation tool /renderpage.html /tools/renderpage.html
Open API (YAML) /openapi.yaml /openapi/openapi.yaml
Open API (JSON) /openapi.json /openapi/openapi.json

4 File Upload Manipulator

Since PHP has been removed from the CMS, it is no longer possible to implement a File Upload Manipulator with PHP scripts that run along with the CMS. Existing PHP scripts that serve as File Upload Manipulator must be migrated to an external service, which can run PHP scripts.

When the container image of the CMS is used, that external service must run in another container and http access between the CMS container and the FUM container must be possible.

5 Removed Features

5.1 XNL

Rendering XNL has been removed. All existing XNL Implementations must be replaced with Velocity Implementations.

5.2 Import/Export

Use the new Content Staging. instead.

5.3 SSO with CAS

Single-Sign-On is now handled by the Keycloak integration

5.4 Activiti Integration

Use the Activiti API directly.

5.5 Auto-Update

See the Gentics infoportal for instructions on how to update Docker, Kubernetes or Linux installations.