<title>Virtual Hosting</title>

<summarylist/>

<section title='Standalone Virtual Hosting'>

<p/>Each Resin instance can serve many virtual hosts.  The virtual
host will have its own servlets and documents.  For greater isolation,
you can configure each virtual host to have its own JVM and you can
have all the virtual hosts controlled by a single web server.

<p/>Configuring the standalone server is the easiest and best
way of testing a virtual host configuration.  The
resin.conf is identical for Resin standalone and for Resin as a
servlet runner.  So even when using an external web server, it's a
good idea to test configuring with Resin standalone.

<p/>Each virtual host has its own <a
href='http-config.xtp#host'>host</a> block.  At very least, each host
will define the <var/id/> specifying the host name and an
<var/app-dir/> to specify the document root.

<p/>The following sample configuration defines two virtual hosts,
gryffindor and slytherin, each with its own document directory.

<example title='resin.conf'>
&lt;http-server>
  ...

&lt;host id='gryffindor.caucho.com'>
  &lt;app-dir>/home/www/gryffindor/docs&lt;/app-dir>
  ...		    
&lt;/host>

&lt;host id='slytherin.caucho.com'>
  &lt;app-dir>/home/www/slytherin/docs&lt;/app-dir>
  ...		    
&lt;/host>
</example>

<p/>Browsing http://gryffindor.caucho.com/test.jsp will look for
/home/www/gryffindor/docs/test.jsp.

<p/>Browsing http://slytherin.caucho.com/test.jsp will look for
/home/www/slytherin/docs/test.jsp.

</section>
<section title='Virtual Hosts with Apache or IIS'>

<p/>A common configuration uses virtual hosts with Apache or IIS.
As usual, Apache or IIS will pass matching requests to Resin.

<p/>The Resin JVM configuration with Apache is identical to the
standalone configuration.  That similarity makes it easy to debug the
Apache configuration by retreating to Resin standalone if needed.

<p/>The <var/ServerName/> directive in Apache is vital to make Resin's
virtual hosting work.  When Apache passes the request to Resin, it
tells Resin the <var/ServerName/>.  Without the <var/ServerName/>,
Resin can get very confused which host to serve.

<example title='httpd.conf'>
LoadModule caucho_module /usr/local/apache/libexec/mod_caucho.so
AddModule mod_caucho.c

CauchoConfigFile /home/www/conf/resin.conf

&lt;VirtualHost 127.0.0.1>
  ServerName gryffindor.caucho.com
&lt;/VirtualHost>

&lt;VirtualHost 192.168.0.1>
  ServerName slytherin.caucho.com
&lt;/VirtualHost>
</example>

<note>You'll the LoadModule and AddModule must appear before
the CauchoConfigFile for Apache to properly understand the
CauchoConfigFile command.  If they're missing, Apache will send
an error.</note>

</section>

<section title='JVM per Virtual Host'>

In some ISP setups, it may make sense to assign a JVM for each
virtual host.  The isolation of web-apps may not be
sufficient; each user needs a separate JVM.  In this configuration,
each JVM needs its own srun-port and possibly its own srun-host.

<p/>In the most straightforward configuration, each JVM gets its own
resin.conf.  The resin.conf can use <a
href='resin-config.xtp#resin:include'>resin:include</a> to share
common configuration.

<example title='httpd.conf'>
&lt;VirtualHost 127.0.0.1>
  ServerName gryffindor.caucho.com
  CauchoConfigFile /home/www/config/gryffindor.conf
&lt;/VirtualHost>

&lt;VirtualHost 192.168.0.1>
  ServerName slytherin.caucho.com
  CauchoConfigFile /home/www/config/slytherin.conf
&lt;/VirtualHost>
</example>

<p/>Here's the corresponding gryffindor.conf

<example title='gryffindor.conf'>
&lt;caucho.com>
&lt;http-server>
  &lt;srun host=localhost port=8910/>

  &lt;host id='www.gryffindor.com'>
    &lt;app-dir>/home/www/gryffindor/htdocs&lt;/app-dir>

    &lt;resin:include href='common.conf'/>
  &lt;/host>
&lt;/http-server>
&lt;/caucho.com>
</example>

<example title='slytherin.conf'>
&lt;caucho.com>
&lt;http-server>
  &lt;srun host=localhost port=8911/>

  &lt;host id='www.slytherin.com'>
    &lt;app-dir>/home/www/slytherin/htdocs&lt;/app-dir>

    &lt;resin:include href='common.conf'/>
  &lt;/host>
&lt;/http-server>
&lt;/caucho.com>
</example>

<p/>You'll start each JVM separately.  With Unix, you might do something like:

<example>
unix> httpd.sh -conf gryffindor.conf -pid gryffindor.pid start
unix> httpd.sh -conf slytherin.conf -pid slytherin.pid start
</example>

<p/>On Unix, the <var/-pid/> will let <var/srun.sh/> know
which server to stop.

<example>
unix> httpd.sh -conf gryffindor.conf -pid gryffindor.pid stop
unix> httpd.sh -conf slytherin.conf -pid slytherin.pid stop
</example>

<p/>When you restart the web server, you can look at
<var/http://gryffindor/caucho-status/>
and <var/http://slytherin/caucho-status/> to check
your configuration.  Check that each virtual host is using the
<var/srun-host/> and <var/srun-port/> that you expect.

<subsection title='Why the host is necessary'>

<p/>The &lt;host> block in gryffindor.conf and slytherin.conf is
required for a subtle reason.  When Resin compiles JSP files, it generates
a Java class name.  Classes for different hosts get different class names
to prevent name collisions.

<p/>If gryffindor.conf and slytherin.conf omit the &lt;host>, Resin will
generate the same class name for both hosts.  If both hosts also use the same
<a href='resin-config.xtp#java'>work-dir</a>, one host will see the JSP
for the other host.

</subsection>
</section>
