Resin Documentation

resin with apache

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

If you have not yet done so, we suggest you use the Resin standalone web server option first.

Before integrating Resin with Apache, it is valuable to configure Resin as a standalone server, especially with more complicated setups such as those involving virtual hosts. Doing so isolates the steps and makes troubleshooting easier.

Many users find that the performance, flexibility, and features of Resin make Resin a desirable replacement for Apache.

When used with Apache, Resin serves JSPs and Servlets and Apache serves static content like html and images. Apache is a frontend server, it handles the request from the browser. Resin's mod_caucho plugin integrates with Apache, it dispatches requests for JSPs and Servlets to one or more backend Resin servers.

mod_caucho queries the backend server to distinguish the URLs going to Resin from the URLs handled by Apache. The backend server uses the <servlet-mapping> directives to decide which URLs to send. Also, any *.war file automatically gets all its URLs. Other URLs stay with Apache.

There's a more complete discussion of the URL dispatching in the How the Plugins Dispatch to Resin page.

Resin needs Apache 1.3.x or greater and DSO support.

To configure Resin with Apache, you must follow the following steps:

1. Compile Apache
2. Compile mod_caucho.so
3. Configure Apache
4. Set up environment
5. Configure resin.xml
6. Restart Apache and start the backend Resin server

unix> /usr/local/apache/bin/httpd -l
Compiled-in modules:
  ...
  mod_so.c
  ...
 

unix> ./configure --prefix=/usr/local/apache --enable-module=so
unix> make
unix> make install

unix> ./configure --prefix=/usr/local/apache \
                  --enable-rule=SHARED_CORE \
                  --enable-rule=SHARED_CHAIN \
                  --enable-module=so \
                  --enable-module=most \
                  --enable-shared=max

unix> ./configure --with-apxs=/usr/local/apache/bin/apxs
unix> make

unix> ./configure --with-apxs
unix> make

unix> ./configure --with-apache=/usr/local/apache
unix> make
unix> make install

# Java Location
JAVA_HOME=/usr/java
export JAVA_HOME

# Resin location (optional).  Usually Resin can figure this out.
RESIN_HOME=/usr/local/share/resin
export RESIN_HOME

# If you're using additional class libraries, you'll need to put them
# in the classpath.
CLASSPATH=

The setup.exe program installs the mod_caucho.dll plugin for any Apache it finds, and modifies the Apache httpd.conf file.

The httpd.conf file is also easily modified manually:

LoadModule caucho_module \
    <installdir>/resin-pro-4.0.17/win32/apache-2.2/mod_caucho.dll

ResinConfigServer localhost 6800
<Location /caucho-status>
  SetHandler caucho-status
</Location>

The communication between mod_caucho and the backend Resin server takes place using a server port.

The resin.xml for the backend server contains a server to enable the port. The default resin.xml has an server listener on port 6800.

<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">

  ...


  <cluster id="app-tier">

    ...

    <server id="" address="127.0.0.1" port="6800"/>

    ...

The resin.xml and the layout of your webapps should match the layout that Apache expects. The mapping of urls to filesystem locations should be consistent between Apache and the backend Resin server.

The default resin.xml looks in resin-4.0.x/webapps/ROOT for JSP files and resin-4.0.x/webapps/ROOT/WEB-INF/classes for servlets and java source files. To tell Resin to use Apache's document area, you configure an explicit web-app with the appropriate document-directory:

<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">

  ...

  <server>

    ...

    <host id="">
 
      <web-app id='/' document-directory="/usr/local/apache/htdocs"/>

    </host>

    ...

  </server>
</resin>

Now you need to start the app-tier Resin server. Starting Resin is the same with Apache or standalone. See the Resin Web Server page for a detailed description.

unix> $RESIN_HOME/bin/resin.sh start 

unix> bin/resin.sh start

win> resin.exe

May 6, 2011 3:06:05 PM com.caucho.boot.WatchdogChildTask run
INFO: WatchdogChild[] starting
May 6, 2011 3:06:05 PM com.caucho.boot.WatchdogChildProcess run
WARNING: Watchdog starting Resin[]
Resin Professional 4.0.17 (built Fri, 15 Apr 2011 06:35:56 PDT)
Copyright(c) 1998-2010 Caucho Technology.  All rights reserved.

  current.license -- 1 Resin server Caucho

Starting Resin Professional on Fri, 06 May 2011 15:06:06 -0400 (EDT)

[11-05-06 15:06:07.824] {main} Proxy Cache disk-size=1024M memory-size=64M
[11-05-06 15:06:08.179] {main} 
[11-05-06 15:06:08.179] {main} Mac OS X 10.6.7 x86_64
[11-05-06 15:06:08.179] {main} Java(TM) SE Runtime Environment 1.6.0_24-b07-334-10M3326, MacRoman, en
[11-05-06 15:06:08.179] {main} Java HotSpot(TM) 64-Bit Server VM 19.1-b02-334, 64, mixed mode, Apple Inc.
[11-05-06 15:06:08.179] {main} 
[11-05-06 15:06:08.179] {main} user.name  = caucho
[11-05-06 15:06:08.472] {main} 
[11-05-06 15:06:08.479] {main} server listening to localhost:6800
[11-05-06 15:06:08.555] {main} 
[11-05-06 15:06:08.873] {main} 
[11-05-06 15:06:08.874] {main} resin.home = /Users/caucho/resin-pro-4.0.17/
[11-05-06 15:06:08.878] {main} resin.root = /Users/caucho/resin-pro-4.0.17/
[11-05-06 15:06:08.879] {main} resin.conf = /Users/caucho/resin-pro-4.0.17/conf/resin.xml
[11-05-06 15:06:08.889] {main} 
[11-05-06 15:06:08.889] {main} server    = 127.0.0.1:6800 (app-tier:default)
[11-05-06 15:06:08.899] {main} stage      = production
[11-05-06 15:06:09.526] {main} WebApp[production/webapp/default/resin-admin] active
[11-05-06 15:06:10.245] {main} WebApp[production/webapp/default/resin-doc] active
[11-05-06 15:06:10.445] {main} WebApp[production/webapp/default/ROOT] active
[11-05-06 15:06:10.446] {main} Host[production/host/default] active
[11-05-06 15:06:10.447] {main} ProServer[id=default,cluster=app-tier] active
[11-05-06 15:06:10.448] {main}   JNI: file, nio keepalive (max=9984), socket
[11-05-06 15:06:10.448] {main} 
[11-05-06 15:06:10.449] {main} 
[11-05-06 15:06:10.450] {main} http listening to *:8080
[11-05-06 15:06:11.023] {main} https listening to *:8443
[11-05-06 15:06:11.092] {main} 
[11-05-06 15:06:11.160] {main} ProResin[id=default] started in 4222ms

Resin will print every port it's listening to. In the above example, Resin has an http listener on port 8080 and an server listener on port 6800 (using its custom 'hmux' protocol). mod_caucho establishes connections to Resin using port 6800, and a web browser can connect using port 8080. Usually the 8080 port will be unused, because web browsers will make requests to Apache, these requests get dispatched to Resin as needed by mod_caucho. A Resin configured http listener on port 8080 is a useful debugging tool, it allows you to bypass Apache and make a request straight to Resin.

The following snippet shows the <http> and <<server>> configuration for the above example.

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="app-tier">
    <server-default>
      <http address="*" port="8080"/>
    </server-default>

    <server id="" address="192.168.2.10" port="6800"/>

    ...
  </cluster>
</resin>

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

2 + 2 = <%= 2 + 2 %>

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

2 + 2 = 4

The installation process above automatically changes the httpd.conf file. You can also configure the httpd.conf file manually, or modify the default configuration created by the installation process.

LoadModule caucho_module libexec/mod_caucho.so

ResinConfigServer localhost 6800
<Location /caucho-status>
  SetHandler caucho-status
</Location>

LoadModule caucho_module \
    <installdir>/resin-pro-4.0.17/win32/apache-2.2/mod_caucho.dll

ResinConfigServer localhost 6800
<Location /caucho-status>
  SetHandler caucho-status
</Location>

The ResinConfigServer is used to tell mod_caucho how to contact the backend Resin server. The backend Resin server tell's mod_caucho which urls should be dispatched.

CauchoHost 127.0.0.1 6800

<Location /foo/*>
  SetHandler caucho-request
</Location>

The virtual host topic describes virtual hosts in detail. If you're using a single JVM, you only need to configure the resin.xml.

LoadModule caucho_module libexec/mod_caucho.so

ResinConfigServer 192.168.0.1 6800
<Location /caucho-status>
  SetHandler caucho-status
</Location>

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="app-tier">

  <server id="" address="192.168.0.1" port="6800"/>

  <host id='www.gryffindor.com'>
    <host-alias>gryffindor.com</host-alias>
     ...
  </host>

  <host id='www.slytherin.com'>
    <host-alias>slytherin.com</host-alias>
     ...
  </host>
</cluster>
</resin>

<VirtualHost gryffindor.com>
ServerName gryffindor.com
ServerAlias www.gryffindor.com
ResinConfigServer 192.168.0.1 6800
</VirtualHost>

<VirtualHost slytherin.com>
ServerName slytherin.com
ServerAlias www.slytherin.com
ResinConfigServer 192.168.0.1 6801
</VirtualHost>

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <server id="" address="192.168.0.1" port="6800"/>

  <host id="">
     ...
  </host>
</cluster>
</resin>

<resin xmlns="http://caucho.com/ns/resin">
<cluster>

  <server id="" address="192.168.0.1" port="6801"/>

  <host id="">
     ...
  </host>
</cluster>
</resin>

$ bin/resin.sh -pid gryffindor.pid -conf conf/gryffindor.conf start
$ bin/resin.sh -pid slytherin.pid -conf conf/slytherin.conf start

...

$ bin/resin.sh -pid gryffindor.pid stop

The Reliability and Load Balancing section provides an introduction to the concepts of load balancing.

mod_caucho recognizes cluster configurations for load balancing. Requests are distributed to all machines in the cluster, all requests in a session will go to the same host, and if one host goes down, Resin will send the request to the next available machine. Optional backup machines only receive requests if all of the primaries are down.

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="app-tier">
    <server id="a" address="192.168.0.11" port="6800" index="1"/>
    <server id="b" address="192.168.0.11" port="6801" index="2" 
             backup="true"/>
    <server id="c" address="192.168.0.12" port="6800" index="3"/>
    <server id="d" address="192.168.0.12" port="6801" index="4" 
             backup="true"/>
    ...
  </cluster>
</resin>

mod_caucho only needs to know about one of the backend servers. It will query that backend server, and learn about all of the other members of the cluster.

ResinConfigServer 192.168.0.11 6800

mod_caucho keeps a local cache of the configuration information, so if the backend server becomes unavailable then the cached configuration will be used until the backend server becomes available again.

The httpd.conf file can also specify more than one backend server, when mod_caucho checks for configuration updates, it will check each in turn, and only if none of them are available will it use the local cached copy.

ResinConfigServer 192.168.0.11 6800
ResinConfigServer 192.168.0.12 6801

CauchoHost 192.168.0.11 6800
CauchoBackup 192.168.0.11 6801
CauchoHost 192.168.0.12 6800
CauchoBackup 192.168.0.12 6801

<Location /foo/*>
  SetHandler caucho-request
</Location>

<Location /applicationA/*>
  ResinConfigServer 192.168.0.11 6800
</Location>

<Location /applicationB/*>
  ResinConfigServer 192.168.0.12 6800
</Location>

1. First, check your configuration with Resin standalone.sh. In other words, add a <http port='8080'/> and check port 8080.
2. Check http://localhost/caucho-status. That will tell if mod_caucho has properly connected to the backend Resin server.
3. Each server should be green and the mappings should match your resin.xml.
4. If caucho-status fails entirely, the problem is in the mod_caucho installation and the Apache httpd.conf.
5. If caucho-status shows the wrong mappings, there's something wrong with the resin.xml or the pointer to the backend server in httpd.conf.
6. If caucho-status shows a red servlet runner, then Resin hasn't properly started.
7. If you get a "cannot connect to servlet engine", caucho-status will show red, and Resin hasn't started properly.
8. If Resin doesn't start properly, you should look at the logs in resin-4.0.x/log. You should start resin.sh -verbose or resin.exe -verbose to get more information.
9. If Resin never shows a "hmux listening to *:6800" line, it's not listening for connections from mod_caucho. You'll need to add a <server> line.
10. If you get Resin's "file not found", the Apache configuration is good but the resin.xml probably points to the wrong directories.