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:

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

Manual transformation of configuration settings

Enabling of features

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

$FEATURE["wastebin"] = true;

 In the new format, this is done with:

feature:
  wastebin: true

Database Access

PHP-style:

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

 New format and configuration parameters:

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:

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

 New format:

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:

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

New format:

config
  loadbalancing:
    threadlimit: 2
 
velocity:
  resource.loader: "string,file"

Configuration changes

Some configuration parameters have been renamed or 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

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:

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

CONF_PATH

DBFILES_PATH

CONF_FILES

LICENSEKEY

KEYS_PATH

CACHE_CONFIG_PATH

CACHE_PATH

LOGS_PATH

PUBLISH_PATH

GIS_PATH

PACKAGES_PATH

CONTENT_PACKAGES_PATH

SCHEDULER_COMNANDS_PATH

STATIC_SERVE_LIST

UI_CONF_PATH

TMP_PATH

NODE_USER_PASSWORD

NODE_DB_DRIVER_CLASS

NODE_DB_HOST

NODE_DB_PORT

NODE_DB_USER

NODE_DB_PASSWORD

NODE_DB_NAME

NODE_DB_PARAMETERS

NODE_DB_URL

NODE_DB_INIT_TIMEOUT

ALOHAEDITOR_PATH

ALOHAEDITOR_PLUGINS_PATH

GCNJSAPI_PATH

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:

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

URL Changes

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

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.