Prepare JBoss Connections and Web App Servers

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, or Oracle), as well as for HSQLDB.

1. Locate the pentaho/server/pentaho-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 same directory.
   • HSQLDB: hsqldb/main
   • H2: h2/main
3. Download the supported JDBC driver for your Pentaho Repository database to the directory that you just created. The JDBC Drivers Reference has a list of supported drivers.
4. Within that directory, perform the following steps.
   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.

<?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>

<?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>

<?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>

<?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 will 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. Copy the pentaho-style.war and pentaho.war files into the pentaho/server/pentaho-server/<your jboss installation directory>/standalone/deployment directory, or verify that the files are already there, as in PostgreSQL.
2. Locate the pentaho/server/pentaho-server/<your jboss installation directory>/standalone/configuration/standalone.xml file and open it with a text editor.
3. 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/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/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/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/pentaho_operations_mart" pool-name="pentahooperationsmartpool" enabled="true" jta="true" use-java-context="true" use-ccm="true">
                            <connection-url>
                                jdbc:postgresql://localhost:5432/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/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/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>                             
    
   
                     

4. Add the driver definition in the driver section of the file. Here is an example of the PostgreSQL driver definition. If you are using another database, 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>

5. Save and close the standalone.xml file.

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

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.war file.

If you have a different database than PostgreSQL, adjust the module name information 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>

3. Save and close the file.
4. Use a zip extraction utility (such as 7-Zip, Winzip, or Archive) to view the contents of the pentaho.war file. Do not unzip or extract the contents of the file.
5. Navigate to the WEB-INF directory and add the jboss-deployment-structure.xml file that you just created to it.
6. Close the pentaho.war file. The zip extraction utility that you used might show a prompt which asks whether you would like to update the file in the pentaho.war archive. Confirm that you would like to update the file.

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.war are not needed. You must remove these resource-references for the Pentaho Server to operate properly.

1. Navigate to the pentaho/server/pentaho-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.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.war archive. If this prompt appears, confirm that you would like to update the file.

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/pentaho-server/pentaho-solutions/system/quartz/quartz.properties file. Change the org.quartz.dataSource.myDS.jndiURL value to jboss/datasources/Quartz, then save and close the file.
2. Use a text editor to open the pentaho/server/pentaho-server/pentaho-solutions/system/audit_sql.xml file. Change the JNDI value to jboss/datasources/Hibernate, then save and close the file.
3. Use a text editor to open the pentaho/server/pentaho-server/pentaho-solutions/system/data-access/settings.xml file. Change the data-access-staging-jndi value to jboss/datasources/Hibernate, then save and close the file.
4. Open the pentaho/server/pentaho-server/pentaho-solutions/system/audit/dialects/h2 directory, making sure to open the file from the correct folder. Use the text editor to open each file in the H2 directory and make the following changes:
   • Change <database>Audit</database> to <database>jboss/datasources/Audit</database>.
   • Change <database>Hibernate</database> to <database>jboss/datasources/Hibernate</database>.

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

JBoss allows a specific set of packages from the JDK to load by default. To configure the Pentaho Platform in JBoss, add this list of packages.

1. Locate the pentaho/server/pentaho-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"/>

4. Save and close the module.xml file.
5. Navigate to the ...modules/system/layers/base/sun/jdk/main/service-loader-resources/META-INF/services directory.
6. Find and remove this driver:  java.sql.Driver.driver.

Step 9: Update applicationContext-spring-security.xml File

The default configuration of the Pentaho Suite includes an extra layer of protection which prevents certain types of session fixation vulnerabilities. This feature can only be enabled on application servers which support the Java Servlet standard 3.1 and later. Because versions of the JBoss web application server prior to JBoss 7.0 do not support this standard, the following changes are required.

In the applicationContext-spring-security.xml file, remove the following beans so Pentaho starts correctly. 

1. Navigate to the pentaho-server/pentaho-solution/system folder and open the applicationContext-spring-security.xml file with a text editor.
2. Find and remove all occurrences of the following string (including the comma).

   sessionMgmtFilter,

3. Find and remove the following code:

   <bean id="sas" class="org.springframework.security.web.authentication.session.ChangeSessionIdAuthenticationStrategy" />

4. Find and remove the following code:

   <property name="sessionAuthenticationStrategy" ref="sas" />

5. Find and remove the following code:

   <bean id="httpSessionSecurityContextRepository" class="org.springframework.security.web.context.HttpSessionSecurityContextRepository"/>

6. Find and remove the following block of code:

   <bean id="sessionMgmtFilter" class="org.springframework.security.web.session.SessionManagementFilter"> 
   <constructor-arg ref="httpSessionSecurityContextRepository"/> 
   <constructor-arg ref="sas"/> 
   </bean>

7. Save and close the file.

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

By default, JBoss allows up to one minute for a web application to be deployed; otherwise, an error occurs. Because the Pentaho 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 3600. Note that if you are installing the Pentaho Server on a VM, you might want to increase the deployment-timeout attribute's value to give the Pentaho 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.war file. Do not unzip the pentaho.war file, just view its contents.
2. Navigate to the WEB-INF directory in the pentaho.war file and open the web.xml file in a text editor.
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.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. Perform the following steps to define this location.

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.war file. Do not unzip the pentaho.war file, just view its contents.
2. Navigate to the WEB-INF directory in the pentaho.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 parameter 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/pentaho-server/pentaho-solutions</param-value>
    </context-param>
   

5. Save the changes and close the file.

Step 4: Configure JBoss Settings

The JBoss startup script needs to be modified to match the Pentaho Server's memory resource requirements. If this step is not performed, the Pentaho 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 section for JVM memory allocation, locate the line for JAVA_OPTS, and replace it with the following line of code:

Windows:

"JAVA_OPTS=-Xms4096m -Xmx6144m -DDI_HOME=%DI_HOME% -Dpentaho.installed.licenses.file=%PENTAHO_INSTALLED_LICENSE_PATH% -Djboss.as.management.blocking.timeout=3600"

Linux: 

JAVA_OPTS="-Xms4096m –Xmx6144m -Djava.net.preferIPv4Stack=true" -DDI_HOME=$DI_HOME -Dpentaho.installed.licenses.file=$PENTAHO_INSTALLED_LICENSE_PATH -Djboss.as.management.blocking.timeout=3600" 

The DI_HOME variable is defined in a separate step. See Start the Pentaho Server.

3. Save the changes and close the file.
4. Use a text editor to open the standalone.xml file in the <your JBoss installation directory>/standalone/configuration folder.
5. 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>

6.  Save the changes and close the file.

Step 5: Configure Pentaho Settings for JBoss

Before you deploy the Pentaho Server, update the Pentaho configuration settings for JBoss.

1. Edit /pentaho-solutions/system/karaf/etc/config.properties to add __redirect to the bootdelegation property, as shown in the following example:

   org.osgi.framework.bootdelegation =__redirected,
       com.sun.*, \
       javax.transaction, \
       javax.transaction.*, \
       javax.xml.crypto, \
       javax.xml.crypto.*, \
       jdk.nashorn.*, \
       sun.*, \
       jdk.internal.reflect, \
       jdk.internal.reflect.*, \
       org.apache.karaf.jaas.boot, \
       org.apache.karaf.jaas.boot.principal

2. Edit /pentaho-solutions/system/karaf/etc/custom.properties to change org.apache.xerces.*; version\=”2.9.1” to org.apache.xerces.*; version\=”2.11.0”. 

Optionally, you can add JBoss logging. We recommend completing the steps in the Add JBoss Logging article, and then running the appropriate script for starting your server. 

Step 6: Complete Checklist 

 Use the Verification Checklist for JBoss Connection Tasks to verify that you have completed all JBoss associated tasks before starting the Pentaho Server:.

Problems Starting the Pentaho Server

Visit our Troubleshooting Guide for help.