Server Migration

This chapter explains what steps need to be taken in order to migrate an existing Gentics CMS installation to a new server.

1 Server migration

1.1 Prerequisites

1.1.1 Source
  • Disable the publishing scheduler tasks to prevent the target system to directly start publishing.
  • Cleanly shutdown the source CMS installation

Note that the commands could vary depending on the distribution of the operating system.


  # On source
  systemctl stop apache
  systemctl stop genticcms
  • Create a MySQL dump from the source server database.

  mysqldump -u root -p node_utf8 > source_node_utf8.sql

1.2 Migration

There are essentially two kinds of migrations. One in which only the content (dbfiles, mysqldump) will be transfered to an existing installation. The other type of migration is a migration which copies the whole node installation from the source server to the target server.

1.3 Content-only

When handling a content-only migration it is very important to ensure that both CMS systems use exactly the same version of Gentics CMS.

  • Make sure that the target CMS installation is shut down (Apache, Tomcat)

The commands could vary depending on the distribution of the server.


  # On target
  systemctl stop apache
  systemctl stop genticcms
  • Transfer the mysql dump and files to the target system

  # On source
  rsync -rav /Node/node/content/dbfiles root@target:/Node/tmp
  rsync -rav /Node/node/content/imagestore root@target:/Node/tmp
  rsync -rav source_node_utf8.sql root@target:/Node/tmp

  # On target
  rm -rf /Node/node/content/dbfiles 
  mv /Node/tmp/dbfiles /Node/node/content/
  chown node: /Node/node/content/dbfiles -R

  rm -rf /Node/node/content/imagestore
  mv /Node/tmp/imagestore /Node/node/content
  chown node: /Node/node/content/imagestore -R
  • Clear all disk-based caches on the target server.

  # On target system
  rm -rf /Node/tomcat/tmp/*
  rm -rf /Node/tomcat/temp/*

Next continue with the database import step

1.4 Full CMS installation

In order to prepare the target server (Cron, Users, Init Scripts, Apache Conf) for the Gentics CMS installation it may be required to install a fresh Gentics CMS installation. This must only be performed if the server did not yet contain a Gentics CMS. Make sure to use a Gentics CMS package file which matches up with the source Gentics CMS major version if you need to perform this step.

  • Make sure that the target CMS installation is shut down (Apache, Tomcat)

The commands could vary depending on the distribution of the server. systemctl stop apache systemctl stop genticcms

  • Backup the used target system license.key.

It is important to use a dedicated license key for each Gentics CMS installation.

  • Copy the Gentics CMS installation files from the source server to the target server.

  # On source system
  rsync -rav /Node root@target:/
  
  # On target system
  # Update the file permissions
  /Node/dist_setperm.sh
  • Clear all disk-based caches on the target server.

  # On target system
  rm -rf /Node/tomcat/tmp/*
  • Ensure that the original license key is restored.

  cp /tmp/original.license.key /Node/tomcat/conf/gentics/license.key
  chown node: /Node/tomcat/conf/gentics/license.key

1.5 Databases

1.5.1 CMS databases

  # 1. Drop the existing database on the target server via:
  # DROP DATABASE node_utf8;

  # 2. Import the source CMS database
  mysql -u root -p node_utf8 < source_node_utf8.sql

You may need to drop existing MySQL stored procedures if you decide to change the previously used MySQL database user. Take a look at the MySQL server migration guide below for more information on this topic. The removed procedures will automatically be recreated during the startup of Gentics CMS.

1.5.2 CR databases (optional)

The imported Gentics CMS database may contain references to Content.Repository databases. You can start the CMS system and check the used connections in the Admin Area (Administration → Content.Admin → ContentRepositories)

You may need to update the server urls. In some cases this could otherwise lead to unforseen content inconsistencies.

1.6 Post migration check

Once you verified that the publising scripts, cr target db and scheduler tasks are setup correctly you can reenable the publishing scheduler task on the target system and invoke a publish process.

You can start the source CMS system once you checked that the publishing process is working as expected.

2 MySQL server migration

In some cases it may be desired to move the MySQL server to a new server or upgrade it to a newer version. The steps below contain infromation on how to deal with that situation. In most other cases these steps can be omitted.

Consider to adapt the memory settings of the MySQL Server before importing the data into the new database server. This will correctly set the logfile size among other settings.

MySQL 5.6.12 – Please note that it is mandatory to disable the sql_mode setting. By default NO_ENGINE_SUBSTITUTION and STRICT_TRANS_TABLES are enabled. Gentics CMS will not function properly when the STRICT_TRANS_TABLES setting is enabled.

Please note that the my.cnf mysqld setting character-set-server must be set to utf8. It is also highly suggested to set the client default-character-set to utf8.

2.1 Configuration files

The node.conf file contains the main database settings.

/Node/etc/node.conf

  $SETTINGS["dbtype"] = "mysql";
  $SETTINGS["db"] = "node_utf8";
  // Adapt this url so that it contains the correct port and the socket file path
  $SETTINGS["server"] = "localhost:3306:/var/run/mysqld/mysqld.sock";
  $SETTINGS["login"] = "node";
  $SETTINGS["pw"] = "YOURPW";
  $SETTINGS["charset"] = "utf8";
  $SETTINGS["jdbcparameters"] = "netTimeoutForStreamingResults=900";

The contentrepository connection properties can be changed later on within the Admin Area of Gentics CMS. (Administration → Content.Admin → ContentRepositories)

2.2 Permissions

The following MySQL permssions are needed:


  mysql> GRANT usage ON *.* to node_cms@HOSTNAME
  mysql> GRANT super ON *.* to node_cms@HOSTNAME
  mysql> GRANT all ON node_utf8.* to node_cms@HOSTNAME
  mysql> GRANT all ON node_utf8_cr.* to node_cms@HOSTNAME

2.3 Changes of the connection settings

The stored procedures/triggers/functions need to be removed when the username and or the used connection ip / hostname changes because those elements contain a reference to the previously used login.

2.4 Dropping of triggers


  mysql> USE node_utf8;
  mysql> SHOW TRIGGERS;
  # Drop each trigger individually via:
  mysql> DROP TRIGGER triggername
  # Verify that all triggers have been deleted
  mysql> SHOW TRIGGERS;

2.5 Creation of triggers

The triggers will be recreated when the user logs in the first time.

2.5.1 Check

  Check that the database triggers were created using the expected definer. (e.g.: 'node_cms@HOSTNAME')
  mysql> SHOW TRIGGERS;