<title css='default.css'>Caucho Servlet Engine on Apache Windows</title>

Resin provides a fast servlet runner for Apache, allowing Apache
to run servlets and JSP files.

<center>
<ct:img src='apache_srun.gif'/>
</center>

<summarylist/>

<section title='Configuring Apache'>

<p/>To configure Apache to load the Caucho Server Runner, add the
following lines to the Apache httpd.conf file:

<example title=httpd.conf>
LoadModule caucho_module &lt;installdir>/resin1.2/srun/win32-1.3.6/mod_caucho.dll
AddModule mod_caucho.c

&lt;IfModule mod_caucho.c&gt;
  CauchoConfigFile &lt;installdir>/resin1.2/resin.conf
  &lt;Location /caucho-status>
    SetHandler caucho-status
  &lt;/Location>
&lt;/IfModule&gt;
</example>

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

<subsection title='Alternate Apache Configuration'>

You can also configure Apache directly, instead of letting Caucho read
configuration from the resin.conf file.  If you use this method, you
need to make sure you match the Apache configuration with the Resin
configuration.

<example title=httpd.conf>
LoadModule caucho_module &lt;installdir>/resin1.2/srun/win32-1.3.6/mod_caucho.dll
AddModule mod_caucho.c

CauchoHost localhost 6802
AddHandler caucho-request jsp
&lt;Location /servlet/*>
   SetHandler caucho-request
&lt;/Location>
</example>
</subsection>

<subsection title="Dispatching">

mod_caucho selects URLs specified by the servlet-mapping directives to go to
Resin.  Other URLs stay with Apache.  There's a more complete
discussion of the URL dispatching in the <a
href="../java_tut/plugin-dispatch.xtp">plugin-dispatch</a> tutorial.

</subsection>
</section>
<section title='Load Balancing' version='Resin 1.2'>

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/>In addition, you can specify backup machines.  The backup only will serve
requests if all primaries are down.

<p/>See the <a href='http-config.xtp'>http config</a> section for more
details.
<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>
</section>

<section title='Error Page' version='Resin 1.2'>

When mod_caucho can't reach any JVM, it will send a default error
page.  Sites can customize the error page with the
<var/error-page/> directive in the resin.conf.

<example title=resin.conf>
...
&lt;web-app>
  &lt;error-page exception-type='connection'
              location='/conn_error_page.html'/>
  ...
&lt;/web-app>
</example>

</section>

<section title='Configuring resin.conf'>

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 Apache's document area, you configure the <var/app-dir/>.
Change <var/app-dir/> from 'doc' to something like '/usr/local/apache/htdocs'.

<example title='resin.conf'>
&lt;caucho.com>
  &lt;http-server
      app-dir='/usr/local/apache/htdocs'>
    &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>

</section>

<section title='Testing the servlet engine'>

Now you need to start the servlet engine.  From the resin1.2/bin
folder, click on srun.

<example>
> resin-2.0/bin/httpd
</example>

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

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

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

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

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

</section>

<section title='Deploying on NT'>

The Servlet Runner can be installed as an NT service.

<p/>To install the service, use

<example>
unix> resin1.2/bin/httpd -install
</example>

<p/>To remove the service, use

<example>
unix> resin1.2/bin/httpd -remove
</example>

<p/>You will either need to reboot the machine or start the service
from the Control&nbsp;Panel/Services panel to start the server.  On a
machine reboot, NT will automatically start the servlet runner.

</section>
