OCEE documentation
OCEE documentation

Quick Start

This page gives an overview of the basic OCEE installation and configuration. For more details, see the corresponding sections in this documentation.

Alkacon OCEE consists of several features. Each of them has to configured individually if you want to use them. But first, you need to install the OCEE core. To do this, perform the following steps:

  • Unzip the OCEE distribution zip somewhere (not in your OpenCms web application)
  • Install the module org.opencms.ocee.base contained in the modules/ folder of the distribution using the OpenCms module manager
  • Copy all the *.jar files from the lib/ folder of the distribution to the WEB-INF/lib folder of your OpenCms web application
  • Restart your servlet container

The OCEE distribution zip contains several configuration files or configuration file fragments that will be used in later installation steps.

A mandatory feature to install is the subscription manager, which is maintining the CEE licence.

Add the license configuration class to the opencms.xml configuration file, adding it below the /opencms/configuration/ node, like this

<configuration>
...
    <config class="org.opencms.ocee.license.CmsLicenseConfiguration"/>
</configuration>

Copy the ocee-license.xml file from the OCEE distribution  to your ${OPENCMS_HOME}/WEB-INF/config/ folder. 

Insert the licence data (customer name and key) that was provided in the mail you received from Alkacon like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE opencms SYSTEM "http://www.alkacon.com/dtd/6.0/ocee-license.dtd">
<opencms>
    <license>
        <name>Alkacon Software GmbH</name>
        <key>207/nAbWRJ2Qe6s53qAzMSpAzp4gIyRH/GWNBUqzqupya7uLbZHN7waOUSgpdZQRJILQrw5A3mpaNF6DUgfrdDon+Lcs671IkK5vhJx2JA7P3OKrqQqzpySR7uYslofmNsToYg==</key>
    </license>
</opencms>

After modifying the configuration files, the servlet container needs to be restarted to enable the changes.

Further information about configuration of the subscription manager

The OCEE Accelerator is no mandatory component, but it is strongly recomment to use.

Add the accelerator configuration class to the opencms.xml configuration file, adding it below the /opencms/configuration/ node, like this

 

<configuration>
...
    <config class="org.opencms.ocee.cache.CmsCacheConfiguration"/>
</configuration>

Copy the ocee-cache.xml file from the OCEE distribution  to your ${OPENCMS_HOME}/WEB-INF/config/ folder. 

Add the new driver sequence in the opencms.properties configuration file, adding it under the  “Configuration of the driver manager” section. You find the example configuration in the opencms.properties.part file of the OCEE distribution:

 

#
# Configuration of the driver manager
###########################################################################
driver.vfs=\
cache,\
db
driver.project=\
cache,\
db
driver.user=\
cache,\
db
driver.history=db
driver.subscription=db

Make sure that the cache driver is always the first driver in the driver cascade

Add the driver classes in the opencms.properties configuration file, adding it under the “Configuration of the caches” section (it could be that this section does not exist in your current configuration file), as follows:

#
# Configuration of the cache drivers
###########################################################################
cache.vfs.driver=org.opencms.ocee.cache.CmsVfsCache
cache.project.driver=org.opencms.ocee.cache.CmsProjectCache
cache.user.driver=org.opencms.ocee.cache.CmsUserCache

After modifying the configuration files, the servlet container needs to be restarted to enable the changes.

Further information about configuration and usage of the accelerator

Add the LDAP configuration class to the opencms.xml configuration file, adding it under the <configuration> node, as follows:

<configuration>
    ...
    <config class="org.opencms.ocee.ldap.CmsLdapConfiguration"/>
</configuration>

Add the new driver sequence in the opencms.properties configuration file, adding it under the “Configuration of the driver manager” section, as follows.

If you are also using the OCEE Accelerator, the accelerator driver should remain the first in the sequence. 

#
# Configuration of the driver manager
###########################################################################
driver.vfs=\
db
driver.project=\
db
driver.user=\
ldap,\
db
driver.history=\
db

Add the driver class in the opencms.properties configuration file, adding it under the “Configuration of LDAP user driver” section (it could be that this section does not exists in your current configuration file), as follows:

#
# Configuration of LDAP user driver
###########################################################################
ldap.user.driver=org.opencms.ocee.ldap.CmsLdapUserDriver

Copy the ocee-ldap.xml file from the OCEE distribution  to your ${OPENCMS_HOME}/WEB-INF/config/ folder. 

Please note that you have to modify this configuration and add your LDAP server configuration and users/groups mappings. See the full documentation for the LDAP connector below.

After modifying the configuration files, the servlet container needs to be restarted to enable the changes.

Further information about configuration and usage of the LDAP connector

To configure an OpenCms Cluster you will need two or more OpenCms instances installed on separated machines. We will first focus on installing the first instance, the editor server.
Installation of the other cluster server later described here

Add the cluster configuration class to the opencms.xml configuration file, adding it under the <configuration> node, as follows:

<configuration>
    ...
    <config class="org.opencms.ocee.cluster.CmsClusterConfiguration"/>
</configuration>

In the opencms-system.xml configuration file, change the memory monitor class as follows:

...
<memorymonitor class="org.opencms.ocee.cluster.CmsClusterMemoryMonitor" >
...

Copy the ocee-cluster.xml file from the OCEE distribution  to your ${OPENCMS_HOME}/WEB-INF/config/ folder. 

Please note that you have to modify this configuration and add your cluster server configuration. See the full documentation for the OCEE cluster below.

Make sure that you use the same names for your cluster nodes that are defined as server names in the opencms.properties file of the corresponding server.

After modifying the configuration files, the servlet container needs to be restarted to enable the changes.

Further information about configuration and usage of the OCEE cluster

The OCEE Replicator needs an installed and working OCEE Cluster manager.  How to configure the cluster can be read in the respective documentation. You will need to configure  your replication master instance as the cluster workplace server.

We will first focus on installing the first instance, the workplace server. Installation of the other cluster server later described here

Add the cluster configuration class to the opencms.xml configuration file, adding it under the <configuration> node, as follows:

<configuration>
...
    <config class="org.opencms.ocee.replication.CmsReplicationConfiguration"/>
</configuration>

In the opencms-system.xml, activate replication support by modifying the runtime info class, under the <runtimeclasses> node, as follows:

<opencms>
<system>
    ...
    <runtimeclasses>
        <runtimeinfo class="org.opencms.ocee.replication.CmsReplicationDbContextFactory"/>
    </runtimeclasses>
    ...
</system>
</opencms>

Add the new driver sequence in the opencms.properties configuration file, adding it under the “Configuration of the driver manager” section, as follows.

If you are using additional drivers (like cache or LDAP), please take care that the first one in every sequence is the cache driver, and the last driver the db driver.

#
# Configuration of the driver manager
###########################################################################
driver.vfs=\
db
driver.project=\
replication,\
db
driver.user=\
replication,\
db
driver.history=db

Add the driver classes under the “Configuration of the replication drivers” section (it could be that this section does not exist in your current configuration file), as follows:

#
# Configuration of the replication drivers
###########################################################################
replication.project.driver=org.opencms.ocee.replication.CmsReplicationProjectDriver
replication.user.driver=org.opencms.ocee.replication.CmsReplicationUserDriver

Add a database pool for the replication in the opencms.properties configuration file.

For this you have to create a new pool and give it a unique new name, let’s say replication , and add it to the “Declaration of database pools” section, as follows:

# Declaration of database pools
###########################################################################
db.pools=\
default,\
replication

Add a database pool configuration section for your new pool replication under the “Configuration of the replication pools” section (it could be that this section does not exist in your current configuration file), as follows.

This is an example for a MySql/MariaDB database:

#
# Configuration of the replication pools
###########################################################################
db.pool.replication.jdbcDriver=org.mariadb.jdbc.Driver
db.pool.replication.jdbcUrl=jdbc:mariadb://localhost:3306/opencmsreplication
db.pool.replication.jdbcUrl.params=?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC
db.pool.replication.user=USERNAME
db.pool.replication.password=PASSWORD
db.pool.replication.poolUrl=opencms:replication

Configure the replication support for each data access driver except for the subscription driver by editing the opencms.properties configuration file under the “Configuration of the database driver manager” section, setting the SQL Manager classes to the right one for your database provider, in this example for MySql/MariaDB:

#
# Configuration of the database driver manager
###########################################################################
...
db.vfs.sqlmanager=org.opencms.ocee.replication.db.mysql.CmsSqlManager
...
db.project.sqlmanager=org.opencms.ocee.replication.db.mysql.CmsSqlManager
...
db.user.sqlmanager=org.opencms.ocee.replication.db.mysql.CmsSqlManager
...
db.history.sqlmanager=org.opencms.ocee.replication.db.mysql.CmsSqlManager

You have to use the correct SQL manager for your db provider in the 'Configuration of the database driver manager' section:

  • MS SQL Server: org.opencms.ocee.replication.db.mssql.CmsSqlManager
  • MySql:  org.opencms.ocee.replication.db.mysql.CmsSqlManager
  • Oracle: org.opencms.ocee.replication.db.oracle.CmsSqlManager
  • Postgresql: org.opencms.ocee.replication.db.oracle.CmsSqlManager

 

Configure the actual replications in ocee-replication.xml. You can find the  available configuration options here.

Also see the full documentation for the OCEE Replication below.

Make sure that the server and pool names in the configurarion match the ones from the cluser configuration and opencms.properties.

After modifying the configuration files, the servlet container needs to be restarted to enable the changes.

Further information about configuration and usage of the OCEE replication

The fastest way to install OCEE on the Cluster servers is copying several compontens from the workplace server:

  • The /WEB-INF/lib folder
  • The following configuration files from the WEB-INF/ config folder :
    • opencms-modules.xml
    • ocee-license.xml
    • ocee-cache.xml
    • ocee-cluster.xml

Add the following to the opencms.xml configuration:

<configuration>
...
    <config class="org.opencms.ocee.license.CmsLicenseConfiguration"/>
    <config class="org.opencms.ocee.cache.CmsCacheConfiguration"/>
    <config class="org.opencms.ocee.cluster.CmsClusterConfiguration"/>
</configuration>

The OCEE accelerator has to be configured in the opencms.properties the same way as it was done on the workplace server.

#
# Configuration of the driver manager
###########################################################################
driver.vfs=\
cache,\
db
driver.project=\
cache,\
db
driver.user=\
cache,\
db
driver.history=db
driver.subscription=db
#
# Configuration of the cache drivers
###########################################################################
cache.vfs.driver=org.opencms.ocee.cache.CmsVfsCache
cache.project.driver=org.opencms.ocee.cache.CmsProjectCache
cache.user.driver=org.opencms.ocee.cache.CmsUserCache

In the opencms-system.xml configuration file, change the memory monitor class as follows:

...
<memorymonitor class="org.opencms.ocee.cluster.CmsClusterMemoryMonitor" >
...

Usually, the OCEE LDAP and Replication are not required on the cluster servers. This is only required for special use-cases:

  • If you have a login function on your website in OpenCms and the users who log in there are adminsitrated in LDAP, then you need the OCEE LDAP configured on the cluster server.
    The configuration is made the same way as on the workplace server.
  • If user data can be modified on the cluster server and you use OCEE replication, you need to configure the user backward replication. Please see here for more information.

To add additional cluster nodes to your cluster, the easiest way is to simply copy the webapplication folder of your first cluster server to the new instance.

Make sure that you adjust the opencms.properties on the new system to set the unique server.name property and optinally set the databse connection to the correct database if you use OCEE replication.

If a new, additional node is added to your cluster, the ocee-cluster.xml has to be extended with the new node on all of your  instances.

When using OCEE replication, it also might be required to add a new replication to the ocee-replication.xml if the new node should have its own replicated database.

In order to activate your OCEE installation, you need to get a valid production subscription key. When OCEE is installed for the first time, you usually have an evaluation or a provisional subscription key which is OpenCms instance independent, but valid for a restricted time only. To obtain a production subscription key, you must send the activation key to Alkacon Software. You will then receive the production license key for this activation key.

Please note  that we can not generate a production key without the activation key.

The activation key is displayed in the OCEE Subscription app in the workplace. It is also written to the servlet container log file.

Please send the OCEE activation key to opencms-support@alkacon.com.
For more details about the OCEE licensing mechanism, see the Subscription Manager documentation.

Updating an exising OCEE instalaltion is easy, you have to replace all org.opencms.ocee.*.jar files in the /WEB-INF/lib folder and reinstall the provided verison of hte OCEE module.

In a cluster, the org.opencms.ocee.*.jar  files have to be replaced on all instances. The module configuration of the OCEE module needs to be transferred to the other instances via the OCEE cluster manager

If you want to update your OpenCms installation to a newser version, you will also need a new version of OCEE which works with the new updated OpenCms.

Using the OpenCms Updater, it is mandatory that you remove your OCEE installation first before running the uptater. This menas you have to

  • Undo all OCEE configuration steps in your WEB-INF/config folder. You can keep the ocee-*.xml config files, but you need ot undo the changes to opencms.xml, opencms.properties and opencms-system.xml
  • Restart the servlet container and uninstall all old OCEE modules using the module manager in the OpenCms workplace
  • Double check whether the WEB-INF/lib folder contains any of the org.opencms.ocee.*.jar  files, and if so, remove them.

After the OpenCms Updater has run, you need to install the new version of OCEE.