Skip to main content
Pentaho Documentation

Prepare JBoss Connections and Web App Servers

Overview

Quisque mattis rutrum ligula et pellentesque. Pellentesque massa enim, pulvinar quis quam quis, aliquet dapibus augue. Aliquam feugiat suscipit turpis, nec ultrices dolor adipiscing ut.

After your repository has been configured, you must configure the web application servers to connect to the BA Repository. In this step, JDBC and JNDI connections are made to the Hibernate, Jackrabbit, and Quartz databases. By default, the BA 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 BA 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 BA Repository Database

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

  1. Locate the pentaho/server/biserver-ee/<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 BA 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 BA Repository database to the directory that 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 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 BA 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/biserver-ee/<your jboss installation directory>/standalone/deployment directory, or verify that the files are already there, as in PostgreSQL.
  2. Locate the pentaho/server/biserver-ee/<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 pentaho.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.war.

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

  1. Navigate to the pentaho/server/biserver-ee/<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 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/biserver-ee/pentaho-solutions/system/quartz/quartz.properties file.
    1. 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/biserver-ee/pentaho-solutions/system/audit_sql.xml file.
    1. Change the JNDI value to jboss/datasources/Hibernate, then save and close the file.
  3. Use a text editor to open the pentaho/server/biserver-ee/pentaho-solutions/system/data-access/settings.xml file.
    1. Change the data-access-staging-jndi value to jboss/datasources/Hibernate, then save and close the file.
  4. Open the pentaho/server/biserver-ee/pentaho-solutions/system/audit/dialects/h2 directory. (Make sure you open the file from the correct folder.)
  5. Use the text editor to open each file in the H2 directory and make the following changes:
    1. Change <database>Audit</database> to <database>jboss/datasources/Audit</database>.
    2. Change <database>Hibernate</database> to <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/biserver-ee/<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 BA 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 timeframe, an error occurs.

Because the BA 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 BA Server on a VM, you might want to increase the deployment-timeout attribute's value to give the BA 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. 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 jboss/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 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/biserver-ee/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.

  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" 
  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.

Start the BA Server

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

  1. Run the startup script for your web application server by launching one of these files in the JBoss bin directory:
    • Windows JBoss: Launch the standalone.bat file. 
    • Linux JBoss: Launch the standalone.sh file. 
  2. Open a web browser and enter this URL: http://localhost:8080/pentaho. The User Console Log On window appears. Note that you will be prompted to install a license. Information on how to do that appears in the Set Up BA Server instructions.