<document>
  <header>
    <product>resin</product>
    <resin-2.0>$resin/ref/httpd.xtp</resin-2.0>
    <version>Resin 3.0</version>
    <title>Resin Web Server</title>
    <description>
      <p>Resin provides a fast standalone web server.
        In our benchmarks, it serves static pages faster than Apache!
        For many sites, the standalone web server is ideal because of its
        performance and because it is easier to configure and maintain than
        using a separate web server.</p>

      <p>
        <figure src='httpd.gif'/>
      </p>
    </description>

  </header>

  <body>
    <summary/>

<section title='Unix (including Linux and MacOS-X)'>

<section title="Getting Started">

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

<ol>
<li>Install JDK 1.4 or later and link /usr/java to the Java home or
set environment variable JAVA_HOME.</li>
<li>tar -vzxf resin-3.0.0.tar.gz</li>
<li>(Optional) Link /usr/local/resin to the resin-3.0.0 directory.</li>
<li>./configure; make; make install
<li>Execute resin-3.0.0/bin/httpd.sh</li>
<li>Browse http://localhost:8080</li>
</ol>

<example title='Getting Started on Unix'>
unix> resin-3.0.x/bin/httpd.sh
Resin 3.0.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
</example>

</section>

<section title="./configure options">

<deftable>
<tr><td>--enable-64bit<td>Compiles the JNI using 64-bits
</deftable>

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

</section>

<section name='deploy' title='Deploying on Unix'>

<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. resin or another non-root user)</li>
<li>Link /usr/local/resin to the current Resin version.  This is $RESIN_HOME.</li>
<li>Create a deployment root, e.g. /usr/local/web, owned by
the resin user.  This is $SERVER_ROOT.</li>
<li>Put the modified resin.conf in /usr/local/web/conf/resin.conf</li>
<li>Put the site documents in /usr/local/web/doc.</li>
<li>Put any .war files in /usr/local/web/webapps.</li>
<li>Output logs will appear in /usr/local/web/log.</li>
<li>Create a startup script and configure the server to start it
when the machine reboots.</li>
</ol>

</section>

<section title="bin/httpd.sh">

<p>bin/httpd.sh uses a perl script, resin-3.0.0/bin/wrapper.pl,
to control the Java process (bin/httpd.sh is a tiny shell script
that calls wrapper.pl).  You can modify bin/httpd.sh.</p>

<p>If you need to stop Resin with <var/kill/>, you'll need to kill
the wrapper.pl process to make sure it doesn't restart Resin.  ("httpd.sh stop"
works by killing the wrapper.pl process.)
or bin/wrapper.pl for your configuration.</p>

<p>In a production environment, the "start" and "stop" arguments to
bin/httpd.sh will start and stop Resin as a Unix daemon
for extra reliability.  If Resin should ever exit,
it will automatically be restarted.</p>

</section>

<section name="script" title="Starting Script">

<p>You can create your own starting script which will start and stop
your Resin instance, and will pass any <a
href="#command-line">command-line arguments</a>.  The script
will typically do a number of things:</p>

<ol>
<li>Configure the location of Java in JAVA_HOME</li>
<li>Configure the location of Resin in RESIN_HOME</li>
<li>Configure your web site directory in SERVER_ROOT</li>
<li>Select a server and pid file if you have multiple Resin servers.</li>
<li>Start and stop the Resin daemon.</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
SERVER_ROOT=/usr/local/web

export JAVA_HOME
export RESIN_HOME
export SERVER_ROOT

$RESIN_HOME/bin/httpd.sh -server-root $SERVER_ROOT \
                         -conf $SERVER_ROOT/conf/resin.conf \
                         -server a -pid $SERVER_ROOT/a.pid \
                         $*
</example>

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

<p>The <code>-server</code> and <code>-pid</code> arguments are only
necessary if you have multiple JVMs either on different machines
or the same machine.
The <a href="doc|config|balance">load balancing</a> and
<a href="doc|config|sessions">distributed sessions</a> pages describe when
you might use -server and -pid.</p>

<p>More information on deploying on Unix is available at:</p>
<ul>
<li><a href="doc|install|linux-boot">Linux boot</a></li>
</ul>

</section>

</section>

<section title="Windows">

<section title="Getting Started">

<ol>
<li>Install JDK 1.4 or later.</li>
<li>Make sure the JDK installation set the environment variable JAVA_HOME correctly</li>
<li>Unzip resin-3.0.0.zip</li>
<li>Execute resin-3.0.0/httpd.exe</li>
<li>Browse http://localhost:8080</li>
</ol>

<example title='Starting on Win32'>
C:\win32> resin-3.0.0\bin\httpd
Resin 3.0.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
</example>

</section>

<section title='Deploying as a Windows Service'>

<p>The Resin Web Server can be installed as an Windows service.</p>

<p>To install the service, use</p>

<example>
C:\> resin-3.0.x\bin\httpd -install -conf conf/myconf.conf
</example>

<p>To remove the service, use</p>

<example>
C:\> resin-3.0.x\bin\httpd -remove
</example>

<p>You will either need to reboot the machine or start the service
from the Control&nbsp;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:\> net start resin
...
C:\> net stop resin
</example>

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

<p>With multiple servers, you can use -install-as <var/foo/> to specify
the service name.</p>

<example>
C:\> resin-3.0.x\bin\httpd -install-as ResinA -conf conf/myconf.conf -server a
C:\> net start ResinA
</example>

<note>There is a bug in many JDKs which cause the JDK to exit when the
administrator logs out.  You can avoid that bug if the
JDK is started with -Xrs. </note>

<example>
C:\> resin3.0.0/httpd.exe -install -Xrs
</example>

</section>
</section>

<section name="command-line" title="Command-line arguments">

<deftable>
<tr><th>Argument</th><th>Meaning</th><th>Default</th></tr>
<tr><td>-verbose</td><td>Show the Java environment before starting Resin.</td><td>off</td></tr>
<tr><td>-conf <var/xxx/><td>Selects the Resin configuration file<td>conf/resin.conf
<tr><td>-java_home <var/xxx/><td>Sets the JDK (also recognizes the environment variable JAVA_HOME.)<td>A heuristic search 
<tr><td>-resin_home <var/xxx/><td>Sets the Resin home directory (also recognizes the environment variable RESIN_HOME.)<td>The parent directory of wrapper.pl
<tr><td>-classpath <var/xxx/><td>Adds to the system classpath.<td>$CLASSPATH
<tr><td>-pid <var/xxx/><td>(Unix) With <var/start/> or <var/stop/>, sets the file
to save the process id.<td>resin.pid
<tr><td>-stdout <var/xxx/><td>Sets the file to save stdout messages.<td>log/stdout.log.
<tr><td>-stderr <var/xxx/><td>Sets the file to save stdout messages.<td>log/stderr.log.
<tr><td>-D<var/my.foo/>=<var/value/><td>Sets a Java system property.<td>n/a
<tr><td>-X<var/xxx/><td>Passes the -X<var/xxx/> command to the JDK.<td>n/a
<tr><td>-J<var/xxx/><td>Passes <var/xxx/> as a JDK argument.<td>n/a
<tr><td>-nojit<td>Disables the Just-In-Time compiler. Useful for debugging.<td>enabled
<tr><td>start<td>(Unix) Starts Resin as a daemon, saving the pid in the pid file.<td>n/a
<tr><td>stop<td>(Unix) Stops Resin as a daemon, using the pid in the pid file.<td>n/a
<tr><td>restart<td>(Unix) Restarts Resin as a daemon, using the pid in the pid file.<td>n/a
<tr><td>-install<td>(Windows) install Resin as a service (but doesn't automatically start.)<td>n/a
<tr><td>-install-as <var/xxx/><td>(Windows) install Resin as a named service (but doesn't automatically start.)<td>n/a
<tr><td>-remove<td>(Windows) install Resin as a service (but doesn't automatically start.)<td>n/a
<tr><td>-remove-as <var/xxx/><td>(Windows) remove Resin as a named service (but doesn't automatically start.)<td>n/a
</deftable>

<section title='Memory Configuration'>

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

<deftable title='Memory Configuration'>
<tr><td>-Xms&lt;size><td>Initial Java heap size, e.g. -Xms32m
<tr><td>-Xmx&lt;size><td>Maximum Java heap size, e.g. -Xmx128m
</deftable>

</section>

</section>

<section title='Starting Java directly'>

<p>You can use the <var/-verbose/> flag to see the arguments the startup
scripts/executables pass to the JDK.  The main Java executable is
<var/com.caucho.server.resin.Resin/> and starting Resin looks like
the following, once you've properly configured the classpath:</p>

<example>
unix> java -Dresin.home=/usr/resin \
           -Djava.util.logging.manager=com.caucho.log.LogManagerImpl \
           com.caucho.server.resin.Resin \
           -conf conf/resin.conf 
</example>
</section>

  </body>
</document>
