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