Installing on GlassFish Server

NOTE: Support for GlassFish 3 has been deprecated. Support for GlassFish 4 has been removed. See release notes.

NOTE: This chapter assumes the iKnowBase database repository has been created, as outlined in Quick Installation and upgrade overview .

Installation on GlassFish Server has the following tasks:

• Install the GlassFish-software
• Create a data source, and deploy to the target
• Deploy the Resource-directory and java web applications to the GlassFish Server
• Configure web application security

Installation and configuration of GlassFish itself.

Non-clustered:

Install a domain containing one or more instances.

Clustered:

Install a domain containing

• a cluster
• one or more instances supporting the cluster
• The WebDav and Instant module does not support clustering. This requires an additional separate instance or a cluster backed by a single instance.
  • Route by server: an instance not part of the cluster and route traffic to this instance using a reverse proxy.

Configuring a database data source

To run iKnowBase under GlassFish, you need to add the required jdbc driver, a connection pool and a data source:

First, install the Oracle JDBC Driver:

• iKnowBase requires JDBC for Oracle Database with SQL XML support: The Oracle jdbc-driver (ojdbc7.jar), the XML-database support (xdb6.jar) and the Oracle XML Parser v2 (xmlparserv2_sans_jaxp_services.jar).
• The jar files can be found on the Oracle web page, or in the product directory of your database (check ${ORACLE_HOME}/jdbc/lib, ${ORACLE_HOME}/rdbms/jlib and ${ORACLE_HOME}/xdk/lib).
• Install the driver to the GlassFish server or domain where you want to install iKnowBase, e.g. either ${GLASSFISH_HOME}/glassfish/lib/ or ${GLASSFISH_HOME}/glassfish/domain/domain1/lib/
• Restart your GlassFish instance.

Next, create a connection pool:

• From the GlassFish console, select “Resources, JDBC, Connection Pools” from the tree.
• Click “New” to create a new pool, and configure it as follows:
• Name = jdbc/iknowbaseDSPool
• ResourceType = javax.sql.ConnectionPoolDataSource
• Vendor=oracle
• Datasource Classname=oracle.jdbc.pool.OracleConnectionPoolDataSource
• Ping=Enabled
• Three properties (only)
  • url=jdbc:oracle:thin:@//dbhost.example.com:1521/dbname.domain
  • user=<database user>
  • password=<database password>

Finally ,create a data source:

• From the GlassFish console, select “Resources, JDBC, JDBC Resources” from the tree.
• Click “New” to create a new data source, and configure it as follows:
  • JNDI Name = jdbc/iknowbaseDS
  • Pool Name = jdbc/iknowbaseDSPool

Configuring cluster single-sign-on-state

The availability service for the cluster and web container must be enabled (enabled by default).

Single-sign-on-state for web container availability should also be enabled to support replicating the authenticated user.

Configuring the HTTP listener for ikbInstant

ikbInstant requires that support for Comet and/or Websockets is enabled on the HTTP listener.

• From the GlassFish console, select “Configurations, <your configuration name>, Network Config, Protocols, http-listener-1 (or your listener name)” from the tree.
• Select the HTTP tab
• Set Comet Support to Enabled

Deploy the applications

Non-clustered

Deployment example using the GlassFish console:

• Select “Applications” in the administration console.
• Select "Deploy"
• Select the relevant web archive.
• Set context root to / (deployments using the administration console will not pick up the configured context root)
• Target applications:
  • A server instance
    • You may enable all modules on a single deployment, but if you use multiple non clustered instances, you must ensure that the WebDav and Instant modules is enabled on only one instance.

Clustered

Deployment example using the GlassFish console:

• Select “Applications” in the administration console.
• Select "Deploy"
• Select the relevant web archive.
• Set context root to / (deployments using the administration console will not pick up the configured context root)
• Target applications:
  • Deploy iknowbase-webapp to the cluster on / with all required modules except WebDav and Instant.
  • Deploy iknowbase-webapp with a different name like “iknowbase-webapp-nocluster” to a server instance on / with the WebDav and Instant modules enabled (all the other modules may be disabled).
    • Configure WebDav to respond to webdav specific hostnames (see WebDav configuration)
    • Instant will respond to the /ikbInstant path.
• Availability:
  • All applications except iKnowBase Instant, iKnowBase WebDav and iKnowBase resources should have the “Availability” flag set.

Deploy the /ressurs-directory

The easiest mechanism is to deploy the iknowbase-resources-6.7.war file, which will automatically expose the resources on /ressurs.

If you want to have the /ressurs-directory (or other directories) available from the file system, unzip them to a directory and configure a reverse proxy in front of GlassFish to server this content for requests starting with “/ressurs”. As a standard deployment of iknowbase-webapp will use context root /, the GlassFish docroot cannot be used.

Configure Web Application Security

iKnowBase does not support the GlassFish container mode for authentication and you must use one of the available Spring Security authentication modules or extend with your own Spring Security module.

See iKnowBase Installation Guide > Web Application Security for additional explanations.

Configure SSL

We strongly recommend using SSL (https) for all production sites.

Terminating SSL in the application server

The procedures for terminating SSL directy in the application server can be found in the glassfish documentation.

Terminating SSL in an external proxy

If you terminate SSL in an external proxy, that proxy will typically use HTTP (an unsecured connection) to talk to the application server. Then, the application server will not be aware that the browser sees a secure connection, and will by default generate links to an unsecure site. To avoid this, note the following items:

• Configure the load balancer to generate a HTTP header called “X-Forwarded-Proto” with the value “https”, ref http://en.wikipedia.org/wiki/List_of_HTTP_header_fields
• Configure the glassfish http protocol listeners to use a scheme-mapping that understands this header, ref http://java.net/jira/browse/GLASSFISH-18685
• Verify this setup by loading /ikb$console/java/request using from a secure connection; the value “Requested URL” should indicate a https-scheme
• Note that you will need at least glassfish 3.1.2.2 for this setup to work

If using Apache httpd for ssl-termination, the following configuration in httpd.conf should set the required header:

<Virtualhost ...>
...
RequestHeader set X-Forwarded-Proto "https"
...
</Virtualhost>

Use the following example from the glassfish domain.xml:

<network-config>
  <protocols>
    <protocol name="http-listener-1">
      <http default-virtual-server="server" max-connections="250" scheme-mapping="X-Forwarded-Proto">
...

Troubleshooting

Using custom passwords on java keystores

If you have changed the passwords on GlassFish’s java truststore (cacerts.jks) and keystore (keystore.jks) during the setup and plan to deploy the iKnowBase Batch Server, the passwords for accessing the keystores must be set using JVM options
-Djavax.net.ssl.keyStorePassword=<your_new_password>
-Djavax.net.ssl.trustStorePassword=<your_new_password>

The Batch Server will fail to start ( SSLInitializationException: Failure initializing default system SSL context) if the passwords are not set.

GlassFish server.log: AS-NAMING-00006 and RAR8067

The following log statements in server.log is related to activiti module

• SEVERE: AS-NAMING-00006: Exception in NamingManagerImpl copyMutableObject: java.lang.IllegalStateException: This web container has not yet been started
• WARNING: RAR8067: Unable to determine pool type for pool [ jdbc/iknowbaseDSPool ], using default pool type

The issue can occur while reloading / redeploying a activiti enabled application (viewer or batch module with activiti enabled). The activiti job executor thread is busy looking for asynchronous tasks and might not shut down within the time used for reloading or redeploying the application.

This error results in a non-functioning activiti job executor and asynchronous tasks will not be loaded by this application.

To resolve the issue, restart the application server.

iKnowBase issue reference: IKBR-1124

GlassFish server.log: log4j called after unloading and Class invariant violation

The GlassFish server will report the following error message during startup:

[#|<TIMESTAMP>|SEVERE|glassfish3.1.2|javax.enterprise.system.std.com.sun.enterprise.server.logging|_ThreadID=1;_ThreadName=Thread-2;|log4j:ERROR log4j called after unloading, see http://logging.apache.org/log4j/1.2/faq.html#unload.|#]
[#|<TIMESTAMP>|SEVERE|glassfish3.1.2|javax.enterprise.system.std.com.sun.enterprise.server.logging|_ThreadID=1;_ThreadName=Thread-2;|java.lang.IllegalStateException: Class invariant violation
    at org.apache.log4j.LogManager.getLoggerRepository(LogManager.java:199)
    at org.apache.log4j.LogManager.getLogger(LogManager.java:228)
    at org.slf4j.impl.Log4jLoggerFactory.getLogger(Log4jLoggerFactory.java:66)
    at org.slf4j.LoggerFactory.getLogger(LoggerFactory.java:270)
    at org.slf4j.LoggerFactory.getLogger(LoggerFactory.java:281)

Set the JVM option -Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false to resolve this issue.

Example for disabling ENABLE_CLEAR_REFERENCES on Domain Administration Server and a cluster named myCluster:

./asadmin create-jvm-options -- -'Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false'
./asadmin create-jvm-options --target myCluster -- -'Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false'

Log4j reference: http://logging.apache.org/log4j/1.2/faq.html#unload
iKnowBase issue reference: IKB-2604

Database connections through firewall or on an unreliable network

When accessing a database through a firewall or on an unreliable network, use the Oracle Net connection descriptor syntax with ENABLE=BROKEN instead of the standard JDBC URL syntax as the database connection string.

Default JDBC URL:

jdbc:oracle:thin:@//localhost:1521/ORCL

Using Oracle Net connection descriptor syntax:

jdbc:oracle:thin:@(DESCRIPTION = (ENABLE = BROKEN)(ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = localhost)(PORT = 1521)))(CONNECT_DATA =(SERVER = DEDICATED)(SERVICE_NAME = ORCL)(FAILOVER_MODE =(TYPE = SESSION)(METHOD = BASIC))))