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 your 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
   • some ./configure options are available
5. Run java -jar resin/lib/resin.jar
   • Or run 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

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 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.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.

Startup Script

You can create your own startup script which will start and stop the ResinWatchdog, and will pass any command-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:

#!/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 \
       $*

This 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 on the Linux boot documentation.

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 view them in the control panel, under the executable string.

With multiple named 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

Running Resin

Processes Overview

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

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

The -jar argument tells java to run the Main-Class defined in resin.jar's manifest. The -conf argument specifies the path to your Resin configuration file. Lastly, Resin accepts start, stop, and restart arguments which are passed to the watchdog process. An additional command-line option, -server is used in load-balanced deployments.

JDK 1.5 includes a jps command which will show the pids of any java processes.

unix> jps
2098 Jps
2064 ResinWatchdogManager
2097 Resin

When running as a daemon (eg, httpd.sh start) ResinWatchdogManager is the watchdog and Resin is the actual Resin instance. When running Resin as a foreground process, the process list displays resin.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.

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 the start, stop and restart of 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 a stop or restart or 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.conf changes, it will exit and the watchdog would start a new Resin instance. Reasons a Resin instance might exit include:

• resin.conf 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 with kill, you must kill the watchdog. Just killing the Resin process results in the watchdog restarting it automatically.

Logging

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