Caucho Technology

resin web server

This document describes how to install and run Resin "standalone" (without Apache or IIS).

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

HTTP Server Overview

browser <-> Resin httpd/servlets,beans <- html,jsp

The server listens at port 8080 in the default configuration and can be changed to the HTTP port 80 during deployment.

Unix, Linux, and Mac OS X

Getting Started

The following steps will start Resin for development:

  1. Install JDK 1.6 or later and link /usr/java to the Java home or define the environment variable JAVA_HOME.
  2. tar -vzxf resin-4.0.x.tar.gz
  3. cd resin-4.0.x
  4. ./configure --prefix=`pwd`
  5. make
  6. make install
  7. Execute bin/ console
    • Or run java -jar lib/resin.jar console
  8. Browse to http://localhost:8080
Successful Foreground Startup Output
unix> bin/ console
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}  = 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    = (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

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/resin to the current Resin directory. 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.xml 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/
  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.

Startup Script

If you installed using the .deb package or ran "sudo make install", the installer created a file named/etc/init.d/resinwhich contains a standard Unix init.d startup file. This file will start Resin when invoked as:

/etc/init.d/resin start

Use the tools that came with your system to execute the script on startup.

Or you can create your own startup script which will start and stop theResinWatchdog, and will pass anycommand-line arguments. The script might 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 ResinWatchdog.

The start script might look like:

Example script



export JAVA_HOME

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

This script would be called as./ startto start and./ stopto stop.

The-serverargument is only necessary if you have multiple servers (JVM instances) either on different machines or the same machine. Theload balancinganddistributed sessionspages describe when you might use-server.


Getting Started

  1. Install JDK 1.6 or later.
  2. Check that the environment variable JAVA_HOME is set to the JDK location, e.g. c:\java\jdk1.6.0_14
  3. Unzip
  4. Define the environment variable RESIN_HOME to the location of Resin, for example c:\resin-4.0.x
  5. Execute resin.exe
  6. Browse to http://localhost:8080
Starting on Win32
May 6, 2011 4:41:28 PM com.caucho.boot.WatchdogChildTask run
INFO: WatchdogChild[] starting
May 6, 2011 4:41:28 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 16:41:29 -0400 (EDT)

[11-05-06 16:41:29.895] {main} Proxy Cache disk-size=1024M memory-size=64M
[11-05-06 16:41:30.083] {main}
[11-05-06 16:41:30.083] {main} Windows Vista 6.0 amd64
[11-05-06 16:41:30.083] {main} Java(TM) SE Runtime Environment 1.6.0_23-b05, Cp1252, en
[11-05-06 16:41:30.084] {main} Java HotSpot(TM) 64-Bit Server VM 19.0-b09, 64, mixed mode, Sun Microsystems Inc.
[11-05-06 16:41:30.084] {main}
[11-05-06 16:41:30.084] {main}  = caucho
[11-05-06 16:41:30.327] {main}
[11-05-06 16:41:30.329] {main} server listening to
[11-05-06 16:41:30.337] {main}
[11-05-06 16:41:30.604] {main}
[11-05-06 16:41:30.604] {main} resin.home = C:\resin-pro-4.0.17
[11-05-06 16:41:30.605] {main} resin.root = C:\resin-pro-4.0.17
[11-05-06 16:41:30.605] {main} resin.conf = C:\resin-pro-4.0.17\conf\resin.xml
[11-05-06 16:41:30.605] {main}
[11-05-06 16:41:30.605] {main} server    = (app-tier:default)
[11-05-06 16:41:30.605] {main} stage      = production
[11-05-06 16:41:31.037] {main} WebApp[production/webapp/default/resin-admin] active
[11-05-06 16:41:31.573] {main} WebApp[production/webapp/default/resin-doc] active
[11-05-06 16:41:31.648] {main} WebApp[production/webapp/default/ROOT] active
[11-05-06 16:41:31.648] {main} Host[production/host/default] active
[11-05-06 16:41:31.649] {main} ProServer[id=default,cluster=app-tier] active
[11-05-06 16:41:31.649] {main}   JNI keepalive: not available on Windows
[11-05-06 16:41:31.649] {main}   JNI: file, socket
[11-05-06 16:41:31.649] {main}
[11-05-06 16:41:31.649] {main}
[11-05-06 16:41:31.650] {main} http listening to *:8080
[11-05-06 16:41:32.022] {main} https listening to *:8443
[11-05-06 16:41:32.038] {main}
[11-05-06 16:41:32.057] {main} ProResin[id=default] started in 2774ms

Deploying as a Windows Service

To install the service runsetup.exe

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

Running Resin

Processes Overview

Resin runs as multiple processes that begin with the following JVM command:

unix> bin/ /usr/local/resin/lib/resin.jar \
           -conf /etc/resin/resin.xml \

The-jarargument tells java to run the Main-Class defined in resin.jar's manifest. The-confargument specifies the path to your Resin configuration file. Lastly, Resin acceptsstart,stop, andrestartarguments which are passed to thewatchdog process. An additional command-line option,-serveris used inload-balanced deployments.

JDK 1.6 includes ajpscommand which will show the pids of any java processes.

Example jps Process List
unix> jps
2098 Jps
2064 ResinWatchdogManager
2097 Resin

When running as a daemon (eg, start)ResinWatchdogManageris the watchdog andResinis the actual Resin instance. When running Resin as a foreground process, the process list displaysresin.jar, which acts as the watchdog.

The first process that starts is the actual startup program,java -jar resin.jar. It passes command-line arguments to the second process, the ResinWatchdogManager. This watchdog process takes care of starting the actual Resin process(es). ResinWatchdogManager monitors the state of Resin and restarts it if necessary, improving reliability.

java resin.jar start: ResinBoot -> ResinWatchdog -> Resin

The Watchdog Process

The ResinWatchdogManager is the parent process, providing automatic restarting Resin in cases of failure, and providing a single point of control for thestart,stopandrestartof all Resin processes. It is responsible for launching Resin with the correct JVM arguments and environment options such as starting Resin as the specified user, e.g. for <user-name> on unix.

ResinWatchdogManager watches Resin via a Socket connection. When the watchdog socket closes, Resin shuts itself down gracefully. The watchdog closes the socket on astoporrestartor if the watchdog itself is killed. If Resin exits for any reason, the watchdog will automatically start a new Resin process. This socket connection approach avoids the need for any signals or actual killing of Resin from the watchdog, and also makes it easy to stop all the Resins if necessary by just killing the watchdog.

The ResinWatchdogManager doesn't actually kill Resin or even check Resin's status, it just checks to see if Resin is alive or not. So if the JVM were to completely lock up, the watchdog would still think Resin was okay and would take no action.

Resin Processes

If Resin detects a major error (like running out of memory) or if the resin.xml changes, it will exit and the watchdog would start a new Resin instance. Reasons a Resin instance might exit include:

  • resin.xml changes
  • out of memory error
  • detected deadlocks
  • segv and other severe errors

Because the watchdog is always managing Resin processes, if you ever need to stop Resin withkill, you must kill the watchdog. Just killing the Resin process results in the watchdog restarting it automatically.


The watchdog will log tolog/watchdog-manager.log. The Resin standard out/err islog/jvm-servername.log. ResinWatchdogManager is responsible for creating both of these log files, sojvm-servername.logis not really under the control of the Resin instance. This makes it somewhat more reliable in case of JVM deadlocks, etc.

Copyright © 1998-2011 Caucho Technology, Inc. All rights reserved.
Resin ® is a registered trademark, and Quercustm, Ambertm, and Hessiantm are trademarks of Caucho Technology.