Migration from CMP 7.x to CMP 8.x

Table of Contents
 

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:

  • Migrate the configuration (from PHP-style to YML-style)
  • Change configuration options, that have been renamed
  • Move files to new locations
  • Adapt URLs for accessing the CMS via HTTP if necessary

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.

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).

Manual transformation of configuration settings

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

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

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

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

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):

HTTP_PORT

Description Http Port of the CMS
Env HTTP_PORT
System Property com.gentics.contentnode.http.port
Configuration server.port
Default 8080

CONF_PATH

Description Path to configuration files
Env CONF_PATH
System Property com.gentics.contentnode.config.path
Configuration
Default conf

DBFILES_PATH

Description Path to binary files
Env DBFILES_PATH
System Property com.gentics.contentnode.dbfiles.path
Configuration config.dbfiles
Default data/dbfiles

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

LICENSEKEY

Description Path to license key file
Env LICENSEKEY
System Property com.gentics.contentnode.license-key.path
Configuration
Default

KEYS_PATH

Description Path to keys directory
Env KEYS_PATH
System Property com.gentics.contentnode.keys.path
Configuration
Default keys

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

CACHE_PATH

Description Path to cache files
Env CACHE_PATH
System Property com.gentics.contentnode.cache.path
Configuration
Default cache

LOGS_PATH

Description Path to logs
Env LOGS_PATH
System Property com.gentics.contentnode.logs.path
Configuration
Default logs

PUBLISH_PATH

Description Path to statically published files
Env PUBLISH_PATH
System Property com.gentics.contentnode.publish.path
Configuration
Default publish

GIS_PATH

Description Path to statically published GIS files
Env GIS_PATH
System Property com.gentics.contentnode.gis.path
Configuration
Default PUBLISH_PATH/gis

PACKAGES_PATH

Description Path to the directory containing the devtool packages
Env PACKAGES_PATH
System Property com.gentics.contentnode.packages.path
Configuration
Default packages

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ALOHAEDITOR_PATH

Description Path to Aloha Editor (used only in development environments)
Env ALOHAEDITOR_PATH
System Property com.gentics.contentnode.alohaeditor.path
Configuration
Default

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

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

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}
...

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

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

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.

Removed Features

XNL

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

Import/Export

Use the new Content Staging. instead.

SSO with CAS

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

Activiti Integration

Use the Activiti API directly.

Auto-Update

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