Before you integrate Resin with Apache

Before integrating Resin with Apache, it is valuable to configure Resin as a
standalone server, especially with more
complicated setups such as those involving virtual hosts. Doing so isolates
the steps and makes troubleshooting easier.

Many users find that the performance, flexibility, and features of Resin
make Resin a desirable replacement for Apache.

How Resin integrates with Apache

When used with Apache, Resin serves JSPs and Servlets and Apache serves
static content like html and images. Apache is a frontend server, it handles
the request from the browser. Resin's mod_caucho plugin integrates
with Apache, it dispatches requests for JSPs and Servlets to one or more
backend Resin servers.

mod_caucho queries the backend server to distinguish the URLs going to Resin
from the URLs handled by Apache. The backend server uses the
<servlet-mapping> directives to decide which URLs to send. Also, any *.war
file automatically gets all its URLs. Other URLs stay with Apache.

Solaris versions of Apache may need additional flags, otherwise
you'll get some linking errors when trying to load Resin. You may need
to refer to the Apache documentation if you get linking errors. Here's an
example configuration on Solaris:

Compiling mod_caucho.so

To compile and install mod_caucho on Unix, you'll need to run
Resin's configure and then make. This step will create
mod_caucho.so and put it in the Apache module directory. Usually,
mod_caucho.so will end up in /usr/local/apache/libexec/mod_caucho.so.

If you know where your apxs executable is, you can use --with-apxs.
apxs is a little Perl script that the Apache configuration
makes. It lets modules like Resin know how all the Apache directories
are configured. It is generally in /usr/local/apache/bin/apxs or
/usr/sbin/apxs. It's usually easiest to use --with-apxs so you don't
need to worry where all the Apache directories are.

unix> ./configure --with-apxs=/usr/local/apache/bin/apxs
unix> make

Even if you don't know where apxs is, the configure script
can often find it:

unix> ./configure --with-apxs
unix> make

As an alternative to --with-apxs, if you've compiled Apache yourself,
or if you have a simple configuration, you can generally just point to
the Apache directory:

The previous --with-apxs or --with-apache should cover most
configurations. For some unusual configurations, you can have finer control
over each directory with the following arguments to ./configure.
In general, you should use --with-apache or --with-apxs, but the other
variables are there if you know what you're doing.

FLAG

DESCRIPTION

--with-apache=dir

The Apache root directory.

--with-apxs=apxs

Pointer to the Apache extension script

--with-apache-include=dir

The Apache include directory

--with-apache-libexec=dir

The Apache module directory

--with-apache-conf=httpd.conf

The Apache config file

Configure the Environment

If you don't already have Java installed, you'll need to download a
JDK and set some environment variables.

Here's a typical environment that you might put in ~/.profile or
/etc/profile

The resin.xml and the layout of your webapps should match the
layout that Apache expects. The mapping of urls to filesystem locations
should be consistent between Apache and the backend Resin server.

The default resin.xml looks in
resin-4.0.x/webapps/ROOT
for JSP files and
resin-4.0.x/webapps/ROOT/WEB-INF/classes
for servlets and java source files. To tell Resin
to use Apache's document area, you configure an explicit
web-app with the appropriate document-directory:

Resin will print every port it's listening to. In the above example,
Resin has an http listener on port 8080 and an server listener on port 6800
(using its custom 'hmux' protocol). mod_caucho establishes connections to
Resin using port 6800, and a web browser can connect using port 8080. Usually
the 8080 port will be unused, because web browsers will make requests to Apache,
these requests get dispatched to Resin as needed by mod_caucho. A Resin
configured http listener on port 8080 is a useful debugging tool, it allows you
to bypass Apache and make a request straight to Resin.

The following snippet shows the
<http>
and <<server>>
configuration for the above example.

The ResinConfigServer is used to tell mod_caucho how to contact
the backend Resin server. The backend Resin server tell's mod_caucho which urls
should be dispatched.

APACHE COMMAND

MEANING

ResinConfigServer hostport

Specifies the Resin JVM at host:port as a configuration server.

caucho-status

caucho-status is optional and probably should be avoided in
a production site. It lets you ask the Caucho Apache module about it's
configuration, and the status of the backend server(s), valuable for
debugging.

After any change to httpd.conf, restart Apache. Now browse
http://localhost/caucho-status.

Manual configuration of dispatching

You can also dispatch to Resin directly from the httpd.conf. Instead of
relying on the ResinConfigServer directive to determine which url's to dispatch
to the backend server, Apache handler's are used to specify the url's to
dispatch.

Load Balancing

mod_caucho recognizes cluster configurations for load balancing.
Requests are distributed to all machines in the cluster, all
requests in a session will go to the same host, and if one host goes down,
Resin will send the request to the next available machine.
Optional backup machines only receive requests if all of the primaries are
down.

mod_caucho only needs to know about one of the backend servers. It will query
that backend server, and learn about all of the other members of the cluster.

ResinConfigServer 192.168.0.11 6800

mod_caucho keeps a local cache of the configuration information, so if the
backend server becomes unavailable then the cached configuration will be used
until the backend server becomes available again.

The httpd.conf file can also specify more than one backend server, when
mod_caucho checks for configuration updates, it will check each in turn, and
only if none of them are available will it use the local cached copy.

Cloud-optimized Resin Server is a Java EE certified Java Application Server, and Web Server, and Distributed Cache Server (Memcached).Leading companies worldwide with demand for reliability and high performance web applications including SalesForce.com, CNET, DZone and many more are powered by Resin.