<s1 title="Resin with Netscape">

<summarylist/>

<p>Resin provides a fast servlet runner for Netscape, allowing Netscape
to run servlets, JSP and XTP files.</p>

<p>To configure Resin with Netscape, you must follow the following steps:</p>
<ol>
<li>Compile caucho_nsapi.so
<li>Configure Netscape
<li>Configure resin.conf
<li>Restart Netscape and start srun
</ol>

<s2 title='Compiling caucho_nsapi.so'>

<p>To compile and install <var/caucho_nsapi/> on Unix, you'll need to run
<code/configure/> and then make.</p>

<p>The argument to --with-netscape is the directory containing the netscape
start and stop scripts, i.e. the parent of the config directory.</p>

<example>
unix> ./configure --with-netscape=/usr/local/netscape/https-your-hostname
unix> make
</example>

<p>If you need finer control over the Netscape configuration, you can use
the following arguments to ./configure.  Resin needs
<var/netscape-include/> and <var/netscape-conf/>.</p>

<deftable>
<tr><td>--with-netscape=dir<td>The Netscape root directory.
<tr><td>--with-netscape-include=dir<td>The Netscape include directory.
<tr><td>--with-netscape-conf=conf<td>The Netscape obj.conf file
</deftable>

</s2>

<s2 title='Configuring Netscape by hand'>

<p>Making caucho_nsapi will automatically change your obj.conf file.
For reference, here are the changes:</p>

<example title=magnus.conf>
Init fn="load-modules" shlib="&lt;build-dir>/caucho_nsapi.so" \
   funcs="caucho_service,caucho_filter,caucho_status"
</example>

<example title=obj.conf>
&lt;Object name=default>
NameTrans fn="caucho_filter" conf="&lt;resin-home>/resin.conf" name="resin"
NameTrans fn="assign-name" from="/caucho-status" name="caucho-status"
...
&lt;/Object>

&lt;Object name="resin">
Service fn="caucho_service"
&lt;/Object>
&lt;Object name="caucho-status">
Service fn="caucho_status"
&lt;/Object>

</example>

<note>Versions prior to iPlanet 6 put the <var/Init/> in obj.conf. </note>

<note>The caucho-status is optional and probably should be avoided in
a production site.  It lets you ask plugin module about the
Caucho status, valuable for debugging.</note>

<p>Restart Netscape.  Now browse http://localhost/caucho-status.  It
should return a table indicating that the servlet runner is stopped.</p>

<p>Browse http://localhost/test.jsp.  It should return a message like:</p>
<results>
Cannot connect to Servlet Runner.
</results>

<s3 title='Load Balancing' version='Resin 1.2'>

<p>In Resin 1.2, you can distribute requests to multiple machines.  All
requests in a session will go to the same host.  In addition, if one
host goes down, Resin will send the request to the next available machine.
<p/>

<p>In addition, you can specify backup machines.  The backup only will serve
requests if all primaries are down.</p>

<p>See the <a href='http-config.xtp'>http config</a> section for more
details.</p>

<example title=resin.conf>
&lt;caucho.com>
&lt;http-server>
  &lt;srun id="a"host='host1' port='6802'/>
  &lt;srun id="b" host='host2' port='6802'/>
  &lt;srun-backup id="c" host='backup port='6802'/>
  ...
&lt;/http-server>
&lt;/caucho.com>
</example>
</s3>
</s2>

<s2 title='Configuring resin.conf'>

<p>By default, Resin will look in resin1.2/doc for JSP files and
resin1.2/doc/WEB-INF/classes for servlets and beans.  To tell Resin
to use Netscape's document area, you configure the <var/app-dir/>.
Change <var/app-dir/> from 'doc' to something like '/usr/local/netscape/doc'.
</p>

<example title='resin.conf'>
&lt;caucho.com>
  &lt;http-server
      app-dir='/usr/local/netscape/docs'>
    &lt;servlet-mapping url-pattern='/servlets/*'
              servlet-name='invoker'/>

    &lt;servlet-mapping url-pattern='*.xtp'
                        servlet-name='com.caucho.jsp.XtpServlet'/>
    &lt;servlet-mapping url-pattern='*.jsp'
                        servlet-name='com.caucho.jsp.JspServlet'/>
  &lt;/http-server>
&lt;/caucho.com>
</example>

</s2>

<s2 title="Netscape's obj.conf">

<p>Installing Resin with Netscape modifies Netscape's obj.conf file.  For most
users, the default installation will be fine.  More sophisticated users
will need to modify the obj.conf file.
</p>

<example>
Init fn=load-types mime-types=mime.types
# load resin shared library
Init fn="load-modules" shlib="/home/resin/libexec/caucho_nsapi.so" \
     funcs="caucho_service,caucho_filter,caucho_status"

&lt;Object name=default>
# you can change the conf value
NameTrans fn="caucho_filter" conf="/home/resin/conf/resin.conf" name="resin"
# comment out the following in production sites
NameTrans fn="assign-name" from="/caucho-status" name="caucho-status"
NameTrans fn=pfx2dir from=/ns-icons dir="/usr/local/src/nes/ns-icons" name="es-internal"
NameTrans fn=pfx2dir from=/mc-icons dir="/usr/local/src/nes/ns-icons" name="es-internal"

...
&lt;/Object>

...

&lt;Object name="resin">
Service fn="caucho_service"
&lt;/Object>

&lt;Object name="caucho-status">
Service fn="caucho_status"
&lt;/Object>
</example>
</s2>

<s2 title='Testing the servlet engine'>

<p>
Now you need to start the servlet engine.</p>
<example>
> resin2.0/bin/httpd.sh
</example>

<p>Now browse http://localhost/test.jsp.  You should get a 'file not
found' message.<p/>

<p>Create a test file '/usr/local/netscape/htdocs/test.jsp'</p>

<example>
2 + 2 = &lt;%= 2 + 2 %>
</example>

<p>Browse http://localhost/test.jsp again.  You should now get</p>

<results>
2 + 2 = 4
</results>

</s2>

<s2 title='Servlet Engine Production'>

<p>A better way to run the servlet engine in a production environment is
to use the start and stop scripts.  These scripts add extra
reliability to the server.  If Resin should ever exit, it will
automatically be restarted.</p>

<p>To start the servlet runner, use</p>

<example>
unix> resin-2.1.0/bin/httpd.sh start
</example>

<p>To stop it, use</p>

<example>
unix> resin2.0/bin/httpd.sh stop
</example>

</s2>

<s2 title='Windows'>

<p>On Windows, the setup program should configure the obj.conf.  Except that
you don't need to compile the plugin on windows, the configuration is
identical.</p>

</s2>
</s1>