<document>
  <header>
    <product>resin</product>
    <resin-2.0>$resin/java_tut/isp.xtp</resin-2.0>
    <title>ISP with Apache</title>
  </header>

  <body>
    <summary/>

<s1 title="File locations">

<p>This sample configuration has Resin home in /usr/local/resin-2.0 and
the user's server root set to /home/slytherin/resin.</p>

<p>The user will create her application in /home/slytherin/resin/doc,
putting classes in doc/WEB-INF/classes and jars in doc/WEB-INF/lib.  If
she uses a war file, she can put it in /home/slytherin/resin/webapps.
Resin will expand the war automatically.</p>

<deftable>
<tr><th>Directory</th><th>Contents
</th></tr><tr><td>/usr/local/resin-2.0</td><td>root owned Resin home
</td></tr><tr><td>/usr/local/resin-2.0/conf/slytherin.conf</td><td>root-owned slytherin configuration
</td></tr><tr><td>/home/slytherin/resin</td><td>User's server root
</td></tr><tr><td>/home/slytherin/resin/doc</td><td>User's documents
</td></tr><tr><td>/home/slytherin/resin/doc/WEB-INF/web.xml</td><td>Any user-specific configuration
</td></tr><tr><td>/home/slytherin/resin/doc/WEB-INF/classes</td><td>The user's Java classes
</td></tr><tr><td>/home/slytherin/resin/doc/WEB-INF/lib</td><td>The user's jars
</td></tr><tr><td>/home/slytherin/resin/webapps</td><td>auto-expanding war directory
</td></tr><tr><td>/home/slytherin/resin/log/stdout.log</td><td>JVM's standard output
</td></tr><tr><td>/home/slytherin/resin/log/stderr.log</td><td>JVM's standard error
</td></tr><tr><td>/home/slytherin/resin/log/error.log</td><td>Servlet errors
</td></tr><tr><td>/home/slytherin/resin/resin.pid</td><td>JVM's saved process id
</td></tr></deftable>

</s1>

<s1 title="slytherin.conf">

<p>In this configuration, each JVM gets its own configuration file.
The slytherin.conf is owned and managed by root.  By having root
control the configuration, you can make sure the mod_caucho/Resin
communication is properly configured.</p>

<p>The user can customize the configuration by adding a
doc/WEB-INF/web.xml file following the servlet deployment descriptor.
ISPs that want give more flexibility can add a &lt;resin:include&gt; directive
to read a user configuration file.</p>

<example title="slytherin.conf">
&lt;caucho.com&gt;
  &lt;http-server&gt;
    &lt;app-dir&gt;doc&lt;/app-dir&gt;
    &lt;srun host='slytherin.caucho.com' port='6802'/&gt;

    &lt;host id='slytherin slytherin.caucho.com'&gt;
      &lt;error-log id='log/error.log'/&gt;

      &lt;war-dir&gt;webapps&lt;/war-dir&gt;

      &lt;web-app id='/'&gt;
        &lt;servlet-mapping url-pattern='*.jsp' servlet-name='jsp'/&gt;
        &lt;servlet-mapping url-pattern='*.xtp' servlet-name='xtp'/&gt;
      &lt;/web-app&gt;
    &lt;/host&gt;
  &lt;/http-server&gt;
&lt;/caucho.com&gt;
</example>

<deftable>
<tr><th>Element</th><th>Description
</th></tr><tr><td>app-dir</td><td>Configures the document directory as a subdirectory of
server-root.
</td></tr><tr><td>srun</td><td>Configures the srun port Resin will listen for Apache
requests.  Browsing http://slytherin/caucho-status will show the
status of the link.
</td></tr><tr><td>host</td><td>Configures the virtual host.  The host name must match
the Apache <var>ServerName</var>.  Multiple host names are allowed as aliases.
</td></tr><tr><td>error-log</td><td>Servlet error log, relative to $SERVER_ROOT,
not $APP_DIR.  So it'll appear in resin, not doc.
</td></tr><tr><td>war-dir</td><td>Directory where the user can put foo.war files.  The
file will be automatically expanded and create an application named foo.
</td></tr><tr><td>web-app</td><td>Defines the user's root application.
</td></tr><tr><td>servlet-mapping</td><td>Defines *.jsp and *.xtp as extensions handled
by Resin.  mod_caucho needs these to know which files to dispatch to Resin.
Any other servlet-mappings should be defined in WEB-INF/web.xml.
</td></tr></deftable>

</s1>

<s1 title="Apache httpd.conf">

<p>Each Apache virtual host use its own resin.conf file.  You can
look at the configuration using /caucho-status for the virtual host,
as usual.</p>

<p>The <var>ServerName</var> is particularly important.  mod_caucho
sends the value of ServerName to the JVM so Resin can choose
a virtual host.  The ServerName value must match the &lt;host&gt; value.</p>

<example>
...

&lt;VirtualHost slytherin.caucho.com&gt;
ServerAlias www.slytherin.caucho.com slytherin
ServerName slytherin.caucho.com

CauchoConfigFile /usr/local/resin-2.0/conf/slytherin.conf
&lt;/VirtualHost&gt;

...
</example>

</s1>

<s1 title="Starting script">

<p>ISPs will generally start the server on system startup as root from
an init script.  However, the JVM should be running as the user to
avoid permission problems.</p>

<p>The main tasks of the script are to change to the user by using "su"
and to set the server-root to the user's root.  The server root needs to
change to the user's directory so the JVM can write its logs and open
any needed caching or other temporary files.</p>

<p>An ISP could provide this script to the user after
removing the "su $USER".  That will give the user a way to start and stop
the JVM if necessary.</p>

<example title="slytherin-start.sh">
#!/bin/sh

JAVA_HOME=/usr/java
export JAVA_HOME

RESIN=/usr/local/resin-2.0
USER=slytherin
ROOT=/home/$USER/resin

su $USER -c "$RESIN/bin/httpd.sh -server-root $ROOT \
                                 -conf $RESIN/conf/$USER.conf \
                                 start"
</example>

</s1>

<s1 title="Sample Installation Order">

<ol>
<li>Untar resin-2.0.x.tar.gz into /usr/local/resin-2.0.x
</li><li>You can change the ownership to root if you like:
<example>
/usr/local# find resin-2.0.x -exec chown root.root {} \;
</example>
</li><li>create conf/slytherin.conf and modify Apache's httpd.conf to point to it.
</li><li>Restart Apache.
</li><li>Browse http://slytherin/caucho-status.  The status should be red (off),
and the host:port and url mappings should match.
</li><li>Create /home/slytherin/resin as "slytherin".
</li><li>Create the slytherin-start.sh script.
</li><li>Start the stytherin-start.sh script.  Error messages will appear in
the /home/slytherin/resin/log files.
root with the 
</li><li>Resin should now be running as the user.  /caucho-status should now
be green (on) and JSP files should work.
</li><li>You'll probably want to create rc.d/init.d scripts to automatically
start Resin on system startup.  Make sure you set any needed environment
variables like JAVA_HOME.
</li></ol>

</s1>
  </body>
</document>