Installing Gentics CMS

This page described what steps are needed to install Gentics CMS.

1 Pre Requirements

  • System Requirements
  • All commands have to be executed using the root user.
  • Make sure the locale en_US.UTF-8 is generated
  • Make sure your timezone is correctly set (eg. to CET)

1.1 Download the package

1.1.1 Debian
1.1.2 Redhat / Suse
  • Download the .tar.gz archive from maven.gentics.com and extract it. Please extract the package tar.gz file on your server to a location of your choice. This guide will substitute the package directory in that location with PACKAGEDIR.

  cd /var/tmp
  tar xfvz contentnode-package-5.16.0.tar.gz
  export PACKAGEDIR=/var/tmp/package

1.2 Database server

When using the debian package installer with MariaDB, this step will be done automatically.

Please install a compatible MySQL Server on your system. We suggest a installation of MariaDB on the same server that will host Gentics CMS.

The following mysql permissions 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;
  mysql> GRANT all ON node_utf8_todo.* to node_cms@HOSTNAME;

The following mysql custom settings are mandatory. (MariaDB / MySQL 5.7)


[mysqld]
  innodb_flush_log_at_trx_commit = 2
  character-set-server           = utf8
  character_set_client           = utf8
  character-set-filesystem       = utf8
  
  sql_mode                       = ""
  innodb                         = FORCE
  default-storage-engine         = InnoDB
  max_allowed_packet             = 256M
  collation_server               = utf8_general_ci

[client]
  default-character-set          = utf8

2 Installation / Migration

You can either do a new Gentics CMS installation (explained under “Installation”) or migrate an existing Gentics CMS installation to use the new Gentics CMS package that uses the system distribution Apache with PHP (explained under “Migrating”).

If you are updating from 5.15.* or older, you should first execute the update to 5.16.* or 5.17.* with Autoupdate and then do the package migration (don’t update to 5.18.* directly). If you are updating from 5.16.* or 5.17.*, you have to do the package migration first and then execute the update with Autoupdate.

The in-depth installation and migration guide can be found for these distributions:

2.1 Final recommendations and suggestions

It is mandatory to adjust the memory settings for your installation. Not doing so can lead to performance issues.

It’s considered best practice to use hyphens (-) instead of underscores (_) in URL’s. For new installations you should add these settings to your configuration.

2.2 Maximum connections between Apache and Tomcat

The default configuration of Tomcat allows only 200 maximum connections for the AJP connector. The number of maximum clients used by Apache must not exceed this limit. If it does, this may cause some requests to fail (after running in a timeout). Please adjust the MaxThreads of the Tomcat server.xml according to the MaxClients settings in the Apache configuration. The max connections accepted by the Tomcat must be equal or higher the max connections accepted by the Apache web server.

2.3 Securing AJP connector

The AJP connector used for accessing Tomcat can be secured in two ways:

  1. Binding to localhost
  2. Using a shared secret between AJP connector and mod_proxy in Apache webserver (not used by default)

It is recommended to at least set the address binding to localhost:

/Node/tomcat/conf/server.xml

...
<Connector port="42889" protocol="AJP/1.3" URIEncoding="UTF-8" redirectPort="8443"
  maxthreads="..." secretRequired="false" address="localhost" />
...

Naming of the configuration parameters of the AJP connector changed with Tomcat 7.0.100. See the changelog for details.

2.4 Apache Tomcat startup behaviour

The default startup behaviour of Apache Tomcat is to start even if the CMS Webapp cannot be started.

By setting the JVM parameter


  -Dcom.gentics.contentnode.exitonstartuperror=true

this can be changed. If the webapp fails to start (e.g. because it cannot load the configuration or access to the backend DB is not possible during startup), the JVM will be terminated and Apache Tomcat will fail to start.

2.5 Notable utilities and software

  • munin – A very versatile monitoring software that helps investigating system performance issues.
  • nagios / icinga – Another monitoring software that helps you monitoring the overall health status of your installation.
  • backup – A backup solution should be installed that created backups of your /Node directory and the used databases. We recommend also the backup of Content.Repositories
  • regular updates – Regular distribution updates are mandatory to keep your installation secure

2.6 Troubleshooting

There are various logs which yield some information.

  • The webserver just states ‘Forbidden’

Most likely the directory permissions are not correct. Check the apache error log.

  • SGB when opening ‘.Node/’

Take a look in /Node/node/log/halt.log. Something might be wrong with the MySQL connection. Check the node.conf and your mysql users. There might be a anonymous user which prevents access for the CMS database user.

  • The tree and the start page show SGB’s directly after login.

The Apache Tomcat server was not able to startup successfully. Try to load the Tomcat settings via:


  curl http://localhost/.Node/?do=24

You should get a list of properties. When this fails you have an error on the apache, php side. Otherwise something is wrong with your Apache Tomcat. Check the Apache Tomcat gentics.log and catalina.log in those cases. Keep in mind that the Apache Tomcat configuration is loaded during startup. You may just have to restart the Apache Tomcat when you just fixed an apache error. The startup of the Apache Tomcat may take a few seconds.

2.7 Resetting the database

The database of the Gentics CMS can by reset anytime, by dropping & recreating the database and running the setup-database.php script:


mysql> DROP database node_utf8;
mysql> CREATE database node_utf8;
rm -R /Node/node/content/dbfiles/* # Delete all CMS files
rm -R /Node/tomcat/temp/pub/* # Clear the publish cache
sudo -u node php /Node/.node/setup-database.php

This only works if the directory /Node/etc/dumps exists. If it does not exist you have to download the .tar.gz file from https://maven.gentics.com/maven2/com/gentics/contentnode-package/ and unpack the archive to /Node/etc/dumps. Use the username “gcn” and your license key to authenticate for the downloads.


CMS_VERSION="YOUR_VERSION"
cd /Node/tmp
wget --http-user=gcn --ask-password https://maven.gentics.com/maven2/com/gentics/contentnode-package/$CMS_VERSION/contentnode-package-$CMS_VERSION.tar.gz
tar xvfz contentnode-package-$CMS_VERSION.tar.gz
sudo -u node cp -R package/Node/etc/dumps /Node/etc/dumps
rm /Node/tmp/contentnode-package-$CMS_VERSION.tar.gz

2.8 Custom start/stop scripts

If a service managing system (like systemd) is used to start and stop the CMS, the start and stop scripts should be configured in the configuration. The configured scripts will be used to start/stop the Apache Tomcat during an autoupdate process.

The following example assumes, that

  • The service genticscms is configured to start/stop the GCMS Tomcat with /Node/bin/nodectl start and /Node/bin/nodectl stop
  • User node has permission to execute the commands (via sudo)
/Node/etc/conf.d/*.conf

$TOMCAT_START_CMD = "sudo service start genticscms";
$TOMCAT_STOP_CMD = "sudo service stop genticscms";