Installing Gentics Content.Node

This page described what steps are needed to install Gentics Content.Node.

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)
  • Correctly installed Oracle JDK

1.1 Initial Steps

  • Download the contentnode-package 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.

Please use the username gcn and your license key to authenticate for the downloads.


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

1.2 MySQL Server

Please install a compatible MySQL Server on your system. We suggest a installation of MySQL Server 5.6.2+ (64Bit) on the same server that will host Gentics Content.Node.

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. (MySQL 5.5 / 5.6)


[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_connection           = utf8_general_ci
  collation_database             = utf8_general_ci
  collation_server               = utf8_general_ci

[client]
  default-character-set          = utf8

1.3 Installation / Migration

You can either do a new Gentics Content.Node installation (explained under “Installation”) or migrate an existing GCN installation to use the new GCN 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:

These guides do not cover the installation of Java. It is mandatory that the environment variable JAVA_HOME points to your Oracle JDK.

1.4 Final recommendations and suggestions

It is highly recommened to adjust the memory settings for your installation.

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

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

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

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

1.4.5 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