connectors/jk/xdocs/jk2/installhowto.xml

<?xml version="1.0"?>
<document>
<copyright>
   Copyright 1999-2004 The Apache Software Foundation
 
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
 
       http://www.apache.org/licenses/LICENSE-2.0
 
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
</copyright>

<properties>
  <title>Installation of jk2 in the Web Server</title>

  <author email="jfrederic.clere@fujitsu-siemens.com">Jean-Frederic Clere</author>
  <author email="andy@tagish.com">Andy Armstrng</author>
  <author email="yoavs@apache.org">Yoav Shapira</author>

  <date>$Date$</date>
</properties>

  <section name="Installation">
    <p>
      The actual build mechanism creates the dso files in the
      build/jk2/${servername} subdirectory of the jakarta-tomcat-connectors/jk.
      When configure --with-jni is used 2 dso files are created.
      These files have to be copied in the right location of the web server
      installation.
    </p>
    <p>
      JNI support in JK2 require APR, which is provded in Apache 2.0, and is
      available for many platforms, so Apache 1.3, IIS and NES/iPlanet should be
      able to use it
    </p>
    <subsection name="Apache 1.3">
      <p>
        In the following example Apache-1.3 is installed in
        /home/apache13/ and the commands are executed in
        the jakarta-tomcat-connectors directory.
      </p>
      <p>
        Apache 1.3 require APR, and if APR has been built with pthread support
        and your Apache 1.3 wasn't (general case in Unix platforms) you should :
        <ul>
        <li>
        Rebuild Apache 1.3 with pthread support (recommanded)
        </li>
        <li>
        Add the LoadFile /usr/lib/pthread.so in beginning of your httpd.conf
        </li>
        </ul>
      </p>
      <p>
        You should also ensure that the linker will be able to locate the apr shared libraries,
        <code>libapr.so</code>, and <code>libaprutil.so</code>, make sure they have been installed
        in linker search locations.
      </p>
      <screen>
        <note>Copy the dso files in the modules location:</note>
        <type>cp jk/build/jk2/apache13/mod_jk2.so /home/apache13/modules</type>
        <note>Copy jkjni.so if you're using JNI</note>
        <type>cp jk/build/jk2/apache13/jkjni.so /home/apache13/modules</type>
        <note>You may have to add pthread library in the httpd.conf:</note>
        <read>LoadFile /usr/lib/pthread.so</read>
        <note>Add mod_jk2 loading in the httpd.conf</note>
        <read>LoadModule jk2_module modules/mod_jk2.so</read>
      </screen>
    </subsection>
    <subsection name="Apache 2">
      <p>
        In the following example Apache-2.0 is installed in
        /home/apache20/apache40 and the commands are executed in
        the jakarta-tomcat-connectors directory.
      </p>
      <screen>
        <note>Copy the dso files in the modules location:</note>
        <type>cp jk/build/jk2/apache2/mod_jk2.so /home/apache20/apache40/modules</type>
        <note>Copy jkjni.so if you're using JNI</note>
        <type>cp jk/build/jk2/apache2/jkjni.so /home/apache20/apache40/modules</type>
        <note>Add mod_jk2 loading in the httpd.conf:</note>
        <read>LoadModule jk2_module modules/mod_jk2.so</read>
      </screen>
    </subsection>
    <subsection name="IIS">
        <p>A pre-built version of the ISAPI redirector server plugin, isapi_redirector2.dll,
        is available under the win32/i386 directory of jakarta-tomcat-connectors distribution.
        You can also build a copy locally from the source present in jakarta-tomcat-connectors
        distribution.<br />The Tomcat redirector requires three entities:
            <ul>
            <li>
            <b>isapi_redirector2.dll</b> - The IIS server plugin, either obtain a pre-built DLL or build it yourself (see the build section).
            </li><li>
            <b>workers2.properties</b> - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). 
                A sample workers2.properties can be found under the conf directory.
            </li><li>
            <b>jk2.properties</b> - A configuration file used by mod_jk2 on the Tomcat side.
            </li>
            </ul>
        </p>
        <p>
            <ol><li>In the registry, create a new registry key named
            <b>"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\2.0"</b>
            </li><li>
            Add a string value with the name <b>serverRoot</b> and a value which is a full path
            to your Tomcat installation (for example <b>c:\jakarta-tomcat</b>).  If Tomcat is installed
            on a different server, this entry must point to the location (directory) where the
            workers2.properties file resides.
            </li><li>
            Add a string value with the name <b>extensionUri</b> and a value of <b>/jakarta/isapi_redirector2.dll</b>
            </li><li>
            Add a string value with the name <b>workersFile</b> and a value which is the full path 
            to your workers2.properties file (for example <b>c:\jakarta-tomcat\conf\workers2.properties</b>)
            </li><li>
            Add a string value with the name <b>logLevel</b> and a value for your log level 
            (can be DEBUG, INFO or ERROR).
            </li><li>Using the IIS management console, add a new virtual directory to your IIS web site.
            The name of the virtual directory must be jakarta. 
            Its physical path should be the directory where you placed isapi_redirector2.dll 
            While creating this new virtual directory assign it with execute access.
            </li><li>
            Using the IIS management console, add isapi_redirector2.dll as a filter in your IIS web site. 
            The name of the filter should reflect its task (I use the name jakarta), 
            its executable must full path to the isapi_redirector2.dll. 
            </li>            
            </ol>        
        </p>
        <p>Install using provided script <b>install4iis.js</b><br/>
        This script creates the virtual directory and installs ISAPI filter for Default webserver<br/>
        <i>C:\Program Files\Apache Software Foundation\Tomcat 5.0</i>
        <screen>
        <note>Open the command prompt and cd to bin folder</note>
        <type>cd C:\Program Files\Apache Software Foundation\Tomcat 5.0\bin</type>
        <note>Copy the isapi_redirector2.dll and install4iis.js to that folder</note>
        <type>cscript install4iis.js</type>
        </screen>
        </p>
        <p>        
        You may modify the default installation using various command line options.
        To see what the options are type <b>csrcipt install4iis.js -h</b>        
        </p>
        <p>
        That's all, you should now start Tomcat and ask IIS to serve you the /examples context. 
        Try <a href="http://localhost/examples/jsp/index.html">http://localhost/examples/jsp/index.html</a> for example and 
        execute some of the JSP examples. 
        </p>        
    </subsection>
    <subsection name="Lotus Domino">
	<p><i>At the time of writing these instruction are applicable to Windows only.
	As soon as there are versions of the Domino redirector available for other
	platforms these instructions will be updated.</i></p>
	
	<p>If necessary build dsapi_redirector2.dll as per the instructions in the
	jk/native2/server/dsapi directory. Copy the DLL into the Domino program
	directory (this is the directory, which may be called something like
	C:\Lotus\Domino, that contains a file called nlnotes.exe). Shortly we will
	tell Domino where to find this file, but before we do that we need to make
	some registry entries. The simplest way is to edit the supplied file
	dsapi_redirector2.reg, which initially will look like this</p>
	
	<screen>
	    <read>Windows Registry Editor Version 5.00</read>
  	    <read></read>
	    <read>[HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Dsapi Redirector\2.0]</read>
	    <read>"serverRoot"="D:\\Works\\Tomcat\\jakarta-tomcat-4.1.27"</read>
	    <read>"workersFile"="conf\\workers2.properties"</read>
	    <read>"tomcatStart"="bin\\startup.bat"</read>
	    <read>"tomcatStop"="bin\\shutdown.bat"</read>
	    <read>"tomcatTimeout"="30000"</read>
	</screen>

	<p>Change serverRoot to reflect the location of your Tomcat installation. The
	other filename parameters can either be relative to serverRoot or absolute
	paths. Once edited double click on dsapi_redirector2.reg to enter it into the
	registry.</p>

	<p><b>Starting Tomcat:</b> The last three registry entries above provide
	commands that the redirector DLL will use to start and stop Tomcat when the
	Domino http server starts and stops respectively. If you don't require this
	behaviour these two lines can be omitted (or deleted if you've already placed
	them in the registry).</p>

	<p><b>The Workers file:</b> If necessary take the sample workers2.properties
	file from jakarta- tomcat- connectors\jk\conf and place it in the location
	specified in the registry settings above (typically the conf directory of your
	Tomcat installation). Edit the file to suit your Tomcat setup.</p>

	<p><b>Configuring Domino:</b> Finally we need to configure Domino to use the
	DSAPI extension DLL. For those who are unfamiliar with Domino server
	configuration most of a server's configurable behavior is dictated by a
	document called the "server document" in a database called the "Public Name
	and Address Book" or "NAB" for short (N.B. Lotus have renamed the NAB to
	"Domino Directory" from Domino 5 onwards). Each Domino server will have a NAB
	(called names.nsf) and each NAB will have a number of server documents
	including one for the current server. If you have not previously configured a
	Domino server you may need to refer to the supplied documentation, or you may
	need to pass this document to your tame Domino administrator.</p>

	<p>Assuming you know your way around a Domino server document what we're going
	to do is actually quite simple. Open the server document for this server,
	place it in Edit mode, then locate the DSAPI section and the 'DSAPI filter
	file names' field on the Internet Protocols tab, HTTP sub- tab. Add
	"dsapi_redirector2.dll" to the DSAPI field, then save and close the
	document.</p>

	<p><b>Restart Domino:</b> In order to get these settings to take effect and
	make sure that you haven't disrupted anything else you should now restart the
	Domino server. If the server is running as a service and you have changed any
	relevant system variables (JAVA_HOME, TOMCAT_HOME, CLASSPATH) since the last
	time you restarted the computer you should do a complete restart now because
	updates to system variables are not seen by services until after a reboot. If
	all goes well you should see something like this on the server console when
	the web server starts up.</p>

	<screen>
	    <read>14/11/2003 13:02:18   Attempting to start Tomcat: D:\...\startup.bat</read>
	    <read>Using CATALINA_BASE:   D:\Works\Tomcat\jakarta-tomcat-4.1.27</read>
	    <read>Using CATALINA_HOME:   D:\Works\Tomcat\jakarta-tomcat-4.1.27</read>
	    <read>Using CATALINA_TMPDIR: D:\Works\Tomcat\jakarta-tomcat-4.1.27\temp</read>
	    <read>Using JAVA_HOME:       C:\JBuilder8\jdk1.4</read>
	    <read>14/11/2003 13:02:18   Apache Tomcat Interceptor (Jakarta/DSAPI/2.0.0) loaded</read>
	    <read>14/11/2003 13:02:19   HTTP Web Server started</read>
	</screen>

	<p>At about the same time Tomcat should open in a new window (assuming you
	enabled the autostart option in the registry settings). You should now be able
	to visit a URL that is handled by Tomcat. Something like</p>

	<p><code>http://name-of-server/servlet/SnoopServlet</code></p>

	<p>may be available, depending on how Tomcat is configured. If that all works
	you're done.</p>

	<p><b>Mailing Lists:</b> There are two mailing lists dedicated to the Domino
	Tomcat redirector:</p>

	<p><a href="http://nomen.tagish.co.uk/mailman/listinfo/domino-tomcat-l">domino-tomcat-l</a></p>

	<p><b>domino-tomcat-l</b> is a general discussion list for issues with the
	redirector and also wider Tomcat/Domino integration issues such as calling the
	Domino Java API from a Tomcat servlet. This list is fairly low volume so
	please subscribe if you're actively using the redirector. If you have an issue
	with the redirector please post it to the list where it will be seen not only
	by the author but by other users who may be able to help with any problems.</p>

	<p><a href="http://nomen.tagish.co.uk/mailman/listinfo/domino-tomcat-announce-l">domino-tomcat-announce-l</a></p>

	<p><b>domino-tomcat-announce-l</b> is for announcements about the Domino Tomcat
	redirector. Mainly this list will be used for new releases but serious
	bugs will also be posted to it. This list will be very low volume; not more than
	a few posts per month. For this reason if you'd like to keep track of new redirector versions
	please subscribe to this list.</p>
  
    </subsection>
  </section>
</document>