OCEE documentation
OCEE documentation

Quick Start

This guide provides a brief overview of how to install and configure the basic components of OCEE. For detailed instructions, please refer to the relevant sections of this documentation.

OCEE consists of multiple features, each requiring separate configuration. Before enabling specific features, you must install the OCEE core:

  • Extract the OCEE Distribution
    Unzip the OCEE distribution archive to a temporary location (not within your OpenCms web application directory).

  • Install the Core Module
    Use the OpenCms Module Manager to install the org.opencms.ocee.base module found in the modules/ folder of the distribution.

  • Copy Library Files
    Copy all *.jar files from the lib/ directory of the distribution to the WEB-INF/lib folder of your OpenCms web application.

  • Restart the Servlet Container
    Restart your servlet container to apply the changes.

Note: The OCEE distribution also includes several configuration files or fragments that will be needed in later setup steps.

One mandatory feature to install is the Subscription Manager, which manages the OCEE license.

  • Update opencms.xml
    Add the license configuration class to your opencms.xml file under the /opencms/configuration/ node:

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

  • Add License File
    Copy the ocee-license.xml file from the OCEE distribution to the ${OPENCMS_HOME}/WEB-INF/config/ directory.

  • Insert License Data
    Open ocee-license.xml and insert your license information (provided by Alkacon via email):

<?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>
  • Restart the Servlet Container
    Restart your servlet container again to apply the license configuration.
Further information about configuration of the subscription manager

The OCEE Accelerator is an optional component, but its use is strongly recommended to improve performance through advanced caching mechanisms.

  • Update opencms.xml
    Add the accelerator configuration class to your opencms.xml file under the /opencms/configuration/ node:

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

  • Copy the Cache Configuration File
    Copy the ocee-cache.xml file from the OCEE distribution to the ${OPENCMS_HOME}/WEB-INF/config/ directory.

  • Update opencms.properties - Driver Sequence
    In the opencms.properties file, locate the "Configuration of the driver manager" section. Modify the driver sequence so that the cache driver is listed first in each cascade. Use the example configuration found in the opencms.properties.part file from 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
  • Add Cache Driver Classes
    Below the "Configuration of the caches" section in opencms.properties (create this section if it doesn't exist), add the cache driver class definitions:
#
# 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
  • Restart the Servlet Container
    After updating the configuration files, restart your servlet container to activate the Accelerator component.

For additional information on configuration options and best practices for the OCEE Accelerator, refer to the Accelerator section in the full documentation.

Further information about configuration and usage of the accelerator

The OCEE LDAP Connector integrates OpenCms with external LDAP directories for user authentication and management. This step is optional but recommended if you need centralized user management.

  • Update opencms.xml
    Add the LDAP configuration class to the <configuration> node in your opencms.xml file:

<configuration>
    ...
    <config class="org.opencms.ocee.ldap.CmsLdapConfiguration"/>
</configuration>
  • Update opencms.properties – Driver Sequence
    In the "Configuration of the driver manager" section, modify the user driver sequence to include the ldap driver.
    If you're also using the OCEE Accelerator, keep the cache driver first in the sequence (not shown in the below minimal setup):
#
# Configuration of the driver manager
###########################################################################
driver.vfs=\
db
driver.project=\
db
driver.user=\
ldap,\
db
driver.history=\
db
  • Add the LDAP Driver Class
    Add a new section titled "Configuration of LDAP user driver" (create it if it doesn’t exist) in the opencms.properties file:
#
# Configuration of LDAP user driver
###########################################################################
ldap.user.driver=org.opencms.ocee.ldap.CmsLdapUserDriver

  • Copy the LDAP Configuration File
    Copy the ocee-ldap.xml file from the OCEE distribution to the ${OPENCMS_HOME}/WEB-INF/config/ directory.

  • Modify the LDAP Configuration File
    Open the ocee-ldap.xml file and configure it to match your LDAP server settings, including server address, authentication details, and user/group mappings.

  • Restart the Servlet Container

    Restart your servlet container to apply the LDAP connector configuration.

For further guidance on configuring LDAP server connections and mapping strategies, please consult the full LDAP Connector documentation section.

Further information about configuration and usage of the LDAP connector

The OCEE Cluster component allows you to run multiple OpenCms instances in a distributed environment. This setup supports high availability and scalability, typically with one workplace server and one or more delivery servers.

In this step, we will focus on setting up the first instance – the workplace server. Configuration of additional cluster servers is described further down in the Quick Start documentation.

  • Update opencms.xml
    Add the cluster configuration class to your opencms.xml file under the <configuration> node:

<configuration>
    ...
    <config class="org.opencms.ocee.cluster.CmsClusterConfiguration"/>
</configuration>
  • Modify opencms-system.xml
    Update the <memorymonitor> to use the cluster-aware implementation:
...
<memorymonitor class="org.opencms.ocee.cluster.CmsClusterMemoryMonitor" >
...

  • Copy the Cluster Configuration File
    Copy the ocee-cluster.xml file from the OCEE distribution to the ${OPENCMS_HOME}/WEB-INF/config/ directory.

  • Configure Cluster Settings
    Edit the ocee-cluster.xml file to define your cluster topology.
    You will need to specify:

    • Cluster node names

    • IP addresses or hostnames of participating servers

    • Role definitions (workplace or delivery)

    Be sure to match the cluster node names with the server names defined in the opencms.properties file for each instance.

  • Restart the Servlet Container
    After applying all configuration changes, restart the servlet container to activate clustering.

For complete instructions on setting up additional servers and configuring communication between nodes, refer to the full OCEE Cluster documentation.

Further information about configuration and usage of the OCEE cluster

The OCEE Replication module enables content replication across multiple OpenCms instances in a cluster environment. It requires a fully configured OCEE Cluster, with the workplace server acting as the replication master.

In this step, we will configure the workplace server. Setup of additional replication targets is covered further down in the Quick Start documentation.

  • Update opencms.xml
    Add the replication configuration class under the <configuration> node:

<configuration>
...
    <config class="org.opencms.ocee.replication.CmsReplicationConfiguration"/>
</configuration>
  • Update opencms-system.xml
    Enable replication support by setting the runtime info class:
<opencms>
<system>
    ...
    <runtimeclasses>
        <runtimeinfo class="org.opencms.ocee.replication.CmsReplicationDbContextFactory"/>
    </runtimeclasses>
    ...
</system>
</opencms>
  • Update opencms.properties – Driver Sequence
    In the "Configuration of the driver manager" section, update the driver chains to include the replication driver. If using the OCEE Accelerator, ensure:
    • cache driver is first (if used)
    • replication driver is in the middle
    • db driver is always last
#
# Configuration of the driver manager
###########################################################################
driver.vfs=\
db
driver.project=\
replication,\
db
driver.user=\
replication,\
db
driver.history=db
  • Add Replication Driver Classes
    Add the following under the "Configuration of the replication drivers" section (create the section if missing):
#
# Configuration of the replication drivers
###########################################################################
replication.project.driver=org.opencms.ocee.replication.CmsReplicationProjectDriver
replication.user.driver=org.opencms.ocee.replication.CmsReplicationUserDriver
  • Declare a New Database Pool
    In the "Declaration of database pools" section, add a new pool name (e.g., replication):
# Declaration of database pools
###########################################################################
db.pools=\
default,\
replication
  • Configure the Replication Database Pool
    Add the "Configuration of the replication pools" section, define the JDBC connection for the replication 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
  • Set SQL Manager Classes
    In the "Configuration of the database driver manager" section, set the appropriate SQL manager for your database type:
#
# 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

  • Replace the class names if using a different DBMS:

    • MS SQL Server: org.opencms.ocee.replication.db.mssql.CmsSqlManager

    • MySQL/MariaDB: org.opencms.ocee.replication.db.mysql.CmsSqlManager

    • Oracle: org.opencms.ocee.replication.db.oracle.CmsSqlManager

    • PostgreSQL: org.opencms.ocee.replication.db.postgresql.CmsSqlManager

  • Copy and configure ocee-replication.xml
    Copy ocee-replication.xml from the distribution to ${OPENCMS_HOME}/WEB-INF/config/ and configure your replication rules, source/target servers, and scheduling options.

    Ensure all server and pool names used here match the definitions from your cluster and opencms.properties configuration.

  • Restart the Servlet Container
    After completing the configuration, restart your servlet container to enable replication support.

For a detailed explanation of replication setups, scheduling options, and target server configuration, consult the full OCEE Replication documentation.

Further information about configuration and usage of the OCEE replication

After configuring the workplace server, you can now set up additional cluster nodes. These servers will join the OpenCms cluster and share cached content, configuration, and (optionally) user sessions.

Quick Deployment: Copy from Workplace Server

To speed up installation, copy the following from the workplace server:

  • The entire /WEB-INF/lib/ folder

  • The following files from /WEB-INF/config/:

    • opencms-modules.xml

    • ocee-license.xml

    • ocee-cache.xml

    • ocee-cluster.xml

These files ensure consistent module registration, licensing, and OCEE configuration across all cluster nodes.

 

  • Configure opencms.xml
    Add the following OCEE configuration classes under the <configuration> node:
<configuration>
...
    <config class="org.opencms.ocee.license.CmsLicenseConfiguration"/>
    <config class="org.opencms.ocee.cache.CmsCacheConfiguration"/>
    <config class="org.opencms.ocee.cluster.CmsClusterConfiguration"/>
</configuration>
  • Configure opencms.properties for OCEE Accelerator
    Just like on the workplace server, add the driver sequences and cache driver classes:
#
# 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
  • Modify opencms-system.xml
    Update the <memorymonitor> to use the cluster-aware implementation:
...
<memorymonitor class="org.opencms.ocee.cluster.CmsClusterMemoryMonitor" >
...

Optional: LDAP & Replication Support on Cluster Nodes

You only need to configure LDAP or Replication on cluster nodes in special cases:

  • LDAP:
    Only required if your website uses OpenCms login and the users are managed in LDAP. If needed, configure it the same way as on the workplace server.

  • Replication:
    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 scale your OpenCms cluster, follow these steps:

  • Clone the Web Application Folder
    Copy the complete web application folder from an existing cluster server to a new machine.

  • Update opencms.properties
    Set a unique server.name for the new node. If using OCEE replication, adjust the database connection for the replication pool if the new server should replicate to a dedicated database.

  • Update ocee-cluster.xml on all nodes
    Add an entry for the new server node. This ensures proper cluster awareness.

  • (Optional) Update ocee-replication.xml
    If the new node needs its own replicated database:

    • Define a new replication target.

    • Configure pool and replication rules accordingly.

After the changes, restart the servlet container on each cluster node to activate the configuration.

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 OCEE is a straightforward process, but it must be done carefully—especially in clustered environments or when upgrading OpenCms itself.

To update your current OCEE installation to a new version:

  • Replace OCEE JAR Files

    • Go to your /WEB-INF/lib/ folder.

    • Replace all existing org.opencms.ocee.*.jar files with the new versions provided in the updated OCEE distribution.

  • Reinstall the OCEE Module

    • Use the OpenCms Module Manager to reinstall the new version of the org.opencms.ocee.base module (located in the modules/ folder of the distribution).

  • Cluster Environment? Do this on all nodes

    • Repeat the steps above on each cluster node.

    • The updated OCEE module configuration must be synchronized across all instances via the OCEE Cluster Manager.

  • Restart Servlet Containers

    • After updating the JARs and modules, restart the servlet container(s) on all instances to apply changes.

When upgrading your OpenCms version, you must also install a compatible version of OCEE. This requires removing the current OCEE installation before running the OpenCms Updater.

Follow these steps:

  • Undo All OCEE Configuration

    In your WEB-INF/config/ folder:

    • You may keep the ocee-*.xml configuration files for reuse.

    • However, you must manually undo any OCEE-related changes in:

      • opencms.xml

      • opencms.properties

      • opencms-system.xml

  • Restart the Servlet Container

    Restart your application server to apply the configuration rollback.

  • Uninstall Old OCEE Modules

    • Open the Module Manager in the OpenCms Workplace.

    • Uninstall all existing OCEE modules.

  • Remove remaining OCEE Libraries

    • Double-check that no org.opencms.ocee.*.jar files remain in /WEB-INF/lib/.

    • If any are present, delete them manually.

  • Run the OpenCms Updater

    Proceed with the OpenCms upgrade using the OpenCms Updater tool.

  • Install New OCEE Version

    After the OpenCms update is complete:

    • Install the new OCEE version that matches your updated OpenCms.

    • Follow all installation steps from this Quick Start Guide to reconfigure OCEE.