4.6.2 Deploying the Connect UI in RedHat JBoss 7

Update Authentication Provider

Connect uses a pluggable authentication provider that is deployed in JBoss as a separate module. The authentication provider is found in kc/import/jboss/connect_auth_jboss.jar. Since Connect user passwords are encrypted, the authentication provider needs to embed a copy of the crypto.properties file.

Add the crypto.properties file to the authentication provider using the following commands:

cd kc/import/jboss
unzip connect_auth_jboss.jar crypto.properties
cp ../../crypto.properties .
zip connect_auth_jboss.jar crypto.properties
rm crypto.properties

In other words, add crypto.properties to connect_auth_jboss.jar.

Note: Do NOT embed the authentication provider module in brickst.war. The authentication provider will be deployed below as a separate JBoss module.

Install JDBC Driver

The correct JDBC driver needs to be added to the JBoss configuration as a new module. In general you create a module by creating a directory under $JBOSS_HOME/modules, copying the appropriate jar files to this directory, and creating a module.xml file that describes the module to JBoss.

Installing Oracle JDBC

Create directory $JBOSS_HOME/modules/oracle/jdbc/driver/main.
Copy ojdbc6.jar and orai18n.jar from $KCHOME/import to here.
Create a file named module.xml in this directory with the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="oracle.jdbc.driver">
    <resources>
        <resource-root path="ojdbc6.jar"/>
        <resource-root path="orai18n.jar"/>
    </resources>
    <dependencies>
        <module name="javax.api"/>
    </dependencies>
</module>

Installing SQL Server JDBC

Create dir $JBOSS_HOME/modules/com/microsoft/sqlserver/main.
Copy $KCHOME/import/sqljdbc4.jar to here.
Create a file named module.xml in this directory with the following structure:

<?xml version="1.0" encoding="UTF-8"?>                
<module xmlns="urn:jboss:module:1.1" name="com.microsoft.sqlserver">
    <resources>
        <resource-root path="sqljdbc4.jar"/>
    </resources>
    <dependencies>
        <module name="javax.api"/>
    </dependencies>
</module>

Installing MySQL JDBC

Create directory $JBOSS_HOME/modules/mysql/jdbc/driver/main
Copy $KCHOME/import/mysql-connector-java-5.1.13-bin.jar to here
Create a file named module.xml in this directory with the following structure:

<?xml version="1.0" encoding="UTF-8"?>                
<module xmlns="urn:jboss:module:1.1" name="mysql.jdbc.driver">
    <resources>
        <resource-root path="mysql-connector-java-5.1.13-bin.jar"/>
    </resources>
    <dependencies>
        <module name="javax.api"/>
    </dependencies>
</module>

Create Data Source Definition for Connect UI

Once the JDBC driver module is defined, the next step is to define a J2EE data source that will be used by the Connect UI. In JBoss 7, data sources are defined in the $JBOSS_HOME/standalone/configuration/standalone.xml file. This file will contain a subsystem element that looks like this:

<subsystem xmlns="urn:jboss:domain:datasources:1.0">
    <datasources>
        <datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" use-java-context="true">
            <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
                <driver>h2</driver>
                <security>
                    <user-name>sa</user-name>
                    <password>sa</password>
                </security>
        </datasource>
        <drivers>
            <driver name="h2" module="com.h2database.h2">
                <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
            </driver>
        </drivers>
    </datasources>
</subsystem>

You will define a new datasource element and a new driver element for the Connect UI data source. Each data source has a minimum and maximum size setting for the connection pool. For the minimum, we recommend one connection per concurrent user. For maximum, we recommend three or more connections per concurrent user.

Note: You may only define one data source since they all use the same name and cannot coexist.

Oracle Data Source

For Oracle, add the following datasource element:

<datasource jndi-name="java:/jdbc/BRICK_STREET_SOFTWARE_CONNECT_DS" pool-name="BRICK_STREET_SOFTWARE_CONNECT_DS" enabled="true">
    <connection-url>jdbc:oracle:thin:@SERVER:1521:ORCL</connection-url>
    <driver>oraclejdbc</driver>
    <pool>
        <min-pool-size>10</min-pool-size>
        <max-pool-size>20</max-pool-size>
        <prefill>true</prefill>
    </pool>
    <security>
        <user-name>USERNAME</user-name>
        <password>PASSWORD</password>
    </security>
</datasource>

In the drivers element, define:

<driver name="oraclejdbc" module="oracle.jdbc.driver"/>

SQL Server Data Source

For SQL Server, add the following datasource element:

<datasource jndi-name="java:/jdbc/BRICK_STREET_SOFTWARE_CONNECT_DS" pool-name="BRICK_STREET_SOFTWARE_CONNECT_DS" enabled="true">
    <connection-url>jdbc:sqlserver://SERVER:1433;DatabaseName=CONNECT10</connection-url>
    <driver>sqlserverjdbc</driver>
    <pool>
        <min-pool-size>10</min-pool-size>
        <max-pool-size>20</max-pool-size>
        <prefill>true</prefill>
    </pool>
    <security>
        <user-name>USERNAME</user-name>
        <password>PASSWORD</password>
    </security>
</datasource>

In the drivers element, define:

<driver name="sqlserverjdbc" module="com.microsoft.sqlserver"/>

MySQL Data Source

For MySQL, add the following datasource element:

<datasource jndi-name="java:/jdbc/BRICK_STREET_SOFTWARE_CONNECT_DS" pool-name="BRICK_STREET_SOFTWARE_CONNECT_DS" enabled="true">
    <connection-url>jdbc:mysql://SERVER:3306/CONNECT10</connection-url>
    <driver>mysqljdbc</driver>
    <pool>
        <min-pool-size>10</min-pool-size>
        <max-pool-size>20</max-pool-size>
        <prefill>true</prefill>
    </pool>
    <security>
        <user-name>USERNAME</user-name>
        <password>PASSWORD</password>
    </security>
</datasource>

In the drivers element, define:

<driver name="mysqljdbc" module="mysql.jdbc.driver"/>

Install Connect Authentication Module

The Connect UI uses container-managed authentication. Therefore, an authentication module needs to be defined in JBoss in order for authentication to work with the Connect UI.

The first step is to create a new Jboss module for the authentication provider.

Create directory $JBOSS_HOME/modules/com/brickstreet/connectauth/main.
Copy $KCHOME/import/jboss/connect_auth_jboss.jar to here.
Create a file named module.xml in this directory with following structure:

<?xml version="1.0" encoding="UTF-8"?>                    
<module xmlns="urn:jboss:module:1.1" name="com.brickstreet.connectauth">
    <resources>
        <resource-root path="connect_auth_jboss.jar"/>
    </resources>
    <dependencies>
        <module name="org.picketbox"/>
        <module name="javax.api" slot="main" export="true"/>
    </dependencies> 
</module>

The second step is to define a security domain that uses the authentication module that we defined above. In JBoss 7, security domains are defined in the $JBOSS_HOME/standalone/configuration/standalone.xml file. This file will contain a subsystem element that looks like this:

<subsystem xmlns="urn:jboss:domain:security:1.1">
    <security-domains>
        <security-domain name="other" cache-type="default">
            ...
        </security-domain>
        ...
    </security-domains>
</subsystem>

You will define a new security-domain element for the Connect authentication module:

    <security-domain name="connect-auth" cache-type="default">
        <authentication>
            <login-module code="com.kana.connect.auth.jboss.ConnectLoginModule" flag="required"/>
        </authentication>
    </security-domain>

Install Bouncy Castle Encryption Provider

Connect uses the Bouncy Castle encryption provider. It must be installed as a separate module.

Create directory $JBOSS_HOME/modules/org/bouncycastle/main.
Copy $KCHOME/import/bcprov-jdk16-145.jar to here.
Create a file named module.xml in this directory with following structure:

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="org.bouncycastle">
    <resources>
        <resource-root path="bcprov-jdk16-145.jar"/>
    </resources>
    <dependencies>
        <module name="javax.api" slot="main" export="true"/>
    </dependencies>
</module>

Deploy brickst.war to the JBoss Server

To deploy the Connect UI, copy brickst.war to the JBoss deployment directory $JBOSS_HOME/standalone/deployments.

Running JBoss

Run JBoss by running the standalone.sh script. Alternatively you can run JBoss as a service and have it started automatically at boot time.

Troubleshooting

JBoss 7 expects brickst.war to be deployed within 60 seconds. If the deployment does not succeed, JBoss assumes the deployment has failed and terminates the deployment. If you see the following message in the JBoss log, you need to increase the deployment timeout.

ERROR [org.jboss.as.server.deployment.scanner] (DeploymentScanner-threads - 1) JBAS015052: Did not receive a response to the deployment operation within the allowed timeout period [60 seconds]. Check the server configuration file and the server logs to find more about the status of the deployment.

To increase the timeout, edit this entry in the standalone.xml file:

<subsystem xmlns="urn:jboss:domain:deployment-scanner:1.1">
    <deployment-scanner path="deployments" relative-to="jboss.server.base.dir" scan-interval="5000" />
</subsystem>

Add a deployment-timeout attribute to the deployment-scanner element. The attribute controls how many seconds JBoss will wait for the deployment operation to complete. The default value is 60. Increase this value until JBoss has sufficient time to deploy the Connect UI.