Chapter 5. Preparing for Production Installation

5.1. Installing the Prerequisite Software

5.1.1. JDK Installation for Production

The supported JDK versions for WAF are 1.3.1 and 1.4.1. Either version will work because the current release does not make use of any 1.4.x APIs not available in earlier JDK releases.

JDK packages may be obtained as described in Section 3.2 JDK Packages.

If you choose to use JDK 1.3.1, you must register the SunJCE security provider by editing the file $JAVA_HOME/jre/lib/security/java.security. To register a provider, specify the class name and priority in the following format:

security.provider.<n>=<className>

For example, suppose the file already has the following providers:

security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.rsajca.Provider

You can add the SunJCE provider as follows:

security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.rsajca.Provider
security.provider.3=com.sun.crypto.provider.SunJCE

If you use JDK 1.4.1, registering the SunJCE provider is not necessary, because it is shipped as part of the standard distribution. It should be already listed among the security providers supplied out of the box. In other words, for JDK 1.4.1, your output should be similar to the following:

cd $JAVA_HOME/jre/lib/security/
grep -E '^security\.provider' java.security
security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.net.ssl.internal.ssl.Provider
security.provider.3=com.sun.rsajca.Provider
security.provider.4=com.sun.crypto.provider.SunJCE
security.provider.5=sun.security.jgss.SunProvider

Note that SunJCE is listed among registered providers.

For additional information about registering the Sun security providers, please refer to http://java.sun.com/j2se/1.3/docs/guide/security/CryptoSpec.html#ProviderInstalling.

5.1.2. Installing Oracle Database for Production

Oracle9i Database 9.2 installation instructions for Linux are available online at http://otn.oracle.com/documentation/oracle9i.html. To access this information, you must first be a registered user to access at http://technet.oracle.com.

At a minimum, you will need the Oracle client libraries (for UNIX, this option is available during installation; on Windows it is called the Oracle Windows Client) if you are connecting to a remote Oracle Database installation. If you do not have an Oracle Database installation, you will need to install Oracle Database as well.

WarningWarning
 

Although you can install WAF with the Oracle Thin driver, there are some known issues with the way it handles LOBs. It is highly recommended that you use the OCI driver instead.

Most likely, the Oracle JDBC driver will be already in place at:

${ORACLE_HOME}/jdbc/lib/classes12.zip

This path is the default value offered by the Oracle Database installation program when configuring the location of the Oracle JDBC driver, if the Oracle Database client library is available and ORACLE_HOME is set accordingly. If this file does not exist, you must install it. You can download the drivers from http://technet.oracle.com; the classes12.zip included with the Solaris drivers works on Red Hat Enterprise Linux as well.

The OCI driver depends on native Oracle Database client libraries which must be properly set via LD_LIBRARY_PATH.

Make sure that the user running the servlet container has read access to the Oracle JDBC driver and client libraries.

To get the Thin JDBC driver to work, the target Oracle Database machine (for example, the one you are connecting to) must have its listener enabled for TCP connections, even if the WAF and Oracle Database installations are on the same host. If the OCI driver is an installed, you can use the OCI driver to eliminate the need for the TCP listener.

Install the Oracle9i Database client according to the instructions provided by Oracle. For further reference, see the Oracle9i Database installation hints for Red Hat Linux 7.2 online at http://www.idevelopment.info/data/DBA_tips/DBATIP_53.shtml.

A number of the commands for installation and day-to-day development assume that the Oracle Database environment has been setup for all users on the machine. This can be trivially accomplished by creating the file /etc/profile.d/oracle.sh as follows (you will need to correct the paths to match your local installation). A line break has been inserted for printing purposes; the "\" signifies where to reconnect the lines into one again:

export ORACLE_HOME=/u00/app/oracle/product/9.0.1
export NLS_LANG='AMERICAN_AMERICA.UTF8'
export PATH=$PATH:$ORACLE_HOME/bin
if [ -z $LD_LIBRARY_PATH ]
then
export LD_LIBRARY_PATH=$ORACLE_HOME/lib:$ORACLE_HOME/ctx/lib
else
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib:\
$ORACLE_HOME/ctx/lib
fi

NoteNote
 

If you are connecting to a local Oracle Database instance and you are not connecting via the listener, you must make sure ORACLE_SID is set in your environment as well. Normally this happens automatically during installation.

5.1.3. Installing PostgreSQL for Production

5.1.3.1. PostgreSQL Server

For detailed installation instructions, see http://www.postgresql.org/docs/7.3/static/installation.html.

Your PostgreSQL database server must listen via TCP/IP. To enable this, add the line tcpip_socket = true to the postgresql.conf of your database, which is usually /var/lib/pgsql/data/postgresql.conf.

When creating a database for use with WAF, there are two items that must be done. First, you need to declare that the database should encode information in the UNICODE setting. For more information, refer to http://www.redhat.com/docs/manuals/database/RHDB-2.1-Manual/admin_user/multibyte.html. Second, you must enable plpgsql for the database.

To create the database, you can execute the following:

createdb -h hostname -E UNICODE dbname
createlang -h hostname plpgsql dbname

Where hostname is the name of the host on which the database is running and dbname is the name of the database you want to create.

5.1.3.2. PostgreSQL Client

Web Application Framework 6.1 comes with its own PostgreSQL JDBC driver. Although the PostgreSQL JDBC driver that comes with Red Hat Enterprise Linux will work, the custom WAF driver is recommended for a production environment. Using the WAF driver, you do not need to configure the client any further.

5.1.4. Installing Servlet Container for Production

5.1.4.1. Basic Servlet Installation

WAF and its applications rely heavily on XML parsing. Both Tomcat and Resin supply their own XML parsers; however, they need to be configured correctly in order to work with WAF. Specifically, the XML/XSL libraries used must be of a tested combination e.g., Xerces/Xalan, Xerces/Saxon, or Caucho XML/XSL. Mixing and matching incompatible XML parsers and XSL transformers will not work.

5.1.4.2. Tomcat 4.x

Tomcat packages may be obtained as described in Section 3.4 Servlet Container Packages.

Tomcat 4.1.x uses the AElfred non-validating parser instead of the Xerces parser. AElfred will not work, and Xerces is used instead. The XML and XSL parsers are controlled by the Tomcat startup script, and can be modified by setting the DOCUMENT_BUILDER_FACTORY, SAX_PARSER_FACTORY, and JAVA_TRANSFORMER_FACTORY environment variables.

NoteNote
 

j2ee.jar includes a Tomcat reference implementation that you should not use. If you have a j2ee.jar in your CLASSPATH, make sure that your tomcat.jar comes before your j2ee.jar.

5.1.4.3. Resin

Resin packages may be obtained as described in Section 3.4 Servlet Container Packages.

If JAVA_HOME is set incorrectly, or is not set and the JDK is installed in a nonstandard location, Resin will die with the error message Bad File Descriptor.

http://www.caucho.com/resin/ref/xml/parsing.xtp discusses how to set Java system properties for the XML and XSL parsers.

5.1.4.4. WebSphere 4.0.x, 5.x

IBM's Websphere Application Server (WAS) requires that the SunJCE.jar library be imported when the application server itself is started, as opposed to when the webapp is started.

5.1.5. Installing Other Third-party Applications for Production

Perl must be installed in order to generate the servlet container configuration file. Although this is probably already included in the base OS install for Linux, on Windows servers, you will probably need to install it, as described in Section 3.5 Other Third-party Packages.