Chapter 36. KIE Server ZIP file installation and configuration

You can install KIE Server using the rhpam-7.11.0-kie-server-jws.zip file available from the Red Hat Process Automation Manager 7.11.0 Add Ons (rhpam-7.11.0-add-ons.zip) file on the Customer Portal and then configure the Java Database Connectivity (JDBC) web server data sources on Red Hat JBoss Web Server .

36.1. Installing KIE Server from ZIP files

KIE Server provides the runtime environment for business assets and accesses the data stored in the assets repository (knowledge store). You can use ZIP files to install KIE Server on an existing Red Hat JBoss Web Server 5.4.0 server instance.

Note

To use the installer JAR file to install KIE Server, see Chapter 35, Using the Red Hat Process Automation Manager installer.

  • The following files have been downloaded, as described in Chapter 34, Downloading the Red Hat Process Automation Manager installation files:

    • Red Hat Process Automation Manager 7.11.0 Add Ons (rhpam-7.11.0-add-ons.zip)
    • Red Hat Process Automation Manager 7.11.0 Maven Repository (rhpam-7.11.0-maven-repository.zip)
  • A backed-up Red Hat JBoss Web Server 5.4.0 server installation is available. The base directory of the Red Hat JBoss Web Server installation is referred to as JWS_HOME.
  • Sufficient user permissions to complete the installation are granted.

Procedure

  1. Extract the rhpam-7.11.0-add-ons.zip file.
  2. From the extracted rhpam-7.11.0-add-ons.zip file, extract the following files:

    • rhpam-7.11.0-kie-server-jws.zip
    • rhpam-7.11.0-process-engine.zip

    In the following instructions, the directory that contains the extracted rhpam-7.11.0-kie-server-jws.zip file is called JWS_TEMP_DIR and the directory that contains the extracted rhpam-7.11.0-process-engine.zip file is called ENGINE_TEMP_DIR.

  3. Copy the JWS_TEMP_DIR/rhpam-7.11.0-kie-server-jws/kie-server.war directory to the JWS_HOME/tomcat/webapps directory.

    Note

    Ensure the names of the Red Hat Process Automation Manager deployments you copy do not conflict with your existing deployments in the Red Hat JBoss Web Server instance.

  4. Remove the .war extensions from the kie-server.war folder.
  5. Move the kie-tomcat-integration-7.52.0.Final-redhat-00007.jar file from the ENGINE_TEMP_DIR directory to the JWS_HOME/tomcat/lib directory.
  6. Move the jboss-jacc-api-<VERSION>.jar, slf4j-api-<VERSION>.jar, and slf4j-jdk14-<VERSION>.jar files from the ENGINE_TEMP_DIR/lib directory to the JWS_HOME/tomcat/lib directory, where <VERSION> is the version artifact file name, in the lib directory.
  7. Add the following line to the <host> element in the JWS_HOME/tomcat/conf/server.xml file after the last Valve definition:

    <Valve className="org.kie.integration.tomcat.JACCValve" />
  8. Open the JWS_HOME/tomcat/conf/tomcat-users.xml file in a text editor.
  9. Add users and roles to the JWS_HOME/tomcat/conf/tomcat-users.xml file. In the following example, <ROLE_NAME> is a role supported by Red Hat Process Automation Manager. <USER_NAME> and <USER_PWD> are the user name and password of your choice:

    <role rolename="<ROLE_NAME>"/>
    <user username="<USER_NAME>" password="<USER_PWD>" roles="<ROLE_NAME>"/>

    If a user has more than one role, as shown in the following example, separate the roles with a comma:

    <role rolename="admin"/>
    <role rolename="kie-server"/>
    <user username="rhpamUser" password="user1234" roles="admin,kie-server"/>
  10. Complete one of the following steps in the JWS_HOME/tomcat/bin directory:

    • On Linux or UNIX, create the setenv.sh file with the following content:

      CATALINA_OPTS="-Xmx1024m -Dorg.jboss.logging.provider=jdk"
    • On Windows, add the following content to the setenv.bat file:

      set CATALINA_OPTS=-Xmx1024m -Dorg.jboss.logging.provider=jdk
Note

If you use Microsoft SQL Server, make sure you have appropriate transaction isolation for your database. If you do not, you may experience deadlocks. The recommended configuration is to turn on ALLOW_SNAPSHOT_ISOLATION and READ_COMMITTED_SNAPSHOT by entering the following statements:

ALTER DATABASE <DBNAME> SET ALLOW_SNAPSHOT_ISOLATION ON
ALTER DATABASE <DBNAME> SET READ_COMMITTED_SNAPSHOT ON

36.2. Configuring JDBC Web Server data sources

Java Database Connectivity (JDBC) is an API specification used to connect programs written in Java to databases. A data source is an object that enables a Java Database Connectivity (JDBC) client, such as an application server, to establish a connection with a database. Applications look up the data source on the Java Naming and Directory Interface (JNDI) tree or in the local application context and request a database connection to retrieve data. You must configure data sources for KIE Server to ensure correct data exchange between the servers and the designated database.

Typically, solutions using Red Hat Process Automation Manager manage several resources within a single transaction. JMS for asynchronous jobs, events, and timers, for example. Red Hat Process Automation Manager requires an XA driver in the datasource when possible to ensure data atomicity and consistent results. If transactional code for different schemas exists inside listeners or derives from hooks provided by the jBPM engine, an XA driver is also required.

Do not use non-XA datasources unless you are positive you do not have multiple resources participating in single transactions.

Note

For production environments, specify an actual data source. Do not use the example data source in production environments.

Prerequisites

  • Red Hat Process Automation Manager is installed on Red Hat JBoss Web Server.
  • The Red Hat Process Automation Manager 7.11.x Maven Repository (rhpam-7.11.0-maven-repository.zip) and the Red Hat Process Automation Manager 7.11.x Add-Ons (rhpam-7.11.0-add-ons.zip) files have been downloaded, as described in Chapter 34, Downloading the Red Hat Process Automation Manager installation files.
  • You want to configure one of the following supported databases and Hibernate dialects:

    • DB2: org.hibernate.dialect.DB2Dialect
    • MSSQL: org.hibernate.dialect.SQLServer2012Dialect
    • MySQL: org.hibernate.dialect.MySQL5InnoDBDialect
    • MariaDB: org.hibernate.dialect.MySQL5InnoDBDialect
    • Oracle: org.hibernate.dialect.Oracle10gDialect
    • PostgreSQL: org.hibernate.dialect.PostgreSQL82Dialect
    • PostgreSQL plus: org.hibernate.dialect.PostgresPlusDialect
    • Sybase: org.hibernate.dialect.SybaseASE157Dialect

Procedure

  1. Complete the following steps to prepare your database:

    1. Extract rhpam-7.11.0-add-ons.zip in a temporary directory, for example TEMP_DIR.
    2. Extract TEMP_DIR/rhpam-7.11.0-migration-tool.zip.
    3. Change your current directory to the TEMP_DIR/rhpam-7.11.0-migration-tool/ddl-scripts directory. This directory contains DDL scripts for several database types.
    4. Import the DDL script for your database type into the database that you want to use, for example:

      psql jbpm < /ddl-scripts/postgresql/postgresql-jbpm-schema.sql
      Note

      If you are using PostgreSQL or Oracle in conjunction with Spring Boot, you must import the respective Spring Boot DDL script, for example /ddl-scripts/oracle/oracle-springboot-jbpm-schema.sql or /ddl-scripts/postgresql/postgresql-springboot-jbpm-schema.sql.

  2. Extract the rhpam-7.11.0-maven-repository.zip offline Maven repository file.
  3. Copy the following libraries from the extracted offline Maven repository to the JWS_HOME/tomcat/lib folder where VERSION is the version of that library:

    org/jboss/spec/javax/transaction/jboss-transaction-api_1.2_spec/{VERSION}/jboss-transaction-api_1.2_spec-{VERSION}.jar
    org/jboss/integration/narayana-tomcat/{VERSION}/narayana-tomcat-{VERSION}.jar
    org/jboss/narayana/jta/narayana-jta/{VERSION}/narayana-jta-{VERSION}.jar
    org/jboss/jboss-transaction-spi/{VERSION}/jboss-transaction-spi-{VERSION}.jar
  4. Copy your database JDBC driver to the JWS_HOME/tomcat/lib folder.
  5. Configure the pooling XA data source in the JWS_HOME/tomcat/conf/context.xml file:

    Note

    Some of the properties in the following examples might not apply to your database server. Check the documentation for your JDBC driver to determine which properties to set.

    1. Configure an XA data source without pooling capabilities. This XA data source is used to create new connections to the target database. In the following example, the XA datasource is xads and the variables are defined in Table 36.1, “XA data source variables”:

      <?xml version="1.0" encoding="UTF-8"?>
      <Context>
      <Resource
      auth="Container"
      databaseName="${datasource.dbName}"
      description="XA Data Source"
      factory="org.apache.tomcat.jdbc.naming.GenericNamingResourcesFactory" loginTimeout="0"
      name="xads"
      uniqueName="xads"
      portNumber="${datasource.port}"
      serverName="${datasource.hostname}"
      testOnBorrow="false"
      type="${datasource.class}"
      url="${datasource.url}"
      URL="${datasource.url}"
      user="${datasource.username}"
      password="${datasource.password}"
      driverType="4"
      schema="${datasource.schema}"
      />
      </Context>

      Table 36.1. XA data source variables

      VariableDescription

      <datasource.dbName>

      The name of the database.

      <datasource.port>

      The port number of the database.

      <datasource.hostname>

      The name of the database host.

      <datasource.class>

      XADataSource class of JDBC driver.

      <datasource.url>

      The JDBC database connection URL. With some databases, the URL property is url and with other databases (for example H2 databases) this property is URL.

      <datasource.username>

      User name for the database connection.

      <datasource.password>

      Password for the database connection.

      <datasource.schema>

      The database schema.

    2. Configure a pooling data source that relies on the XA data source for creating new connections. In this example, the data source is poolingXaDs, <datasource.username> is the user name for the database connection, and <datasource.password> is the password for the database connection:

      <?xml version="1.0" encoding="UTF-8"?>
      <Context>
      <Resource
      name="poolingXaDs"
      uniqueName="poolingXaDs"
      auth="Container"
      description="Pooling XA Data Source" factory="org.jboss.narayana.tomcat.jta.TransactionalDataSourceFactory" testOnBorrow="true"
      transactionManager="TransactionManager" transactionSynchronizationRegistry="TransactionSynchronizationRegistry" type="javax.sql.XADataSource"
      username="${datasource.username}"
      password="${datasource.password}"
      xaDataSource="xads"
      />
      </Context>

      The data source is now available under the java:comp/env/poolingXaDs JNDI name and passes it to the KIE Server through the org.kie.server.persistence.ds system property as described in the next steps.

      Note

      The pooling data source configuration relies on additional resources that have been previously configured in context.xml file in kie-server application, specifically TransactionManager and TransactionSynchronizationRegistry.

  6. Configure KIE Server to use the data source:

    1. Open one of the following scripts in a text editor:

      Note

      The setenv.sh or setenv.bat script should already exist. However, if it does not, create it.

      • For Linux or Unix:

        JWS_HOME/tomcat/bin/setenv.sh
      • For Windows:

        JWS_HOME/tomcat/bin/setenv.bat
    2. Add the following properties to CATALINA_OPS where <hibernate.dialect> is the Hibernate dialect for your database:

      CATALINA_OPTS="-Xmx1024m
      -Dorg.jboss.logging.provider=jdk
      -Dorg.kie.server.persistence.ds=java:comp/env/poolingXaDs
      -Dorg.kie.server.persistence.tm=JBossTS
      -Dorg.kie.server.persistence.dialect=${<hibernate.dialect>}"