<document>
  <header>
    <product>resin</product>
    <version>Resin 3.2</version>
    <title>Resin Web Server</title>
    <description>
      <p>This document describes how to install and run Resin
        "standalone" (without Apache or IIS).</p>
      <p>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.</p>
    </description>
  </header>
  <body>
    <localtoc/>

<s1 title="HTTP Server Overview">

<figure src="httpd.gif" alt="browser <-> Resin httpd/servlets,beans <- html,jsp"/>

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

<s1 title="Unix, Linux, and Mac OS X">

<s2 title="Getting Started">

<p>The following steps will start Resin for development:</p>

<ol>
<li>Install JDK 1.6 or later and link /usr/java to the Java home or define the 
environment variable <var>JAVA_HOME</var>.</li>
<li><code>tar -vzxf resin-4.0.x.tar.gz</code></li>
<li><code>cd resin-4.0.x</code></li>
<li><code>./configure --prefix=`pwd`</code>
  <ul><li>some <a href="starting-resin-command-line.xtp">./configure options</a> are available</li></ul>
</li>
<li><code>make</code></li>
<li><code>make install</code></li>
<li>Execute <code>bin/resin.sh console</code>
  <ul><li>Or run <code>java -jar lib/resin.jar console</code></li></ul>
</li>
<li>Browse to <a href="http://localhost:8080">http://localhost:8080</a></li>
</ol>
<example title="Successful Foreground Startup Output">
unix> bin/resin.sh 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} 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
</example>

</s2>

<s2 name="deploy" title="Deployment Directories">

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

<ol>
<li>Create a user to run Resin (e.g. <var>resin</var> or another non-root user)</li>
<li>Link <var>/usr/local/resin</var> to the current Resin directory. This is <var>$RESIN_HOME</var>.</li>
<li>Create a deployment root, e.g. <var>/var/www</var>, owned by the resin user. This is <var>$RESIN_ROOT</var>.</li>
<li>Put the modified <var>resin.xml</var> in <var>/etc/resin/resin.conf</var></li>
<li>Put the site documents in <var>/var/www/webapps/ROOT</var>.</li>
<li>Put any .war files in <var>/var/www/webapps</var>.</li>
<li>Put any virtual hosts in <var>/var/www/hosts/www.foo.com</var>.
  <ul><li>Refer to <a href="http-virtual-hosts.xtp">virtual hosts</a> for more information.</li></ul>
</li>
<li>Output logs will appear in <var>/var/www/log</var>.</li>
<li>Create a startup script and configure the server to start it when the machine reboots.</li>
</ol>

</s2>

<s2 name="script" title="Startup Script">

<p>If you installed using the .deb package or ran "<code>sudo make install</code>", 
the installer created a file named <var>/etc/init.d/resin</var>
which contains a standard Unix init.d startup file.  This file will start
Resin when invoked as:
</p>
<example>
/etc/init.d/resin start
</example>
<p>Use the tools that came with your system to execute the script
on startup.  
</p>

<p>Or you can create your own startup script which will start and stop
the <a href="#Running Resin">ResinWatchdog</a>, and will pass any <a href="#command-line">command-line arguments</a>.  The script
might typically do a number of things:</p>

<ol>
<li>Configure the location of Java in <var>JAVA_HOME</var></li>
<li>Configure the location of Resin in <var>RESIN_HOME</var></li>
<li>Configure your web site directory in <var>RESIN_ROOT</var></li>
<li>Select a server and pid file if you have multiple Resin servers.</li>
<li>Start and stop the <a href="#Running Resin">ResinWatchdog</a>.</li>
</ol>

<p>The start script might look like:</p>

<example title="Example start.sh script">
#!/bin/sh

JAVA_HOME=/usr/java
RESIN_HOME=/usr/local/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 \
      -root-directory $RESIN_ROOT \
      -conf /etc/resin/resin.xml \
      -server a \
       $*
</example>

<p>This script would be called as <code>./start.sh start</code> to start
and <code>./start.sh stop</code> to stop.</p>

<p>The <code>-server</code> argument is only
necessary if you have multiple servers (JVM instances) either
on different machines or the same machine.
The <a href="clustering-overview.xtp">load balancing</a> and
<a href="deploy-ref.xtp#session-config">distributed sessions</a> pages describe when
you might use <code>-server</code>.</p>

<!--
<p>More information on deploying on Unix is available on the
<a href="linux-boot.xtp">Linux boot</a> documentation.</p>
-->

</s2>

</s1>

<s1 title="Windows">

<s2 title="Getting Started">

<ol>
<li>Install JDK 1.6 or later.</li>
<li>Check that the environment variable <var>JAVA_HOME</var> is set to the JDK 
location, e.g. <code>c:\java\jdk1.6.0_14</code></li>
<li>Unzip resin-4.0.x.zip</li>
<li>Define the environment variable <var>RESIN_HOME</var> to the location of
Resin, for example <code>c:\resin-4.0.x</code></li>
<li>Execute <code>resin.exe</code></li>
<li>Browse to <a href="http://localhost:8080">http://localhost:8080</a></li>
</ol>

<example title="Starting on Win32">
C:\resin-pro-4.0.17>resin.exe
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} user.name  = caucho
[11-05-06 16:41:30.327] {main}
[11-05-06 16:41:30.329] {main} server listening to 127.0.0.1:6800
[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    = 127.0.0.1:6800 (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
</example>

</s2>

<s2 title="Deploying as a Windows Service">

<p>To install the service run <var>setup.exe</var></p>

<p>You will either need to reboot the machine or start the service
from the Control&#160;Panel/Services panel to start the server.  On a
machine reboot, Windows will automatically start the web server.</p>

<p>You can also start and stop the service from the command-line:</p>

<example>
C:\&gt; net start resin
...
C:\&gt; net stop resin
</example>

</s2>
</s1>

<s1 title="Running Resin">
<s2 title="Processes Overview">
<p>Resin runs as multiple processes that begin with the following JVM command:</p>

<example>
unix> bin/resin.sh /usr/local/resin/lib/resin.jar \
           -conf /etc/resin/resin.xml \
           start
</example>

<p>The <var>-jar</var> argument tells java to run the Main-Class defined
in resin.jar's manifest. The <var>-conf</var> argument specifies the 
path to your Resin configuration file. Lastly, Resin accepts <var>start</var>,
<var>stop</var>, and <var>restart</var> arguments which are passed to the <a href="#The Watchdog Process">watchdog
process</a>. An additional command-line option, <var>-server</var> is used
in <a href="clustering-overview.xtp">load-balanced deployments</a>.</p>

<p>JDK 1.6 includes a
<a href="http://download.oracle.com/javase/6/docs/technotes/tools/share/jps.html">jps</a>
command which will show the pids of any java processes.</p>

<example title="Example jps Process List">
unix&gt; jps
2098 Jps
2064 ResinWatchdogManager
2097 Resin
</example>

<p>When running as a daemon (eg, <code>resin.sh start</code>)
<var>ResinWatchdogManager</var> is the watchdog and <var>Resin</var>
is the actual Resin instance. When running Resin as a foreground process,
the process list displays <var>resin.jar</var>, which acts as the watchdog.</p>

<p>The first process that starts is the actual startup program,
<code>java -jar resin.jar</code>. 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.</p>

<figure src="startup-watchdog.png" alt="java resin.jar start: ResinBoot -> ResinWatchdog -> Resin"/>

</s2>

<s2 title="The Watchdog Process">
<p>The ResinWatchdogManager is the parent process, providing automatic restarting
Resin in cases of failure, and providing a single point of control for
the <var>start</var>, <var>stop</var> and <var>restart</var> 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 &lt;<a config-tag="user-name"/>&gt; on unix.</p>

<p>ResinWatchdogManager watches Resin via a Socket connection. When
the watchdog socket closes, Resin shuts itself down gracefully. The 
watchdog closes the socket on a <var>stop</var> or <var>restart</var>
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.</p>

<p>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.</p>
</s2>

<s2 title="Resin Processes">
<p>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:</p>

<ul>
  <li>resin.xml changes</li>
  <li>out of memory error</li>
  <li>detected deadlocks</li>
  <li>segv and other severe errors</li>
</ul>

<p>Because the watchdog is always managing Resin processes, if you ever
need to stop Resin with <var>kill</var>, you must kill the watchdog. Just killing
the Resin process results in the watchdog restarting it automatically.</p>
</s2>

<s2 title="Logging">

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

</s1>

  </body>

</document>
