<document>
<localtoc/>

Many sites will use the default resin.conf with only minimal configuration changes, e.g. changing the <http> port, adding <openssl> port, new <database> configuration or <authenticator> for security. Those sites can use the default resin.conf as an sample index into the configuration tags to be customized.

This overview provides an overview of some of the other customizations available in the resin.conf. For example some sites have have more sophisticated requirements, either adding many virtual hosts, proxy caching, load-balancing, or adding distributed sessions.

As a starting point to the structure of Resin's configuration, it's best to look at the minimal usable resin.conf file. All configuration in Resin ultimately derives from the top-level resin.conf file, so understanding and debugging a configuration can start from the resin.conf and work toward any included files such as <g>resin-web.xml</g>.

The minimal usable resin.conf file listens to HTTP at port 8080 and looks for web-apps in webapps. So the URL http://localhost:8080/test.php would look in $SERVER_ROOT/webapps/ROOT/test.php.

$SERVER_ROOT defaults to $RESIN_HOME, i.e. the resin-3.1.0 directory. It can also be assigned with a command-line argument --server-root

<resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <cluster id="app-tier"> <server id=""> <http port="8080"/> </server> <resin:import path="${resin.home}/conf/app-default.xml"/> <host id=""> <web-app-deploy path="webapps"/> </host> </cluster> </resin>

To start Resin with this minimal resin.conf use the following:

<example> share> java -jar resin-3.1.0/lib/resin.jar

Or to start Resin as a daemon use "start":

<example> share> java -jar resin-3.1.0/lib/resin.jar start

The <resin> tag is a container for all the Resin configuration. It will generally contain one or most <cluster> configuration. In more complete configuration, it may also contain logging, class loader, system-property or global resource definitions.

The namespace declaration of http://caucho.com/ns/resin enables Resin's validation of the configuration files. The validator will detect syntax errors and provide a summary of the syntax to help debug resin.conf files.

The namespace declaration of http://caucho.com/ns/resin/core enables Resin control tags like <resin:import>, <resin:set>, and <resin:if>. These control tags can help organize configuration files, but you should take care not to overuse them, which might overcomplicate the configuration file.

The <cluster> tag configures clusters of servers. The cluster consists of a number of virtual hosts, possibly including a default virtual host. Each <server> in a <cluster> handles the same requests.

A web-site using Resin's load balancing might have two clusters: a web-tier handling the HTTP requests and an app-tier handling servlets, PHP and JSP pages.

A <server> configures a single JVM instance running Resin. There may be multiple servers in a <cluster> and there may also be multiple servers on a machine.

The <server> will have a unique id which matches the -server command-line argument.

The <server> will also configure any <http> ports, any setuid <user-name> changes and any <thread-max>, <socket-timeout>, or <keepalive-max> values.

Typically, common configuration for multiple servers like <http> and <thread-max> will be put in a <server-default> tag to simplify the configuration.

The <http> tag configures HTTP ports. It may contain <openssl> tags for SSL support.

The <http> tags are often put in a <server-default> tag, sharing the configuration for all servers in a cluster.

The <resin:import> can import other configuration files to help organize complicated configurations. The app-default.xml file in the example defines the usual servlets that applications expect, like the JSP servlet, the PHP/Quercus servlet, and default configuration like <g>resin-web.xml</g> and <g>web.xml</g>.

Resin's configuration files can use EL expressions, including predefined variables like ${resin}, ${cluster}, ${host}, and ${webApp}.

The <host> tags configure virtual host. In this minimal example, the host is the default virtual host; it will match any host which other <host> tags do not match.

More complicated sites with many virtual hosts will often use a host-deploy tag to automatically deploy virtual hosts in a hosts deployment directory, and use host-default to share common virtual host configuration.

The <web-app> and <web-app-deploy> tags configure web-applications. Web applications are mini-virtual hosts, i.e. sections of the web site that are conceptually distinct from each other. Many sites will only have a single root web-application.

The <web-app-deploy> tag defines a webapps directory which automatically deploys web-applications. The ROOT web-app is a special name which matches the root URL.

Adding a virtual host with Resin can be as simple as creating new directories and adding content. The default virtual host has a <host-deploy> tag which defines a hosts deployment directory. For example, a virtual host www.foo.com might be browsable as http://www.foo.com/test.php. Assuming the server-root is /var/www, you can create a new virtual host by adding a file in:

<example> /var/www/hosts/www.foo.com/webapps/ROOT/test.php

Of course, Resin's virtual host's can be configured in other directory configurations. The <host>, <host-deploy>, and <host-default> tags let sites choose where to put their virtual hosts.

The following example shows both the <host> and <host-deploy> methods of configuring virtual hosts. The <host> for www.foo.com directly configures the foo.com site in the resin.conf. The <host-deploy> for hosts configures a host deployment directory. Any directory added to hosts will automatically create a new virtual host. Finally, the <host> with id="" defines the "default" virtual host. Any request not matching any other host will use the virtual host.

<resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <root-directory>/var/www</root-directory> <server ... /> <host-default> <web-app-deploy path="webapps"/> <resin:import path="host.xml" optional="true"/> </host-default> <host id="www.foo.com"> <host-alias>foo.com</host-alias> <root-directory>foo.com</root-directory> </host> <host id=""> <root-directory>default-host</root-directory> </host> <host-deploy path="hosts"/> </cluster> </resin>

The above example also introduces the <host-default> tag. The <host-default> defines configuration common to all hosts following the <host-default>. In this case, we define an optional host configuration file host.xml and a standard webapps deployment directory. The <host-default> are processed as macros in configuration-file order. So a configuration tag later in the file can override the defaults.

In Resin, adding servers to a cluster is just adding a <server> tag to a <cluster> block. Each <server> has an id which is unique in the resin.conf file. The server will also have a unique address and port which allows the servers in the cluster to communicate with each other.

Clustering is used for load-balancing, distributed sessions and remote administration. Adding servers to a cluster lets sites handle more traffic and improves reliability by providing redundant servers.

<resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <server-default> <http port="80"/> <user-name>resin</user-name> </server-default> <server id="app-a" address="192.168.2.10" port="6800"/> <server id="app-b" address="192.168.2.11" port="6800"/> <server id="app-c" address="192.168.2.12" port="6800"/> <host id=""> ... </host> </cluster> </resin>

In the previous example, each server listens to port 80 as defined in the <server-default>. The unique id and address are internal IP addresses. (The server address should never be external.) Because the example is listening to port 80, the <user-name> switches from root to a safer runtime uid.

The resin.conf can define multiple <cluster> tags in the same resin.conf. Resin's load-balancing will typically use two clusters, a web-tier for the HTTP servers and an app-tier for the servlets, PHP and JSP files. A sample load balancing configuration might look like:

<resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server-default> <http port="80"/> </server-default> <server id="web-a" address="192.168.1.10" port="6800"/> <cache memory-size="64M"/> <host id=""> <web-app id=""> <rewrite-dispatch> <load-balance regexp="" cluster="app-tier"/> </rewrite-dispatch> </web-app> </host> </cluster> <cluster id="web-tier"> <server id="app-a" address="192.168.2.10" port="6800"/> <server id="app-b" address="192.168.2.11" port="6800"/> <server id="app-c" address="192.168.2.12" port="6800"/> <host id="www.foo.com"> ... </host> </cluster> </resin>

Resin includes a <rewrite-dispatch> tag for general URL rewriting and dispatching similar to Apache's mod_rewrite. <rewrite-dispatch> can forward to a new location when a site moves content, it can convert host urls into paths, and rewrite "pretty" URLs into PHP pages, load-balance to a cluster, and dispatch to normal servlets.

The following example rewrites "pretty" URLs like /wiki/Load-balance to actual urls like /wiki/index.php/Load-balance

<web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <dispatch regexp="\.(php|gif|css|jpg|png)"/> <forward regexp="" target="/index.php"/> </rewrite-dispatch> </web-app> <resin xmlns="http://caucho.com/ns/resin"> <cluster id=""> ... <rewrite-dispatch> <redirect regexp="^http://www.foo.com" target="http://test.com/"/> </rewrite-dispatch> </cluster> </resin> <resin xmlns="http://caucho.com/ns/resin"> <cluster id="web-tier"> <server id="web-a"> <http port="80"/> </server> <host id=""> <web-app id="/"> <rewrite-dispatch> <load-balance regexp="" cluster="app-tier"/> </rewrite-dispatch> </web-app> </host> </cluster> <cluster id="app-tier"> <server id="app-a" server="192.168.2.10"/> <server id="app-b" server="192.168.2.11"/> ... </cluster> </resin>

With Resin 3.1, applications can deploy REST, Hessian, and SOAP using the same instance class. A good introductary example is the SOA Hello, World tutorial.

The <web-service> tag configures the web service. The service is a Java object which exposes a JAX-WS interface and receives and sends Java objects encoded with JAXB. The service object itself is configured using JAXB-style IoC, i.e. standard bean-style property initialization.

<web-app xmlns="http://caucho.com/ns/resin"> <web-service class="example.HelloServiceImpl"> <jndi-name>service/HelloService</jndi-name> <init> <greeting>Hello, World</greeting> </init> <hessian> <url-pattern>/hello/hessian/*</url-pattern> </hessian> <rest> <url-pattern>/hello/rest/*</url-pattern> </rest> <soap> <url-pattern>/hello/soap/*</url-pattern> </soap> </web-service> </web-app>

The web service client configuration makes a Java proxy available to servlets and PHP pages through JNDI, or through a @Resource injection. The client can be SOAP, Hessian, or REST. A REST tutorial shows how to obtain a proxy to the Flickr REST service.

The <web-service-client> tag configures the client proxy. It provides a Java interface and a URL for the service. The URL specifies the encoding and the protocol, e.g. REST over HTTP or Hessian over HTTP. The client will typically have a jndi-name to store the client proxy.

<web-app xmlns="http://caucho.com/ns/resin"> <web-service-client jndi-name="rest/flickr"> <url>rest:http://foo.com/flickr/rest/</url> <interface>example.FlickrAPI</interface> <jaxb-package>example.data</jaxb-package> </web-service-client> </web-app>
</document>