<s1 title="File Configuration">

<s2 title="RESIN_HOME">

<p>RESIN_HOME is the directory containing the Resin binaries and classes.
In the default configuration, RESIN_HOME will be the same as SERVER_ROOT,
i.e. the document directories and log files are based on RESIN_HOME.
A typical location for RESIN_HOME might be /usr/local/resin.</p>

<p>RESIN_HOME is controlled by the command-line and system environment when
Resin starts.  The heuristic for selecting RESIN_HOME is

<ol>
<li>-resin-home <var/dir/> command-line argument
<li>$RESIN_HOME system environment variable
<li>The parent directory of the starting binary.  bin/httpd,
or bin/httpd.sh will look at its own directory and then use the parent directory as RESIN_HOME.
</ol>

<p>The Resin binary will set the Java system property
resin.home to the value for RESIN_HOME, e.g. by setting
-Dresin.home=$RESIN_HOME.  If an application starts
the Resin main class directly, it should set the resin.
home system property.</p>

<deftable title="Contents of RESIN_HOME">
<tr><th>Directory/File<th>Description
<tr><td>bin/<td>Resin startup binaries
<tr><td>lib/<td>jar files automatically added to the system classpath.
Applications may add third-party library .jar files.
<tr><td>libexec/<td>JNI *.so files to be automatically loaded
<tr><td>classes/<td>Optional directory of classes to be added to the system classpath.  (Applications should use WEB-INF/classes instead.)
<tr><td>conf/<td>Directory containing configuration files when RESIN_HOME is the same as SERVER_ROOT.
<tr><td>conf/resin.conf<td>The main Resin configuration file when RESIN_HOME is the same as SERVER_ROOT.
<tr><td>doc/<td>Document root when RESIN_HOME is the same as SERVER_ROOT for the default virtual host.
<tr><td>webapps/<td>War expansion directory when RESIN_HOME is the same as SERVER_ROOT for the default virtual host.
<tr><td>log/<td>Log directory when RESIN_HOME is the same as SERVER_ROOT.
</deftable>

</s2>

<s2 title="SERVER_ROOT">

<p>SERVER_ROOT is the directory containing the user's
configuration, documents, and log files.  By default, SERVER_ROOT is
the same as RESIN_HOME, but sophisticated users will create a
separate directory from the Resin binaries.  For example, an ISP
might have a separate SERVER_ROOT for each user's JVM.  A typical
location for SERVER_ROOT might be /usr/local/webroot.</p>

<p>SERVER_ROOT is controlled by the command-line when Resin starts.
The heuristic for selecting SERVER_ROOT is:</p>

<ol>
<li>The value of &lt;root-dir> in the &lt;http-server> section of
the resin.conf.
<li>-server-root <var/dir/> command-line argument
<li>The value of RESIN_HOME.
</ol>

<deftable title="Contents of SERVER_ROOT">
<tr><th>Directory/File<th>Description
<tr><td>conf/<td>Directory containing the resin.conf configuration file.
<tr><td>conf/resin.conf<td>The main Resin configuration file.
<tr><td>cache/<td>Directory Resin's cache files.
<tr><td>doc/<td>Document root for the default virtual host.
<tr><td>webapps/<td>War expansion directory for the default virtual hosts.
<tr><td>log/<td>Log directory.
<tr><td>WEB-INF/<td>Application classes and jars common to all virtual
hosts.
<tr><td><var/foo.com/>/<td>Root directory for a virtual host.
</deftable>

</s2>

<s2 title="virtual host root-dir">

<p>Each virtual host has its own root directory.  The root directory
contains virtual host's documents, war directory, and logs.</p>

<p>The virtual host's directory is configured in the resin.conf.
<a href="http-config.xtp#root-dir">root-dir</a> configures the
virtual host's root.  <a href="http-config.xtp#doc-dir">doc-dir</a>
configures the virtual host's document directory.</p>

<deftable title="Contents of the virtual host">
<tr><th>Directory/File<th>Config<th>Description
<tr><td>webapps/<td><a href="http-config.xtp#war-dir">war-dir</a><td>.war expansion directory.
<tr><td>webapps/WEB-INF/<td><a href="http-config.xtp#war-dir">war-dir</a><td>Common classes for the virtual host
<tr><td>doc/<td><a href="http-config.xtp#doc-dir">doc-dir</a><td>document directory.
<tr><td>log/access.log<td><a href="http-config.xtp#access-log">access-log</a><td>per-virtual host access logs
<tr><td>log/error.log<td><a href="http-config.xtp#error-log">error-log</a><td>per-virtual host error logs
<tr><td>log/stdout.log<td><a href="app-config.xtp#stdout-log">stdout-log</a><td>per-virtual host System.out
<tr><td>log/stderr.log<td><a href="app-config.xtp#stderr-log">stderr-log</a><td>per-virtual host System.err
</deftable>

</s2>

<s2 title="webapps (war-dir)">

<p>The webapps directory automatically expands .war and .ear files.</p>

<p>Each .war file will be expanded into
a web-app as a directory under the webapps directory.  webapps/foo.war will
expand into webapps/foo.  /foo will then be a web-app for the virtual
host.  So the URL might be http://www.bar.com/foo.</p>

<p>Each .ear file will expand its jars and .war files.  The jars will go
into webapps/WEB-INF/lib.  The .wars will be expanded into webapps.</p>

<p>The resin.conf configures the webapps directory with
the <a href="http-config.xtp#war-dir">war-dir</a> configuration.</p>

<example title="Configuring the war-dir">
&lt;host id="www.bar.com">
  &lt;root-dir>bar.com&lt;/root-dir>
  &lt;war-dir>webapps&lt;/war-dir>
&lt;/host>
</example>

<s3 title=".war file">

<p>A .war file is a packaged Servlet application. It's just a renamed
.jar file of the web-app directory tree. Resin provides a special
webapps directory which will automatically expand .war files,
configured by the <a href="http-config.xtp#war-dir">war-dir</a>
attribute in the resin.conf's host configuration.</p>

<p>Placing a foo.war in webapps/foo.war will prompt Resin to expand
foo.war into webapps/foo/*. Resin will automatically create a new
application browsable at the URL http://localhost:8080/foo</p>

<p>You can also use the &lt; war-dir> for development. Just creating a
webapps/bar directory will create an application browsable at
http://localhost:8080/bar. A small warning, though, any bar.war placed
in webapps will delete and replace your webapps/bar directory.</p>

<p>The special .war file ROOT.war can be used to configure the 'root'
web-app, i.e. the web-app with no context path. webapps/ROOT is
browsed with http://localhost:8080.</p>

<p>Resin always handles all files in a war, even when Resin is used
with another webserver like Apache.</p>

</s3>

</s2>

<s2 title="web-app directory">

<p>Each web application has its own document directory.
The files in that directory are served as static file.  The WEB-INF
subdirectory contains classes and configuration files for the web-app.</p>

<p>Web applications are either configured implicitly by the
webapps directory or explicitly in the resin.conf.  Any .war files in the
webapps directory will create a web application.  <var/foo.war/> will
expand into the web-app directory <var/webapps/foo/>.  The WEB-INF
directory is in <var/webapps/foo/WEB-INF/>.</p>

<p>Web applicatoins configured in the resin.conf can be placed anywhere
in the filesystem using the <var/app-dir/> tag.</p>

<example title="Explicit web-app in resin.conf">
&lt;host id='www.foo.com'>
  &lt;web-app id='/bar' app-dir='/opt/bar'/>
&lt;/host>
</example>

<p>The web-apps can also be configured using regular expressions.
For example, <var//~ferg/> may translate into a web-app in
/home/ferg/public_html.</p>

<example title="Regexp web-app in resin.conf">
&lt;host id=''>
  &lt;web-app url-regexp='/~([^/]*)'>
    &lt;app-dir>/home/$1/public_html&lt;/app-dir>
  &lt;/web-app>
&lt;/host>
</example>

<deftable title="web-app directory contents">
<tr><th>Directory/File<th>Description
<tr><td><var/test.html/><td>Static HTML file served to user
<tr><td><var/foo.jsp/><td>JSP file served to user
<tr><td>WEB-INF/<td>Directory for classes and servlets
</deftable>

</s2>

<s2 title="WEB-INF">

<p>The WEB-INF contains the classes, jars, and configuration files
for the web application.  WEB-INF is at the root of the web-app's
document directory.</p>

<deftable title="Contents of WEB-INF">
<tr><th>Directory/File<th>Description
<tr><td>classes/<td>Directory containing .class files
<tr><td>lib/<td>Directory containing .jar files
<tr><td>tld/<td>Directory containing tag library configuration files.
<tr><td>sessions/<td>Directory containing persistent sessions.
<tr><td>work/<td>Directory containing Resin's automatically
generated java and class files for JSP, XSL, and EJB.
<tr><td>tmp/<td>Temporary directory for the web-app.
<tr><td>web.xml<td>Servlet standard configuration file for the web-app.
<tr><td>resin-web.xml<td>Resin-specific configuration.
<tr><td><var/foo.ejb/><td>Resin-specific EJB configuration files.
</deftable>

<s3 title="WEB-INF for hosts and http-server">

<p>Hosts and the http-server may also have a WEB-INF directory.
The host's WEB-INF will be shared for all web-apps in the virtual host.
The http-server's WEB-INF will be shared for all virtual hosts in
the server.</p>

<p>The host's WEB-INF directory is in webapps/WEB-INF.
The http-server's WEB-INF is in SERVER_ROOT/WEB-INF.</p>

<p>Sites will typically use the host's WEB-INF to share resources,
EJB servers, or single-signon authenticators for all applications in a
host or in the server.</p>

</s3>

</s2>

<s2 title="path-mapping (aliasing)">

<p>In the web.xml file, directories and files can be aliased using
the <a href="app-config.xtp#path-mapping">path-mapping</a> directive.

<example title="aliasing /images to /opt/images">
&lt;web-app>
  &lt;path-mapping>
    &lt;url-pattern>/images/*&lt;/url-pattern>
    &lt;real-path>/opt/images&lt;/real-path>
  &lt;/path-mapping>
&lt;/web-app>
</example>

</s2>

<s2 title="Path Variable expansion">

<p>Paths in configuration variables can use path and
regular expression variables.</p>

<deftable>
<tr><th>Variable<th>Value
<tr><td>$server-root<td>The root of the server instance.  Same as the -server-root argument.
<tr><td>$server-doc<td>The document root for the server instance.
<tr><td>$host-root<td>The root directory of the enclosing &lt;host>
<tr><td>$host-doc<td>The document directory of the enclosing &lt;host>
<tr><td>$app-dir<td>The app-dir of the enclosing &lt;web-app>
<tr><td>$host0 ... $host9<td>Regular expression replacement from a host url-regexp.
<tr><td>$app0 ... $app9<td>Regular expression replacement from a web-app url-regexp.
<tr><td>$0 ... $9<td>Regular expression replacement for the containing context (host or web-app)
<tr><td>$<var/foo/><td>Java property value from System.getProperty("foo")
</deftable>

</s2>

</s1>
