Introduction

The present guide is addressed to administrators who want to install IOM 2.12 in their Linux based infrastructure. It enables them to understand what artifacts are contained in the IOM 2.12 delivery and how they can be installed, configured and deployed.

The document describes how to install IOM 2.12.

For a technical overview of typical installation scenarios please see references.

Glossary

References

• System Requirements - Intershop Order Management
• Guide - IOM Database Migration (2.0 - 2.17)
• Overview - IOM 2.11 - 2.12 Migration
• Guide - Intershop Order Management - Technical Overview
• Guide - IOM Watchdog 2.2 - 2.11

1.3 Additional References

• Concept - IOM Customer E-Mails
• JSON Web Tokens
• JSON Web Algorithms (JWA) | 3.2. HMAC with SHA-2 Functions
• WildFly
• PostgreSQL 10

Prerequisites

Java Development Kit

The WildFly application server hosting and running IOM requires an installed Java development kit (JDK) of at least version 11.

The JAVA_HOME global environment variable has to point to the installation directory of the JDK.

Mail Server

The IOM requires an existing mail server that processes internal and external e-mails sent from IOM via the SMTP protocol.

Also server host and port need to be known for later configuration.

PostgreSQL Server

The IOM requires a PostgreSQL database hosted by a PostgreSQL database server and can reside on its own host.

To make the database server fit for IOM, certain configuration steps in a standard installation are necessary. For setup and initialization steps please refer to section Database Setup and Initialization.

Support

Intershop does not offer PostgreSQL support further than general recommendations for its use as relational database for the IOM.

A list of companies offering professional Postgres support can be found at PostgreSQL: Professional Services.

Also the PostgreSQL community has some excellent mailing lists, pgsql-general being the most active, see PostgreSQL: PostgreSQL Mailing List Archives.

Operating System

The IOM only supports PostgreSQL servers hosted on a Linux based OS.

Version

We recommend PostgresSQL 10. The IOM version 2.12 is also compatible with PostgreSQL 9.5+

Definition of Properties

The IOM uses four major property files which are explained below.

Installation Properties

The local environment of IOM is defined in $OMS_ETC/installation.properties.

installation.properties defines shell variables, which are read by $OMS_HOME/bin/set_env.sh to provide the environment for all scripts and programs belonging to the IOM system.

$OMS_HOME/bin/set_env.sh provides the content of installation.properties as simple shell variables. Additionally, it adds some exported variables, e.g., PATH and some variables required by 3^rd party programs (e.g., the content of JBOSS_JAVA_OPTS will be exported as JAVA_OPTS to be available for standalone.sh).

Cluster Properties

Cluster properties are WildFly system properties, which define the machine independent configuration of an IOM cluster.

These properties are located in $OMS_ETC/cluster.properties.

PostgreSQL related properties are read by set_env.sh and exported as environment variables.

Adjust cluster.properties to the real values, used by your OMS cluster. For example, you have to enter the access-information for the database, in order to enable the IOM application server, to access the database.

Deployment Properties

Deployment properties define which artifacts of the IOM should be deployed to the WildFly application server.

The properties are located in $OMS_ETC/deployment.cluster.properties. The order of entries within this .properties file is important, it reflects the order of deployments.

The table below shows the entries in $OMS_ETC/deployment.cluster.properties:

System Properties

System properties are defined in $OMS_ETC/system.std.cluster.properties. This file contains Wildfly specific configuration settings. Mostly there is no need to adapt any properties defined in this file, without one exception: the webservices subsystem of Wildfly is responsible for delivery of wsdl files. For correct creation of links within wsdl-files, a proper configuration of this subsystem is required.

Adjust the following properties in system.std.cluster.properties to get properly working wsdl-requests.

Database Setup and Initialization

User

Define a dedicated OS user for the PostgreSQL service. (referred to as the "postgres OS user" in following descriptions)

Cluster Initialization

Data Directory

The PostgreSQL data directory contains all of the data files for the database. The variable PGDATA is used to reference this directory. It must be prepared prior to the initialization and belongs exclusively to the postgres OS user.

You should not use this directory for private data, nor add symbolic links to it. But you will probably want an extra file system built on RAID backed up by battery. Just make sure, not to use its root folder for the data directory and have the major version within the path.

This will facilitate maintenance and Postgres major upgrades, e.g., /iomdata/pg_9.6/data.

This directory must belong to the postgres OS user.

# as root
mkdir /iomdata/pg_10/data
chown <postgres OS user>:<group> /iomdata/pg_10/data

# as the postgres OS user
# add PGDATA=/iomdata/pg_10/data to the user environment

Initialization (initdb)

The initdb of the standard installation process needs special consideration to work on one of the IOM's databases. Initdb will create a new PostgreSQL database cluster and its superuser, see PostgreSQL 10 | initdb.

It must be called as the postgres OS user.

There are a few options to choose from during a Postgres initialization for IOM:

1. Consider using data-checksums (PostgreSQL 10 | initdb | --data-checksums).

2. Make sure to use an UTF8 encoding. Depending on your operating system, you may need to replace the string "UTF8" with "UTF-8" (all places).

   Note

   No change of encoding
   This parameter cannot be changed after the cluster initialization.

   The command to perform initdb may change according to the OS, the Postgres version and to the way you did install it.
   For YUM installations refer to YUM_Installation.
   
   Examples:

   Example

   # Postgres 10, YUM installation on Red Hat 7
   # for more info type /usr/pgsql-10/bin/postgresql-10-setup --help 
   
   # as root
   export PGSETUP_INITDB_OPTIONS="--encoding=UTF8 --locale=en_US.UTF-8 --data-checksums -U postgres -W"
   /usr/pgsql-10/bin/postgresql-10-setup initdb postgresql-10
   
   # without YUM, as root
   ...../pgsql-10/bin/initdb --encoding UTF8 --locale=en_US.UTF-8 --data-checksums -D /iomdata/pg_10/data -U postgres -W
   

Further Recommendations

Client Authentication

The access permissions must be defined in $PGDATA/pg_hba.conf.

Use MD5 as auth-method to prevent passwords to be sent in cleartext across the connection.

You cannot use ident for TCP/IP connections, otherwise the JDBC driver connection from IOM to the database will not work. See PostgreSQL 10 | Chapter 20. Client Authentication for details.

Database Server Configuration

To achieve best performances, almost all of the data (tables and indexes) required for the ongoing work load should be able to reside within the file system cache. Monitoring the I/O activity will help to identify insufficient memory resources.

The IOM is built with Hibernate as API between the application logic and the database. This results mainly in a strong OLTP activity, with a large number of tiny SQL statements. Larger statements occur during import/export jobs and for some OMT search requests.

The following main parameters in $PGDATA/postgresql.conf should be adapted, see PostgreSQL 10 | Chapter 19. Server Configuration.

You can consider PGConfig 2.0 as guideline (using the OLTP Model).

Some aspects of data reliability are discussed here PostgreSQL 10 | Chapter 30. Reliability and the Write-Ahead Log. Understanding VACUUM is also essential when configuring/monitoring Postgres, see PostgreSQL 10 | Chapter 24. Routine Database Maintenance Tasks.

Create User and Database

The following steps describe the setup of a new database.

To perform the next steps, you need to be able to use the psql command and be able to access the database server via its superuser (usually postgres).

su - <postgres OS user>
# set variables
IS_OMS_DB_HOST=<first host from is.oms.db.hostlist>
IS_OMS_DB_PORT=<port of first host from is.oms.db.hostlist>
 
# connect to the database server as the super user
psql -U postgres -h $IS_OMS_DB_HOST -p $IS_OMS_DB_PORT -d postgres

Create User

IOM connects with its own dedicated database user.

1. Create user:

   Create user

   -- create user 
   CREATE USER "<value of your is.oms.db.user>" PASSWORD '<value of your is.oms.db.pass>';

Dedicated Tablespace (Optional)

The database initialization dump does not expect a given tablespace, all objects will be placed in the default users tablespace. When your data directory is located on an adequate file system, you can keep the Postgres default tablespace which is located in $PGDATA/base. If you want to define a dedicated tablespace (i.e., on a dedicated file system), you should:

1. Set it as default for the user and for the database prior to use the provided initialization dump (provided it has been created):

   Default tablespace

   -- set default table space
   ALTER USER "<value of your is.oms.db.user>" SET default_tablespace = 'tblspc_iom';

Also see Postgres table spaces: https://www.postgresql.org/docs/10/static/sql-createtablespace.html

Create Database

IOM uses its own dedicated database.

1. Create the database:

   Create database

   -- create database
   CREATE DATABASE "<value of your is.oms.db.name>"
     WITH OWNER = "<value of your is.oms.db.user>"
      ENCODING = 'UTF8'         
      TABLESPACE = pg_default   -- or your dedicated tablespace 
      LC_COLLATE = 'en_US.UTF-8' 
      LC_CTYPE = 'en_US.UTF-8'   
      CONNECTION LIMIT = -1; 

2. Set database search_path:

   Set search path

   -- set search_path
   ALTER DATABASE "<value of your is.oms.db.name>" SET search_path = customer, oms, omt, product, system, admin;

3. Exit the psql console:

   Exit console

   -- exit console
   postgres=# \q

Installation of IOM

Preparation of Operating System and File System

Create OS User and Group on the Host

Intershop strongly recommends to create a dedicated group and user for the IOM installation on the host system. It is recommended to place the users home directory outside the IOM installation. The following script uses the same value for user name and group name:

# as root set variables
# default: oms
# use "oms" if you do not want to customize the installation layout
OMS_USER=<name of user to own and run IOM>
 
# use "/home/$OMS_USER" as home-directory
OMS_USER_HOME=<home directory of OMS user>
 
# add group
groupadd $OMS_USER

# add user
# users home is created at default location
useradd -g $OMS_USER -d $OMS_USER_HOME -m $OMS_USER

# set password
passwd $OMS_USER

Create OMS Home Directory

1. Log in as root.

2. Create directory $OMS_HOME, set owner and group.

   Create $OMS_HOME, set owner and group

   # as root
   # use "/opt/$OMS_USER.$OMS_SERVER_TYPE" if you do not want to customize the installation layout
   OMS_HOME=<installation directory of IOM>
    
   mkdir -p $OMS_HOME
   chown $OMS_USER:$OMS_USER $OMS_HOME

Extract the Release Package

1. Log in as $OMS_USER. 

2. Place and extract the IOM release package in $OMS_HOME.

   Extract package

   # as $OMS_USER at directory $OMS_HOME
   # extract the IOM release package
   tar -xvzf IOM-2.12.0.0.tgz

   This creates the main directories: etc, var, bin, lib, application etc.

Edit Installation Properties

For the following tasks the local environment of IOM has to be defined in $OMS_HOME/etc/installation.properties. See installation.properties for more information.

Distribute the Release Package Contents

According to the Linux File System Hierarchy Standard, OMS installation will be distributed on different file systems. The variable $OMS_VAR and the command line switch --etc of integrate.sh define the directories, where to place the according parts of OMS. There is no need to change the default values, except you want to adapt the installation layout to your own needs.

1. Edit etc/installation.properties as $OMS_USER if you want to adapt the installation layout to your own needs.
   You do not need to make any changes at the moment, if you want to use the default layout.
   1. Change OMS_USER to the name of the user, who should own and run IOM.
   2. Change OMS_HOME to the name of the directory, where the IOM software has been placed.
   3. Change OMS_VAR to the name of the directory, where to place var-data of IOM.
   4. Change OMS_SHARE to the name of the directory, where to place shared data of IOM.
   5. Change OMS_LOG to the name of the directory, where to place log data of IOM.

2. Prepare the directories $OMS_SHARE, $OMS_VAR, $OMS_LOG and $ETC_TARGET before distributing OMS to these locations. Set the placeholders to the values defined in installation.properties.

3. As the manual describes the setup process of a single IOM machine, $OMS_SHARE must not be mounted to a real shared file-system. For this kind of installation, a local directory is fully sufficient. In this case, the health-check of the shared file-system must be disabled (see description of property is.oms.sharedfs.healthcheck above).

   Setup user and directories

   # as root at $OMS_HOME
    
   # read installation.properties
   . etc/installation.properties
    
   # use "/etc/opt/$OMS_USER.$OMS_SERVER_TYPE" if you do not want to customize the installation layout
   ETC_TARGET=<directory, where to place etc-data>
   
   # prepare the directories 
   mkdir -p "$ETC_TARGET" 
   chown $OMS_USER:$OMS_USER "$ETC_TARGET" 
   mkdir -p "$OMS_VAR" 
   chown $OMS_USER:$OMS_USER "$OMS_VAR"
   mkdir -p "$OMS_LOG"
   chown $OMS_USER:$OMS_USER "$OMS_LOG"
   mkdir -p "$OMS_SHARE" 
   chown $OMS_USER:$OMS_USER "$OMS_SHARE"

4. Distribute the release package parts by running the integrate.sh script.

   Execute integrate.sh

   # as $OMS_USER at $OMS_HOME
    
   # set variable
   # use "/etc/opt/$OMS_USER.$OMS_SERVER_TYPE" if you do not want to customize the installation layout
   ETC_TARGET=<directory, where to place etc-data>
    
   # copy etc- and var-data to configured locations
   bin/integrate.sh --etc="$ETC_TARGET"

   This will copy the relevant parts to the target directory, defined by the --etc=... command line parameter and $OMS_VAR as defined in installation.properties. It also creates symlinks from $OMS_HOME/etc -> $ETC as well as from $OMS_HOME/var -> $OMS_VAR.

5. Afterwards, check the newly created symlinks in $OMS_HOME directory and delete the temporary directory ETC.VAR.SRC.*, which contains backups of etc- and var-directories.

Initialize Database with Dump

Import the initial dump for IOM that will contain the basic necessary database configuration. This dump can be found in the IOM delivery package at $OMS_HOME/postgres/dumps.

1. Edit etc/cluster.properties as $OMS_USER if you do not want to use the default PostgreSQL configuration. If you want to use a PostgreSQL database at localhost, which was created with default configuration, you do not need to make any changes at the moment,

   1. Change /system-property=is.oms.db.hostlist to the hostname or IP and port of your PostgreSQL database.
   2. Change /system-property=is.oms.db.name to the name of your database dedicated for IOM.
   3. Change /system-property=is.oms.db.user to the name of the user, which should be used to connect to the PostgreSQL database.
   4. Change /system-property=is.oms.db.pass to the password of the user, who connects to the PostgreSQL database.

2. Import is done using the following SQL command for import.

   Install database dump

   # as $OMS_USER at $OMS_HOME
   # setup environment
   . bin/set_env.sh
    
   # unzip and install initial data dump
   gunzip -c postgres/dumps/OmsDB.initial.2.12.0.0.sql.gz | psql -U $PGUSER -h $PGHOST -p $PGPORT -d $PGDATABASE

Database Migration

Refer to Guide - IOM Database Migration (2.0 - 2.17) if you have to migrate the database.

This is the case when migrating from an older version of IOM or if the IOM version you are installing has a higher version number than the dump you have installed before.

Install WildFly

Download and Place the WildFly Installation Package

1. Get the latest version of WildFly 15.0 from http://wildfly.org/downloads/ (i.e., 15.0.1.Final) as a TGZ archive into /tmp.

2. Create directory $JBOSS_HOME, set owner and group.

   Create JBOSS-HOME directory

   # as root do
   JBOSS_HOME=<set variable according the settings in installation.properties>
   OMS_USER=<name of user to own and run IOM>
    
   mkdir -p $JBOSS_HOME
   chown $OMS_USER:$OMS_USER $JBOSS_HOME

3. As $OMS_USER unpack the downloaded archive into $JBOSS_HOME:

   Extract WildFly appserver

   # as $OMS_USER at $OMS_HOME
   # setup environment
   . bin/set_env.sh
   
   # set variable
   WILDFLY_VERSION=15.0.1.Final
   
   # extract wildfly package to $JBOSS_HOME
   cd $JBOSS_HOME
   tar -xzf /tmp/wildfly-$WILDFLY_VERSION.tar.gz
   ( cd wildfly-$WILDFLY_VERSION; mv * .[a-zA-Z0-9]* .. )
   rmdir wildfly-$WILDFLY_VERSION

Prepare Configuration

Adapt installation.properties

1. Set JBOSS_BIND_ADDRESS in installation.properties to an IP address, which is reachable by the browser.
   It is also possible to use the default value of 0.0.0.0 here. This value represents „any address“ and covers all available network interfaces.

Install WildFly Application Server as a System Service

IOM release provides a systemd-unit template to install WildFly as a service. The expand_template.sh script uses the environment, hence the information stored in installation.properties, to fill the template. Before expanding the template, make sure you have updated installation.properties. At least the variable JAVA_HOME needs to be adapted.

Since different IOM application servers might run on a single machine, the service name for every server has to be unique.

1. Edit installation.properties.
   1. JAVA_HOME has to be adapted to point to the directory holding the Java 11 installation.
   2. JBOSS_JAVA_OPTS can be adapted, if you want to change the default memory-configuration, garbage-collection configuration, etc.

2. Expand the systems unit template with current configuration.

   Expand system-unit template

   # as $OMS_USER setup environment
   . bin/set_env.sh
   
   # expand systemd-unit template
   expand_template.sh < $OMS_ETC/jboss-as.service.template > /tmp/jboss-as-$OMS_SERVER_TYPE.service

3. Install WildFly as a service.

   Install Wildfly as a service

   # as root set server type
   OMS_SERVER_TYPE=<server type of IOM>
    
   # copy expanded template
   cp /tmp/jboss-as-$OMS_SERVER_TYPE.service /etc/systemd/system
   
   # enable service
   systemctl enable jboss-as-$OMS_SERVER_TYPE
   
   # start service
   systemctl start jboss-as-$OMS_SERVER_TYPE

Prepare WildFly for Working as IOM Application Server

Configure WildFly

For the following steps, the WildFly application server needs to be running. WildFly will be configured for usage with IOM. 

1. Edit installation.properties.
   It is recommended to change the default password defined by JBOSS_ADMIN_PASSWD.

2. Create the admin user and configure WildFly.

   Configure Wildfly

   # as $OMS_USER in $OMS_HOME setup environment
   . bin/set_env.sh
    
   # create admin user for WildFly management
   add-user.sh -u $JBOSS_ADMIN_USER -p $JBOSS_ADMIN_PASSWD
    
   # load initial configuration of IOM
   jboss-cli.sh -u=$JBOSS_ADMIN_USER -p=$JBOSS_ADMIN_PASSWD --controller=$JBOSS_BIND_ADDRESS:$JBOSS_MGMT_PORT -c --file="$OMS_ETC/initSystem.std.$OMS_SERVER_TYPE.cli"
    
   # enhanced standard properties are set in the WildFly 
   cat $OMS_ETC/system.std.$OMS_SERVER_TYPE.properties | update_properties.sh --jboss-cli="jboss-cli.sh -u=$JBOSS_ADMIN_USER -p=$JBOSS_ADMIN_PASSWD -c --controller=$JBOSS_BIND_ADDRESS:$JBOSS_MGMT_PORT"
    
   # load $OMS_ETC/cluster.properties
   cat $OMS_ETC/cluster.properties | update_properties.sh --jboss-cli="jboss-cli.sh -u=$JBOSS_ADMIN_USER -p=$JBOSS_ADMIN_PASSWD -c --controller=$JBOSS_BIND_ADDRESS:$JBOSS_MGMT_PORT"

3. Restart the WildFly application server.

   Restart Wildfly

   # as root restart application server
   systemctl restart jboss-as-$OMS_SERVER_TYPE

Deploy IOM Artifacts

For the following steps, the WildFly application server and the PostgreSQL database need to be running. All deployment artifacts, which are listed in $OMS_ETC/deployment.$OMS_SERVER_TYPE.properties will be deployed into WildFly application server.

1. Deploy all artifacts defined by deployment.$OMS_SERVER_TYPE.properties.

   Deploy IOM artifacts

   # as $OMS_USER in $OMS_HOME setup environment
   . bin/set_env.sh
    
   # deploy all artifacts defined by deployment.properties
   deploy.sh --jboss-cli="jboss-cli.sh -u=$JBOSS_ADMIN_USER -p=$JBOSS_ADMIN_PASSWD -c --controller=$JBOSS_BIND_ADDRESS:$JBOSS_MGMT_PORT"

2. Check whether all artifacts have been deployed successfully:

   Get deployment status

   # as $OMS_USER in $OMS_HOME setup environment
   . bin/set_env.sh
    
   # get deployment status
   jboss-cli.sh -u=$JBOSS_ADMIN_USER -p=$JBOSS_ADMIN_PASSWD -c --controller=$JBOSS_BIND_ADDRESS:$JBOSS_MGMT_PORT "deployment-info" 

   Example output for standalone server:

   Console output

   NAME                                             RUNTIME-NAME                                     PERSISTENT ENABLED STATUS 
   postgresql-jdbc4                                 postgresql-jdbc4                                 true       true    OK     
   bakery.base-app-2.12.0.0-SNAPSHOT.ear            bakery.base-app-2.12.0.0-SNAPSHOT.ear            true       true    OK     
   process-app-2.12.0.0-SNAPSHOT.ear                process-app-2.12.0.0-SNAPSHOT.ear                true       true    OK     
   bakery.control-app-2.12.0.0-SNAPSHOT.war         bakery.control-app-2.12.0.0-SNAPSHOT.war         true       true    OK     
   bakery.impex-app-2.12.0.0-SNAPSHOT.war           bakery.impex-app-2.12.0.0-SNAPSHOT.war           true       true    OK     
   bakery.communication-app-2.12.0.0-SNAPSHOT.ear   bakery.communication-app-2.12.0.0-SNAPSHOT.ear   true       true    OK     
   bakery.omt-app-2.12.0.0-SNAPSHOT.war             bakery.omt-app-2.12.0.0-SNAPSHOT.war             true       true    OK     
   oms.rest.communication-app-2.12.0.0-SNAPSHOT.war oms.rest.communication-app-2.12.0.0-SNAPSHOT.war true       true    OK     
   oms.monitoring-app-2.12.0.0-SNAPSHOT.war         oms.monitoring-app-2.12.0.0-SNAPSHOT.war         true       true    OK     
   gdpr-app-2.12.0.0-SNAPSHOT.war                   gdpr-app-2.12.0.0-SNAPSHOT.war                   true       true    OK     
   rma-app-2.12.0.0-SNAPSHOT.war                    rma-app-2.12.0.0-SNAPSHOT.war                    true       true    OK
   
   

Install IOM Watchdog as a System Service

If you operate the IOM as a highly available system, the Wildfly application server must not run directly as system service. Instead, IOM Watchdog has to run as system service, starting and stopping the Wildfly application server depending on health checks, made on the application server, see Guide - Intershop Order Management - Technical Overview.

Since different IOM application servers may run on a single machine, the service name for every server has to be unique. 

The IOM release provides a systemd-unit template to install IOM Watchdog as a service. The expand_template.sh script uses the environment, hence the information stored in installation.properties to fill the template. Before expanding the template, make sure you have updated the installation.properties. At least the variable OMS_HOME needs to be up to date.

1. Edit installation.properties. 
   OMS_HOME has to be up to date.

2. Expand the systems unit template with current configuration:

   Expand system-unit template

   # as $OMS_USER setup environment
   . bin/set_env.sh
   
   # expand systemd-unit template
   expand_template.sh < $OMS_ETC/oms-watchdog.service.template > /tmp/jboss-as-$OMS_SERVER_TYPE.service

3. Install IOM Watchdog as a service.

   Install Wildfly as a service

   # fill the variable according the settings in installation.properties
   OMS_SERVER_TYPE=<server type of IOM>
    
   # as root copy expanded template
   cp /tmp/jboss-as-$OMS_SERVER_TYPE.service /etc/systemd/system
   
   # enable service
   systemctl enable jboss-as-$OMS_SERVER_TYPE
   
   # start service
   systemctl start jboss-as-$OMS_SERVER_TYPE

Configure Rotation Logs

The subsystem undertow is configured to write access logs to $OMS_LOG. It is only able to provide a daily rotation of logs. If you want to provide access logs to the ICI (Intershop Commerce Insight) to get a performance analysis, you need to use hourly rotation of logs. To overcome the limitation of undertow rotation feature, OMS provides a simple shell script to rotate the logs: bin/logrotate.sh.

If you use the default configuration of watchdog.properties and you want a logfile rotation according access_log.log you should add watchdog.log to logrotate too.

This script has to be executed at the beginning of every hour, by adding the following line to the crontab of $OMS_USER:

0 * * * *  . $OMS_HOME/bin/set_env.sh && logrotate.sh $OMS_LOG/access_log.log $OMS_LOG/watchdog.log