Resin provides a fast web server which can be used by itself or as a load balancer. In our benchmarks, it serves static pages faster than Apache. For most sites, the Resin web server is ideal because of its performance, security and reliability.

Unix (including Linux and MacOS-X)

Getting Started

The following steps will start Resin for development:

1. Install JDK 1.5 or later and link /usr/java to the Java home or set environment variable JAVA_HOME.
2. tar -vzxf resin-3.1.0.tar.gz in /usr/local/share
3. (Optional) Link /usr/local/share/resin to the resin-3.1.0 directory.
4. ./configure; make; make install
5. Run java -jar resin/lib/resin.jar
   • Or resin/bin/httpd.sh
6. Browse http://localhost:8080

unix> java -jar resin/lib/resin.jar
Resin Professional 3.1.0 (built Fri, 08 Sep 2006 12:49:30 PDT)
Copyright(c) 1998-2006 Caucho Technology.  All rights reserved.

  001111.license - 1 Resin server Hogwarts School

Starting Resin on Tue, 12 Sep 2006 19:11:52 -0700 (PDT)

[21:22:21.282] Proxy Cache disk-size=1024M memory-size=8M
[21:22:21.477] Server[id=,cluster=app-tier] starting
[21:22:21.477] 
[21:22:21.477] Mac OS X 10.4.7 ppc
[21:22:21.477] Java 1.5.0_06-64, 32, mixed mode, sharing, MacRoman, en, "Apple Computer, Inc."
[21:22:21.477] resin.home = /usr/local/share/resin
[21:22:21.478] resin.root = /var/www
[21:22:21.478] 
[21:22:21.492] Loaded Socket JNI library.
[21:22:21.595] hmux listening to localhost:6800
[21:22:21.696] http listening to *:8080
[21:22:21.842] Host[] starting
[21:22:22.089] WebApp[] starting

./configure options

The 64-bit JNI compilation must match the JDK you're using, i.e. you'll need to use something like "-J-d64" to properly enable 64 bit JDKs.

Deployment Directories

When deploying, it's a good idea to create a bit of structure to make Resin and website upgrades easier and more maintainable.

1. Create a user to run Resin (e.g. resin or another non-root user)
2. Link /usr/local/share/resin to the current Resin version. This is $RESIN_HOME.
3. Create a deployment root, e.g. /var/www, owned by the resin user. This is $RESIN_ROOT.
4. Put the modified resin.conf in /etc/resin/resin.conf
5. Put the site documents in /var/www/webapps/ROOT.
6. Put any .war files in /var/www/webapps.
7. Put any virtual hosts in /var/www/hosts/www.foo.com.
8. Output logs will appear in /var/www/log.
9. Create a startup script and configure the server to start it when the machine reboots.

start/stop and the watchdog process

In a deployment environment, Resin will be started with "start", "stop", and "restart" arguments to the resin.jar, e.g.

unix> java -jar /usr/local/share/resin/lib/resin.jar \
           -conf /etc/resin/resin.conf \
           start

The "start" and "stop" send messages to a watchdog process which takes care of starting the actual Resin process. The watchdog monitors the state of Resin and restarts it if necessary to improve reliability.

Because of the watchdog manager, if you ever need to stop Resin with kill, you will need to kill the watchdog. If you just kill the Resin process, the watchdog will restart it automatically. JDK 1.5 includes a "jps" command which will show the pids of any java processes. The WatchdogManager is the watchdog and Resin is the Resin instance.

Starting Script

You can create your own starting script which will start and stop your Resin instance, and will pass any command-line arguments. The script will typically do a number of things:

1. Configure the location of Java in JAVA_HOME
2. Configure the location of Resin in RESIN_HOME
3. Configure your web site directory in RESIN_ROOT
4. Select a server and pid file if you have multiple Resin servers.
5. Start and stop the Resin daemon.

The start script might look like:

#!/bin/sh

JAVA_HOME=/usr/java
RESIN_HOME=/usr/local/share/resin
RESIN_ROOT=/var/www

java=$JAVA_HOME/bin/java

export JAVA_HOME
export RESIN_HOME
export RESIN_ROOT

$java -jar $RESIN_HOME/lib/resin.jar \
      -resin-root $RESIN_ROOT \
      -conf /etc/conf/resin.conf \
      -server a \
       $*

The script would be called as "./start.sh start" to start and "./start.sh stop" to stop.

The -server argument is only necessary if you have multiple servers (JVM instances) either on different machines or the same machine. The load balancing and distributed sessions pages describe when you might use -server.

More information on deploying on Unix is available at:

• Linux boot

Windows

Getting Started

1. Install JDK 1.5 or later.
2. Make sure the JDK installation set the environment variable JAVA_HOME correctly
3. Unzip resin-3.1.0.zip
4. Run java -jar resin-3.1.0/lib/resin.jar
5. Or execute resin-3.1.0/httpd.exe
6. Browse http://localhost:8080

C:\win32> resin-3.1.0\bin\httpd
Resin 3.1.0-beta (built Thu Feb 13 18:21:13 PST 2003)
Copyright(c) 1998-2002 Caucho Technology.  All rights reserved.

Starting Resin on Sat, 01 Mar 2003 19:11:52 -0500 (EST)
[19:11:56.479] ServletServer[] starting
[19:11:57.000] Host[] starting
[19:11:58.312] Application[http://localhost:8380/doc] starting
[19:12:11.872] Application[http://localhost:8380/quercus] starting

...

[19:12:12.803]http listening to *:8380
[19:12:12.933]hmux listening to *:6802

Deploying as a Windows Service

The Resin Web Server can be installed as an Windows service.

To install the service, use

C:\> resin-3.1.x\httpd -install -conf conf/myconf.conf

To remove the service, use

C:\> resin-3.1.x\httpd -remove

You will either need to reboot the machine or start the service from the Control Panel/Services panel to start the server. On a machine reboot, Windows will automatically start the web server.

You can also start and stop the service from the command-line:

C:\> net start resin
...
C:\> net stop resin

Resin's -install saves the command-line arguments and starts the service with those arguments. You can look at them in the control panel, under the executable string.

With multiple servers, you can use -install-as foo to specify the service name.

C:\> resin-3.1.x\httpd -install-as ResinA \
                       -conf conf/myconf.conf \
                       -server a
C:\> net start ResinA

Command-line arguments

Memory Configuration

Memory configuration is part of the JVM's arguments. For most JVMs, you can find the full list by starting "java -X".

JDK arguments

Resin 3.1 has moved all JDK arguments into the resin.conf file, in the <jvm-args> tag. Because the Resin 3.1 watchdog JVM starts the Resin server instance, it can pass the arguments defined in the configuration file. By moving the Java arguments to the configuration file, the site configuraion is easier and more maintainable.

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

    <server-default>
      <jvm-args>-Xmx512m</jvm-args>
      <jvm-args>-Xss1m</jvm-args>
      <jvm-args>-verbosegc</jvm-args>

      <http port="8080"/>
    </server-default>

    <server id="a" address="192.168.2.1" port="6800"/>

    ...
  </cluster>
</resin>

Load balancing

Resin's web server can scale to large loads with its load-balancing capability.

The Reliability and Load Balancing section provides more details of Resin's load balancing.

Load balancing divides the Resin servers into two clusters: the web-tier and the app-tier. In Resin 3.1, all the cluster and load balance configuration is in a single resin.conf. The actual deployed server is selected with the -server web-a command-line argument.

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

  <cluster id="web-tier">
    <server-default>
      <http port="80"/>
    </server-default>

    <server id="web-a" address="192.168.1.10" port="6800"/>

    <cache disk-size="1024m" memory-size="64m"/>

    <host id="">
      <web-app id="">

        <rewrite-dispatch>
          <load-balance regexp="" target="app-tier"/>
        </rewrite-dispatch>

      </web-app>
    </host>
  </cluster>

  <cluster id="app-tier">
    <server id="app-a" address="192.168.2.10" port="6800"/>
    <server id="app-b" address="192.168.2.11" port="6800"/>
    <server id="app-c" address="192.168.2.12" port="6800"/>

    ... <!-- hosts and web-app configuration -->
  </cluster>
</resin>

Performance vs Apache

Resin is an excellent web server for both static pages and for load-balancing to multiple backend application servers. For a web-tier server, static page performance and load-balance performance are both important, as is the ability to proxy cache pages. The following benchmarks give a quick comparison between Resin and Apache as web-tier servers: both are very close in performance, although Resin is slightly faster than Apache in most of these cases.

These results were benchmarked with Resin 3.1.0 and Apache 2.2.3 with a pair of Debian Linux machines using a 1G ethernet. Resin's proxy cache was disabled to match Apache's default no proxy-cache configuration, but no other special configurations were applied to either server.

The first set of benchmarks compare static page serving using a 1k page to simulate small image files and a 64k page to simulate normal web pages. For the small pages, Resin was about 5% faster than Apache, and for large pages, the two are essentially identical.

The second set of benchmarks compare load balancing of JSP pages to a backend Resin server. Both a 1k page and a 64k page were simulated. For comparison, the performance of Resin serving the same JSP page as a standalone HTTP server is also provided. Again, for small pages Resin is about 5-10% faster than Apache and is essentially identical for larger pages.

Caveats

As always, no artificial benchmark can replace measuring your own application with your own configuration and load. In most cases, other considerations like the application performance and database performance will dominate the performance (although proxy caching can make slow applications run as fast as static pages.) These numbers in particular are a trivial tests with a simple load. They do measure the maximum performance of the web server, so they are valuable information, but they are very different from a benchmark of a complete application.

Warnings aside, these results do indicate that many sites should seriously consider using Resin as their web-tier load-balancing server. (After benchmarking your own application, of course.)