Skip to main content
Pentaho Documentation

Prepare JBoss Connections and Web App Server

After your repository has been configured, you must configure the web application servers to connect to the DI Repository. In this step, JDBC and JNDI connections are made to the Hibernate, Jackrabbit, and Quartz databases. By default, the DI Server software is configured to be deployed and run on the Tomcat server.

If you are using JBoss, both JDBC and JNDI connection information must be specified. This checklist for JBoss connection tasks will help you verify that you have completed all items needed before starting the Pentaho DI Server.

Install JDBC Driver as a Module in JBoss

In JBoss, JDBC driver information is stored in a module, which is an XML file that you create. You must download the JDBC driver software component to the correct directory, then create module.xml files for each database.

The JDBC Drivers Reference has a list of supported drivers.

Step 1: Create Module File for Pentaho Repository Database

You need to create a file for the database that hosts the Pentaho Repository (either PostgreSQL, MySQL, MS SQL Server, or Oracle), as well as for HSQLDB.

  1. Locate the pentaho/server/data-integration-server/<your jboss installation directory>/modules/system/layers/base/org folder and create one of the following paths for the database on which you are hosting the Pentaho Repository.
    • PostgreSQL: postgresql/main
    • MySQL: mysql/main
    • Oracle: oracle/main
    • MS SQL Server: sqlserver/main
  2. Create these two paths in the /modules/system/layers/base/org directory.
    • HSQLDB: hsqldb/main
    • H2: h2/main
  3. Download the supported JDBC driver for your Pentaho Repository database to the directory you just created. The JDBC Drivers Reference has a list of supported drivers.
  4. Within that directory, do the following things:
    1. Use an editor to create a text file named module.xml.
    2. Copy the appropriate code into the module.xml file, then modify it so that the name of the JDBC driver you just downloaded appears.
    3. Save and close the module.xml file.
Repository Type Module code
PostgreSQL
<?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="org.postgresql">
        <resources>
            <resource-root path="[Name of JDBC Jar You Downloaded Here]"/>
        </resources>
        <dependencies><module name="javax.api"/></dependencies>
    </module>
MySQL
<?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="org.mysql">
        <resources>
            <resource-root path="[Name of JDBC Jar You Downloaded Here]"/>
        </resources>
        <dependencies><module name="javax.api"/></dependencies>
    </module>
Oracle
<?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="org.oracle">
        <resources>
            <resource-root path="[Name of JDBC Jar You Downloaded Here]"/>
        </resources>
        <dependencies><module name="javax.api"/></dependencies>
    </module>
MS SQL Server
<?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="org.sqlserver">
        <resources>
            <resource-root path="[Name of JDBC Jar You Downloaded Here]"/>
        </resources>
        <dependencies><module name="javax.api"/></dependencies>
    </module>

Step 2: Create Module File for HSQL Database

You need to create a module file for the HSQL database. 

The version of HSQLDB used should be 2.3.2.

  1. Download the supported JDBC driver for HSQLDB and place it in the hsqldb/main directory.
  2. In the hsqldb/main directory, create a text file named module.xml.
  3. Copy this code into the module.xml file, then modify it so that the name of the JDBC driver you just downloaded appears in the resource-root path.
    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="org.hsqldb">
    <resources>
    <resource-root path="[Name of JDBC Jar You Downloaded Here]"/>
    </resources>
    <dependencies><module name="javax.api"/></dependencies>
    </module>
    
  4. Save and close the module.xml file.

Step 3: Create Module File for H2 Database

You need to create a module file for the H2 database.

  1. In the h2/main directory, create a text file named module.xml.
  2. Copy this code into the module.xml file, then modify it so that the name of the JDBC driver you just downloaded appears in the resource-root path.
    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="org.h2">
    <resources>
    <resource-root path="[Name of JDBC Jar You Downloaded Here]"/>
    </resources>
    <dependencies><module name="javax.api"/></dependencies>
    </module>
    
  3. Save and close the module.xml file.

Step 4: Define JNDI Database Connection Information in JBoss

JNDI is used to specify port, driver, user name, and password information for the Audit and Quartz databases that are housed on your Pentaho Repository database. This section shows you how to define your JNDI database connection information.

If you have a different database than PostgreSQL, or if you are using a different port, password, user, driver class information, or IP address, make sure that you adjust the examples in this section to match the ones in your environment.

  1. Locate the pentaho/server/data-integration-server/<your jboss installation directory>/standalone/configuration/standalone.xml file and open it with a text editor.
  2. Insert these lines after the definition for ExampleDS data source.
     
    <datasource jndi-name="java:jboss/datasources/Hibernate" pool-name="hibpool" enabled="true" jta="true" use-java-context="true" use-ccm="true">
    					<connection-url>jdbc:postgresql://localhost:5432/di_hibernate</connection-url>
    					<driver-class>org.postgresql.Driver</driver-class>
    					<driver>org.postgresql</driver>
    					<pool>
    						<prefill>false</prefill>
    						<use-strict-min>false</use-strict-min>
    						<flush-strategy>FailingConnectionOnly</flush-strategy>
    					</pool>
    					<security>
    						<user-name>hibuser</user-name>
    						<password>password</password>
    					</security>
    				</datasource>
    				
    				<datasource jndi-name="java:jboss/datasources/Quartz" pool-name="quartzpool" enabled="true" jta="true" use-java-context="true" use-ccm="true">
    					<connection-url>jdbc:postgresql://localhost:5432/di_quartz</connection-url>
    					<driver-class>org.postgresql.Driver</driver-class>
    					<driver>org.postgresql</driver>
    					<pool>
    						<prefill>false</prefill>
    						<use-strict-min>false</use-strict-min>
    						<flush-strategy>FailingConnectionOnly</flush-strategy>
    					</pool>
    					<security>
    						<user-name>pentaho_user</user-name>
    						<password>password</password>
    					</security>
    				</datasource>
    				
    				<datasource jndi-name="java:jboss/datasources/Audit" pool-name="auditpool" enabled="true" jta="true" use-java-context="true" use-ccm="true">
    					<connection-url>jdbc:postgresql://localhost:5432/di_hibernate</connection-url>
    					<driver-class>org.postgresql.Driver</driver-class>
    					<driver>org.postgresql</driver>
    					<pool>
    						<prefill>false</prefill>
    						<use-strict-min>false</use-strict-min>
    						<flush-strategy>FailingConnectionOnly</flush-strategy>
    					</pool>
    					<security>
    						<user-name>pentaho_user</user-name>
    						<password>password</password>
    					</security>
    				</datasource>
    				
    				<datasource jndi-name="java:jboss/datasources/PDI_Operations_Mart" pool-name="PDI_Operations_Mart" enabled="true" jta="true" use-java-context="true" use-ccm="true">
    					<connection-url>jdbc:postgresql://localhost:5432/di_hibernate</connection-url>
    					<driver-class>org.postgresql.Driver</driver-class>
    					<driver>org.postgresql</driver>
    					<pool>
    						<prefill>false</prefill>
    						<use-strict-min>false</use-strict-min>
    						<flush-strategy>FailingConnectionOnly</flush-strategy>
    					</pool>
    					<security>
    						<user-name>hibuser</user-name>
    						<password>password</password>
    					</security>
    				</datasource>
    
  3. Add the driver definition in the driver section of the file. Here is an example of the PostgreSQL driver definition. If you are using MySQL, MS SQL Server, or Oracle, modify the driver name, module, and data source class accordingly.
    <driver name="org.postgresql" module="org.postgresql"> 
    <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class> 
    </driver> 
    <driver name="org.hsqldb" module="org.hsqldb"> 
    <driver-class>org.hsqldb.jdbcDriver</driver-class> 
    </driver> 
    
  4. Save and close the standalone.xml file.

Step 5: Add JBoss Deployment Structure File to pentaho-di.war

The jboss-deployment-structure.xml file controls class loading. It prevents automatic dependencies from being added, adds dependencies, defines additional modules, changes isolated class loading behavior, and adds additional resource roots to a module. You will need to create, then add a JBoss deployment structure file (jboss-deployment-structure.xml) to the pentaho-di.war.

If you have a different database than PostgreSQL, adjust the module names in this section to match the ones in your environment.

  1. Use a text editor to create a new file named jboss-deployment-structure.xml.
  2. Copy the following code snippet to the jboss-deployment-structure.xml file.
<jboss-deployment-structure>
<deployment>
<exclude-subsystems>
<subsystem name="resteasy" />
<subsystem name="jaxrs" />
<subsystem name="webservices" />
</exclude-subsystems>
<dependencies>
<module name="org.h2" />
<module name="org.postgresql" />
<module name="org.jboss.modules" />
<module name="org.hsqldb" />
</dependencies>
</deployment>
</jboss-deployment-structure>
  1. Save and close the file.
  2. Use a zip extraction utility (such as 7-Zip, Winzip, or Archive) to view the contents of the pentaho-di.war file. Do not unzip or extract the contents of the file.
  3. Navigate to the WEB-INF directory and add the jboss-deployment-structure.xml file that you just created to it.
  4. Close the pentaho-di.war file. The zip extraction utility that you used might show a prompt that asks whether you would like to update the file in the pentaho-di.war archive. If this happens, confirm that you would like to do this.

Step 6: Remove JNDI Resource References in JBoss

Because JBoss has its own mechanism for referencing JNDI data sources, the resource-references in the web.xml file located in the pentaho-di.war are not needed. You must remove these resource-references for the DI Server to operate properly.

  1. Navigate to the pentaho/server/data-integration-server/<your jboss installation directory>/standalone/deployments directory.
  2. Use a zip extraction utility (such as 7-Zip, Winzip, or Archive) to view the contents of the pentaho-di.war file. Do not unzip or extract the contents of the file.
  3. Navigate to the WEB-INF directory and open the web.xml file in a text editor.
  4. Delete all <resource-ref> tagged entries including everything between the <resource-ref> and </resource ref> tags.
  5. Save and close the file.
  6. The zip extraction utility that you used might show a prompt that asks whether you would like to update the file in the pentaho-di.war archive. If this happens, confirm that you would like to do this.

Step 7: Update JNDI Data Source Reference to Conform to JBoss Standards 

Update these files so that referenced JNDI datasources conform to JBoss standards.

  1. Use a text editor to open the pentaho/server/data-integration-server/pentaho-solutions/system/quartz/quartz.properties file.
  2. Change the org.quartz.dataSource.myDS.jndiURL value to jboss/datasources/Quartz, then save and close the file.
  3. Use a text editor to open the pentaho/server/data-integration-server/pentaho-solutions/system/audit_sql.xml file.
  4. Change the JNDI value to jboss/datasources/Hibernate, then save and close the file.
  5. Open the pentaho/server/data-integration-server/pentaho-solutions/system/audit/dialects/h2 folder. Use the text editor to open each file and make the following changes: 
  • Change <database>Audit</database> to <database>jboss/datasources/Audit</database>.
  • Change <database>Hibernate</database><database>jboss/datasources/Hibernate</database>.

Step 8: Enable JBoss Classloader to Load Classes from Sun JDK

JBoss enables certain set of packages from JDK to be loaded by default. To configure the Pentaho Platform in JBoss, add this list of packages.

  1. Locate the pentaho/server/data-integration-server/<your jboss installation directory>/modules/system/layers/base/sun/jdk/main directory.
  2. Open the module.xml file with any text editor.
  3. Add these three lines below the list of packages in the module.xml.
<path name="sun/net/www/protocol/jar"/>
<path name="sun/net/www/protocol/jar/JarURLConnection"/>
<path name="com/sun/org/apache/xerces/internal/jaxp/datatype"/> 
  1. Save and close the module.xml file.
  2. Navigate to the ...modules/system/layers/base/sun/jdk/main/service-loader-resources/META-INF/services directory.
  3. Find and remove this driver:  java.sql.Driver.driver.

Prepare JBoss Web Application Servers

If you have installed the JBoss web application server, you must manually complete several configuration tasks. 

Step 1: Increase the Amount of Time JBoss Allows for DI Server Deployment

By default, JBoss allows up to one minute for a web application to be deployed. If the web application is not deployed within that time frame, an error occurs.

Because the DI Server deployment requires more than one minute, manually edit the standalone.xml file to increase the deployment time.

  1. Use a text editor to open the <your jboss installation directory>/standalone/configuration/standalone.xml file.
  2. Find the deployment-scanner tag, add the deployment-timeout attribute, then set the attribute equal to 480. Note that if you are installing the DI Server on a VM, you might want to increase the deployment-timeout attribute's value to give the DI Server more time to deploy.
    <deployment-scanner scan-interval="5000" relative-to="jboss.server.base.dir" path="deployments" scan-enabled="true" deployment-timeout="3600"/>
    
  3. Save and close the file.

Step 2: Disable the JBoss RESTEasy Scan

To load pentaho REST services correctly, the RESTEasy scan in JBoss must be disabled. These instructions explain how to do this.

  1. Use a zip extraction utility such as 7-Zip, Winzip, or Archive to view the contents of the <your jboss installation directory>/standalone/deployments/pentaho-di.war file. Do not unzip the pentaho-di.war file, just view its contents.
  2. Navigate to the WEB-INF directory in the pentaho-di.war file and open the web.xml file in a text editor.<</li>
  3. At the end of the <context-param> tags, add this code.
    <context-param>
                 <param-name>resteasy.scan</param-name>
                 <param-value>false</param-value>
            </context-param>
            <context-param>
                 <param-name>resteasy.scan.resources</param-name>
                 <param-value>false</param-value>
            </context-param>
            <context-param>
                 <param-name>resteasy.scan.providers</param-name>
                 <param-value>false</param-value>
    </context-param>
    
  4. Save the changes and close the file.
  5. The zip extraction utility that you used might show a prompt that asks whether you would like to update the file in the pentaho-di.war archive. If this happens, confirm that you would like to do this.

Step 3: Set the Location of the pentaho-solutions Directory

To deploy JBoss correctly, Pentaho recommends that you define the location of the Pentaho solutions directory in the web.xml file. These instructions explain how to do this.

  1. If you have not done so already, use a zip extraction utility such as 7-Zip, Winzip, or Archive to view the contents of the <your jboss installation directory>/standalone/deployments/pentaho-di.war file. Do not unzip the pentaho-di.war file, just view its contents.
  2. Navigate to the WEB-INF directory in the pentaho-di.war file and open the web.xml file in a text editor.
  3. Locate the following <context-param> tags.
    <context-param>
          <param-name>solution-path</param-name>
          <param-value></param-value>
     </context-param>
    
  4. Set the paramater value of the solution-path to the pentaho-solutions path. An example of the code is below.
    <context-param>
         <param-name>solution-path</param-name>
         <param-value>/home/pentaho/server/data-integration-server/pentaho-solutions</param-value>
     </context-param>
    
  5. Save the changes and close the file.

Step 4: Configure JBoss Settings

Before you deploy the DI Server, modify the JBoss startup script to match the DIServer's memory resource requirements. If this step is not performed, the DI Server will not start. Besides matching memory resources, the Tomcat connector must also be updated for UTF-8 encoding.

We recommend increasing the time outs even further than shown here if you have a large database and you are upgrading from 5.x.

  1. Use a text editor to open the standalone configuration file. The file you open depends on your operating system.
    • Windows: <your JBoss installation directory>\bin\standalone.conf.bat
    • Linux: <your JBoss installation directory>/bin/standalone.conf
  2. Find the line for JAVA_OPTS and change the code as follows:

Windows:

"JAVA_OPTS=-Xms4096m -Xmx4096m -XX:MaxPermSize=256m -DDI_HOME=%DI_HOME% -Dpentaho.installed.licenses.file=%PENTAHO_INSTALLED_LICENSE_PATH% -Djboss.as.management.blocking.timeout=3600"

Linux:

JAVA_OPTS="-Xms4096m –Xmx4096m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true" -DDI_HOME=$DI_HOME -Dpentaho.installed.licenses.file=$PENTAHO_INSTALLED_LICENSE_PATH -Djboss.as.management.blocking.timeout=3600" 
  1. Save the changes and close the file.
  2. Use a text editor to open the standalone.xml file in the <your JBoss installation directory>/standalone/configuration folder.
  3. Set the org.apache.catalina.connector.URL_ENCODING and org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING system properties by adding the following lines of code to the standalone.xml file:
<system-properties>
  <property name="org.apache.catalina.connector.URI_ENCODING" value="UTF-8"/>
  <property name="org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING" value="true"/>
</system-properties>
  1.  Save the changes and close the file.

Step 5: Configure http and https Ports on JBoss

Since the DI Server is configured to run on 9080 (http) and 9443 (https), you need to configure JBoss for these ports as well.

  1. Use a text editor to open the standalone.xml file, which is located in pentaho/server/data-integration-server/<your jboss installation directory>/standalone/configuration directory.
  2. Modify the http and https socket-binding parameters to reflect the DI Server ports.
    <socket-binding name="http" port="9080"/>
    <socket-binding name="https" port="9443"/>
  3. Save the changes and close the file.

Step 6: Configure the Fully-Qualified URL for DI Server

If you need to change the DI Server fully qualified URL, locate the server.properties file and modify the port number to match your SSL-enabled port number. Save and close the file when you are done with the changes.

<context-param>
    <param-name>fully-qualified-server-url</param-name>
    <param-value>http://localhost:9080/pentaho-di/</param-value>
</context-param>

Start the DI Server

After you have completed all of the JBoss tasks, it is time to start the DI server.  After you have completed all of the JBoss tasks, you are ready to start the DI Server. If you want to add the optional JBoss logging, do that first and then run the appropriate script for starting your server.