<document>
<header>
<title>Packaging/Deployment</title>
<description>
<p>Resin provides a wide variety of custom packaging and deployment
options.
</p>
</description>
</header>

<body>

<localtoc/>

<s1 title="Custom web-app with .war file">

<p>In this scenario, you want to configure a web-app with a
specific root-directory and specify the location of the .war file.
As usual, when Resin sees any changes in the .war file, it will expand
the new data into the root-directory and restart the web-app.  This
capability, gives sites more flexibility where their directories and
archive files should be placed, beyond the standard webapps directory.</p>

<p>The optional <code>archive-path</code> argument of the
&lt;web-app> will point to the .war file to be expanded.</p>

<deftable title="web-app deployment options">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>archive-path</td>
  <td>path to the .war file which contains the web-app's contents</td>
  <td></td>
</tr>
<tr>
  <td>dependency-check-interval</td>
  <td>how often Resin should check for changes in the web-app for a redeployment</td>
  <td>2s</td>
</tr>
<tr>
  <td>id</td>
  <td>unique identifier for the web-app and the default context-path value</td>
  <td></td>
</tr>
<tr>
  <td>redeploy-check-interval</td>
  <td>how often Resin should check the .war file for changes</td>
  <td>60s</td>
</tr>
<tr>
  <td>redeploy-mode</td>
  <td>how Resin should handle redeployment: automatic, lazy, or manual</td>
  <td>automatic</td>
</tr>
<tr>
  <td>root-directory</td>
  <td>path to the expanded web-app directory</td>
  <td><var>id</var> as a sub-directory of the virtual-hosts's root</td>
</tr>
</deftable>

<example title="Example: resin.xml for custom web-app">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="">
  &lt;host id="">

    <b>&lt;web-app id="/foo" root-directory="/var/www/foo"
             archive-path="/usr/local/stage/foo.war"/></b>

  &lt;/host>
&lt;/cluster>
&lt;/resin>
</example>

</s1>

<s1 title="Startup and Redeploy Modes">
<p>
The startup-mode is used in a number of places to determine the behaviour of a resource when the server starts.
</p>

<p>
The startup-mode has three values: "automatic", "lazy", and "manual".
</p>

<ul>
  <li>automatic - starts the resource on server start (default)</li>
  <li>lazy - starts the resource on the first use</li>
  <li>manual - waits for JMX to start the resource</li>
</ul>

<p>
The redeploy-mode is used in a number of places to determine the behaviour of a resource when it is replaced or modified while the server is running.
</p>

<p>
The redeploy-mode has two values: "automatic", and "manual".
</p>

<ul>
  <li>automatic - restarts the resource when it is modified (web.xml, *.class, *.war, etc).</li>
  <li>manual - waits for JMX to restart the resource when changes occur.</li>
</ul>
</s1>

<s1 title="web-app versioning">

<p>Resin can deploy multiple versions of a web-app simultaneously,
simplifying any application upgrades.  The old version of the web-app
will continue to receive old sessions, while the new version will get
the new requests.  So any user will see a consistent version as the
web site update occurs with no downtime required.</p>

<p>The versioning requires &lt;web-app-deploy>, i.e. it works with
the webapps directory.  The versioning is numerically-based, allowing
dotted notation, to determine the most recent version.  A simple deployment
process might use <var>foo-101</var> to upgrade from <var>foo-100</var>.
A more complicated one might use <var>foo-10.3.14</var> to upgrade from
<var>foo-10.3.13</var>.</p>

<p>The <var>versioning</var> attribute of the &lt;web-app-deploy>
enables versioning:</p>

<example title="Example: resin.xml for webapps versioning">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="">
&lt;host id="">

  <b>&lt;web-app-deploy path="webapps" versioning="true"/></b>

&lt;/host>
&lt;/cluster>
&lt;/resin>
</example>

</s1>

<s1 title="Deploying to a live server without interruption">
<p>It may be possible to deploy a web application to a live server
without interruption to service if certain conditions are met.</p>

<ol>
  <li>The session objects for your users are being persisted.
  </li><li>The usage of session scoped objects between the old version and the new is compatible.
  </li><li>The usage of application scoped objects between the old version and the new is compatible.
  </li><li>Database schema changes are not required.
</li></ol>

<p>Resin allows you to have a backup instance running.  The idea is that
this backup instance of Resin takes over if your primary Resin
instance goes down.</p>

<p>If you are using a load balancer to distribute your load to multiple
primary servers, each primary server has a backup server.</p>

<p>You can use this feature to deploy to a live server without
interruption of service.</p>

<ol>
<li>shutdown primary server(s) (backup server(s) takes over)

</li><li>deploy new war to primary server(s)

</li><li>start primary server(s).  As soon as the primary server starts,
the user will be using the new version of the application.
    
</li><li>deploy new war to backup server(s)
</li></ol>

</s1>

<s1 title="Browser-based Remote Deployment">
<p>
As of Resin 4.0.0, it is now possible to deploy web applications remotely
to a shared repository that is distributed across the cluster.  This feature
allows you to deploy once to any triad server and have the application
be updated automatically across the entire cluster.  When a new 
<a href="clustering-overview.xtp">dynamic server</a> joins the cluster, the
triad will populate it with these applications as well.
</p>
<p>
To deploy an application remotely:
</p>
<ol>
<li>log into the resin-admin console on
any triad server.  <em>Make sure you are connecting over SSL, as this feature
is not available over a non-encrypted channel.</em></li>
<li>Browse to the "webapp" tab of the resin-admin server and at the bottom
of the page, enter the virtual host, URL, and local .war file specifying
the web application, then press "Deploy".
<figure src="deploy-webapp.png"/>
</li>
<li>
The application should now be deployed on the server.  In a few moments,
all the servers in the cluster will have the webapp.
<figure src="deployed-webapp.png"/>
</li>
</ol>
</s1>

<s1 title="ant/maven Remote Deployment">

<p>With remote deployment, you can use an ant or maven task to deploy
a .war file to a running Resin instance.  This will require some configuration
of the resin.xml to enable deployment.  For security reasons, remote
deployment and administration is disabled by default, so you will need
to enable the features to use them.</p>

<ul>
<li>Enable remote administration (the HMTP service).</li>
<li>Add at least one admin user in AdminAuthenticator.</li>
<li>Enable the remote deploy service.</li>
</ul>

<p>The first step is enabling remote administration, so you can manage
the server remotely, either with eclipse, or ant, or maven.
If disabled, Resin will ignore all remote administration requests.
The disabled error message will be something like "Failed to connect
to HMTP because HMTP service has not been enabled."  In
the resin.xml, the &lt;resin:RemoteAdminService> tag enables remote
administration:</p>

<example title="Example: resin.xml enable remote administration">
&lt;resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="urn:java:com.caucho.resin">
       ...

  &lt;resin:AdminAuthenticator>
     &lt;resin:user name="harry" password="..."/>
  &lt;/resin:AdminAuthenticator>
  
  &lt;cluster id="">
  
    &lt;resin:RemoteAdminService/>
    &lt;resin:DeployService/>

    ...
  &lt;/cluster>
&lt;/resin>
</example>

<p>The second step is adding at least one administration user, so only
authorized administrators can update the server.  The <a
href="security.xtp">&lt;resin:AdminAuthenticator></a> tag configures
administrators.  If no administrators are added, Resin will reject any
remote administration requests.</p>

<p>The third step is enabling the deploy service itself with the
&lt;resin:DeployService> tag.  The deploy service is responsible for
managing uploads of new applications and distributing them to the
servers in the cluster.</p>

<p>When troubleshooting, it's helpful to know that Resin uses BAM/HMTP
to connect the deployment client with the deployment server.  The
&lt;resin:RemoteAdminService> enables BAM/HMTP.  If the server is down
or the remote admin service isn't enabled, the error messages will
complain that the BAM/HMTP connection is not allowed.</p>

</s1>

</body>
</document>
