File locations

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

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.

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

slytherin.conf

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.

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 <resin:include> directive to read a user configuration file.

<caucho.com>
  <http-server>
    <app-dir>doc</app-dir>
    <srun host='slytherin.caucho.com' port='6802'/>

    <host id='slytherin slytherin.caucho.com'>
      <error-log id='log/error.log'/>

      <war-dir>webapps</war-dir>

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

Element	Description
app-dir	Configures the document directory as a subdirectory of server-root.
srun	Configures the srun port Resin will listen for Apache requests. Browsing http://slytherin/caucho-status will show the status of the link.
host	Configures the virtual host. The host name must match the Apache ServerName. Multiple host names are allowed as aliases.
error-log	Servlet error log, relative to $SERVER_ROOT, not $APP_DIR. So it'll appear in resin, not doc.
war-dir	Directory where the user can put foo.war files. The file will be automatically expanded and create an application named foo.
web-app	Defines the user's root application.
servlet-mapping	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.

Apache httpd.conf

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.

The ServerName 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 <host> value.

... <VirtualHost slytherin.caucho.com> ServerAlias www.slytherin.caucho.com slytherin ServerName slytherin.caucho.com CauchoConfigFile /usr/local/resin-2.0/conf/slytherin.conf </VirtualHost> ...

Starting script

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.

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.

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.

#!/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"

Sample Installation Order

1. Untar resin-2.0.x.tar.gz into /usr/local/resin-2.0.x
2. You can change the ownership to root if you like:

   /usr/local# find resin-2.0.x -exec chown root.root {} \;

3. create conf/slytherin.conf and modify Apache's httpd.conf to point to it.
4. Restart Apache.
5. Browse http://slytherin/caucho-status. The status should be red (off), and the host:port and url mappings should match.
6. Create /home/slytherin/resin as "slytherin".
7. Create the slytherin-start.sh script.
8. Start the stytherin-start.sh script. Error messages will appear in the /home/slytherin/resin/log files. root with the
9. Resin should now be running as the user. /caucho-status should now be green (on) and JSP files should work.
10. 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.

Copyright © 1998-2002 Caucho Technology, Inc. All rights reserved. Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.