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. 

Perform JBoss-Specific Connection Tasks

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.

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. Download the supported JDBC driver for your BA Repository database to the postgresql/main, mysql/main, or oracle/main directories (which ever one you created).
  3. In the postgresql/main, mysql/main, or oracle/main (which ever one you created), 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>
 

Create Module File for HSQL Database

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

  1. Locate the pentaho/server/biserver-ee/<your jboss installation directory>/modules/system/layers/base/org directory and create the following path: hsqldb/main.
  2. Download the supported JDBC driver for HSQLDB and place it in the hsqldb/main directory.
  3. In the hsqldb/main directory, create a text file named module.xml.
  4. 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>
    
  5. Save and close the module.xml file.

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.
  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:/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:/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:/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:/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 MySQL 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>
    
  5. Close and save the standalone.xml file.
  6. Open the pentaho/server/biserver-ee/pentaho-solutions/system/applicationContext-spring-security-jdbc.xml file. Change the port number, driver class name, user name, and password to reflect your environment's settings, if necessary. When complete, save and close the file.

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

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.

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.
  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/biserver-ee/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/biserver-ee/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>to <database>jboss/datasources/Hibernate</database>.

Prepare JBoss Web Application Servers

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

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 480. 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="480"/>
    
  3. Save and close the file.

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.<</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. In the web.xml file, change the BA Server fully qualified URL by modifying the port number to match your SSL-enabled port number.
    <context-param>
        <param-name>fully-qualified-server-url</param-name>
        <param-value>http://localhost:8080/pentaho/</param-value>
    </context-param>
    
  5. Save the changes 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.

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.

Increase JBoss Default Memory Settings

Before you deploy the BA Server, modify the JBoss startup script to match the BA Server's memory resource requirements. If this step is not performed, the BA Server will not start.

  1. Use a text editor to open the standalone configuration file. The file you open depends on your operating system.
    • Microsoft Windows: <your jboss installation directory>/bin/standalone-conf.bat
    • Linux: <your jboss installation directory>/bin/standalone.conf
  2. Change the following code from -Xms1303m -Xmx1303m -XX:MaxPermSize=256m to this:
    -Xms4096m -Xmx6144m -XX:MaxPermSize=256m
    
  3. Save the changes and close the file.

Delete jsf-api.jar (JBoss 6.2.x only)

If you are deploying Pentaho on JBoss 6.2.x, delete the jsf-api.jar file.  Here is 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.war file. Do not unzip the pentaho.war file, just view its contents.
  2. Delete the jsf-api.jar from the WEB-INF/lib directory.
  3. Save and close the war file.

Optional: Add JBoss Logging

You can add Pentaho application level logging to the JBoss logging subsystem.

  1. Open the standalone.xml file in the <your jboss directory>/standalone/configuration directory.
  2. Under the </extensions> tag add this code.
     <system-properties>
          <property name="org.jboss.as.logging.per-deployment" value="false"/>
      </system-properties>
    
  3. Find the <console-handler ...> or <file-handler ...> sections and add the following two handlers.
    <console-handler name="PENTAHOCONSOLE">
    <level name="ALL"/>
    </console-handler>
       <file-handler name="PENTAHOFILE">
        <file relative-to="jboss.server.log.dir" path="pentaho.log"/>
        <append value="false"/>
    </file-handler>
    
  4. Under the file handlers section, there is a section containing <logger> tags. Configure the <root-logger> handler to use these handlers.
    <handler name="PENTAHOCONSOLE"/>
    <handler name="PENTAHOFILE"/>
    
  5. Add the following loggers above <root-logger>.
    <logger category="org.hibernate" use-parent-handlers="false">
        <level name="ERROR"/>
            <handlers>
                <handler name="PENTAHOFILE"/>
                <handler name="PENTAHOCONSOLE"/>
            </handlers>
    </logger>
    <logger category="net.sf.ehcache" use-parent-handlers="false">
        <level name="ERROR"/>
            <handlers>
                <handler name="PENTAHOFILE"/>
                <handler name="PENTAHOCONSOLE"/>
            </handlers>
       </logger>
    <logger category="org.quartz" use-parent-handlers="false">
        <level name="ERROR"/>
            <handlers>
                <handler name="PENTAHOFILE"/>
                <handler name="PENTAHOCONSOLE"/>
    </handlers>
    </logger>
        <logger category="org.springframework" use-parent-handlers="false">
        <level name="ERROR"/>
            <handlers>
                <handler name="PENTAHOFILE"/>
                <handler name="PENTAHOCONSOLE"/>
            </handlers>
    </logger>
    <logger category="org.springframework.security" use-parent-handlers="false">
        <level name="ERROR"/>
        <handlers>
            <handler name="PENTAHOFILE"/>
            <handler name="PENTAHOCONSOLE"/>
        </handlers>
    </logger>
    <logger category="org.pentaho" use-parent-handlers="false">
        <level name="ERROR"/>
        <handlers>
            <handler name="PENTAHOFILE"/>
            <handler name="PENTAHOCONSOLE"/>
        </handlers>
    </logger>
    <logger category="com.pentaho" use-parent-handlers="false">
        <level name="ERROR"/>
        <handlers>
            <handler name="PENTAHOFILE"/>
            <handler name="PENTAHOCONSOLE"/>
        </handlers>
    </logger>
    <logger category="org.jfree.JCommon" use-parent-handlers="false">
        <level name="ERROR"/>
        <handlers>
            <handler name="PENTAHOFILE"/>
            <handler name="PENTAHOCONSOLE"/>
        </handlers>
    </logger>
    <logger category="org.apache.jackrabbit.core.security.authentication.AbstractLoginModule" use-parent-handlers="false">
        <level name="ERROR"/>
        <handlers>
            <handler name="PENTAHOFILE"/>
            <handler name="PENTAHOCONSOLE"/>
        </handlers>
    </logger>
    <logger category="RepositoryImportLog" use-parent-handlers="false">
        <level name="INFO"/>
        <handlers>
            <handler name="PENTAHOFILE"/>
            <handler name="PENTAHOCONSOLE"/>
        </handlers>
    </logger>
    
  6. Save and close the file.