254 lines
14 KiB
HTML
254 lines
14 KiB
HTML
|
<!DOCTYPE html>
|
||
|
|
<html lang="en">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
||
|
|
<meta charset="utf-8">
|
||
|
|
<title>Using VIVO with other servlet containers</title>
|
||
|
|
<link rel="stylesheet" href="./css/doc.css" media="screen">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div id="branding" role="banner">
|
||
|
|
<h1 class="vivo-logo"><a href="http://vivoweb.org"><span class="displace">VIVO</span></a></h1>
|
||
|
|
</div>
|
||
|
|
<div id="wrapper-content" role="main">
|
||
|
|
<h1>Using VIVO with other servlet containers</h1>
|
||
|
|
<div>
|
||
|
|
January 3, 2013
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
The default installation process for VIVO tells how to build and deploy VIVO
|
||
|
|
into a Tomcat servlet container. This document tells how to build VIVO so it can be used
|
||
|
|
in any servlet container that supports the Java Servlet 2.4 Specification.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
This process will produce:
|
||
|
|
<ul>
|
||
|
|
<li>a WAR file for the VIVO application,</li>
|
||
|
|
<li>a WAR file for the Solr application,</li>
|
||
|
|
<li>a TAR file for the Solr home directory, configured to work with VIVO.</li>
|
||
|
|
</ul>
|
||
|
|
These artifacts can then be installed into a servlet container (or more than one),
|
||
|
|
and configured to work together.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The configuration includes the customary <code>runtime.properties</code> file in the
|
||
|
|
Vitro home directory. It also requires items that tell the VIVO application
|
||
|
|
and the Solr application how to find their respective home directories. These
|
||
|
|
items are specific to the servlet container. However, they
|
||
|
|
are described so you can translate them to your container of choice.
|
||
|
|
</p>
|
||
|
|
<p><em>
|
||
|
|
Note: earlier releases of VIVO used a single <code>deploy.properties</code> file
|
||
|
|
to specify both build properties and runtime properties. This file has now been
|
||
|
|
split into <code>build.properties</code> and <code>runtime.properties</code>
|
||
|
|
</em></p>
|
||
|
|
<p>
|
||
|
|
Start by reading the customary <a href="install.html">
|
||
|
|
instructions for installing VIVO</a>, taking note of the Tomcat-specific sections.
|
||
|
|
This document will consist mostly of comparisons to those instructions.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<toc>
|
||
|
|
<h3>Creating a container-neutral VIVO</h3>
|
||
|
|
<ol>
|
||
|
|
<li>
|
||
|
|
<a href="#before_build">Before the build</a>
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
<a href="#build_script">Running the build script</a>
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
<a href="#deploy_solr">Deploying Solr</a>
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
<a href="#deploy_vivo">Deploying VIVO</a>
|
||
|
|
</li>
|
||
|
|
</ol>
|
||
|
|
</toc>
|
||
|
|
|
||
|
|
<h3 id="before_build">1. Before the build</h3>
|
||
|
|
<h4>Required software</h4>
|
||
|
|
<p>
|
||
|
|
Tomcat is not required. You can use any servlet container
|
||
|
|
that supports the Java Servlet 2.4 Specification.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<h4>Logging properties for VIVO</h4>
|
||
|
|
<p>
|
||
|
|
The logging properties for VIVO are determined by the file
|
||
|
|
<code>[vitro-core]/webapp/config/default.log4j.properties</code>.
|
||
|
|
<em>(Note: if <code>debug.log4j.properties</code> exists,
|
||
|
|
it will override <code>default.log4j.properties</code>).</em>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Notice how the location of the log file is determined:
|
||
|
|
<pre>log4j.appender.AllAppender.File=$${catalina.home}/logs/${webapp.name}.all.log</pre>
|
||
|
|
The filename of the log file is based on the <code>webapp.name</code> property
|
||
|
|
found in the <code>build.properties</code> file. This substitution is made during
|
||
|
|
the build process. The path to the log file is based on the system property
|
||
|
|
<code>catalina.home</code> which is set by Tomcat at runtime.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
You will likely want to change this line -- making it an absolute path, or
|
||
|
|
basing it on some other system property.
|
||
|
|
Notice that <code>ant</code> will substitute properties such as
|
||
|
|
<code>${webapp.name}</code> during the build process. The name of a system property
|
||
|
|
requires a second dollar sign, e.g. <code>$${catalina.home}</code> to protect it from <code>ant</code>.
|
||
|
|
<code>Ant</code> will remove the second dollar sign, but will not try to substitute
|
||
|
|
a value for the property. At runtime, when Log4J reads the properties file,
|
||
|
|
it will substitute the matching system property.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<h4>Logging properties for Solr</h4>
|
||
|
|
<p>
|
||
|
|
The logging properties for Solr are determined by the file
|
||
|
|
<code>[vitro-core]/webapp/config/solr/logging.properties</code>.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
As with VIVO, the location of the log file is based on the system property
|
||
|
|
<code>catalina.home</code> which is set by Tomcat at runtime.
|
||
|
|
<pre>org.apache.juli.FileHandler.directory = ${catalina.base}/logs</pre>
|
||
|
|
Note that only one dollar sign is used, since Ant does not attempt to
|
||
|
|
substitute properties in this file.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The syntax of the Solr logging properties is different from the syntax for VIVO.
|
||
|
|
This is because VIVO uses Log4J as a back end for the Commons Logging framework,
|
||
|
|
while Solr uses JULI as a back end for SLF4J.
|
||
|
|
</p>
|
||
|
|
<p><em>
|
||
|
|
Note: Solr is able to do this because Tomcat provides the JULI framework by default.
|
||
|
|
Other servlet containers may require JULI to be installed. If you encounter this as an issue, please
|
||
|
|
share your experience with the VIVO Development mailing list (<code>vivo-dev-all@lists.sourceforge.net</code>),
|
||
|
|
so we can improve our distribution.
|
||
|
|
</em></p>
|
||
|
|
|
||
|
|
<h4>The <code>build.properties</code> file</h4>
|
||
|
|
<p>
|
||
|
|
The standard installation instructions specify that these properties
|
||
|
|
are required in <code>build.properties</code>
|
||
|
|
<ul>
|
||
|
|
<li><code>vitro.core.dir</code></li>
|
||
|
|
<li><code>webapp.name</code></li>
|
||
|
|
<li><code>tomcat.home</code></li>
|
||
|
|
<li><code>vitro.home</code> <em>-- note that this was <code>vitro.home.directory</code>
|
||
|
|
in previous releases</em></li>
|
||
|
|
</ul>
|
||
|
|
However, if you are building with <code>ant distribute</code>, then only these are required:
|
||
|
|
<ul>
|
||
|
|
<li><code>vitro.core.dir</code></li>
|
||
|
|
<li><code>webapp.name</code></li>
|
||
|
|
</ul>
|
||
|
|
<code>tomcat.home</code> is ignored by the <code>distribute</code> target.
|
||
|
|
You may choose to specify <code>vitro.home</code> in <code>build.properties</code>,
|
||
|
|
or later, when you deploy VIVO (see <a href="#deploy_vivo">Deploying VIVO</a>).
|
||
|
|
If you specify <code>vitro.home</code> in <code>build.properties</code>, you can override
|
||
|
|
it when you deploy, but you will receive a warning when VIVO starts, saying that <code>vitro.home</code>
|
||
|
|
has been specified twice.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<h3 id="build_script">2. Running the build script</h3>
|
||
|
|
<p>
|
||
|
|
To build VIVO for other servlet containers, you will use one of these commands:
|
||
|
|
<ul>
|
||
|
|
<li><code>ant distribute</code> -- to incorporate changes since your previous build.</li>
|
||
|
|
<li><code>ant clean distribute</code> -- to do a full build from scratch</li>
|
||
|
|
</ul>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The build will produce a file named <code>distribution.tar.gz</code>, in the <code>.build</code>
|
||
|
|
sub-directory of your VIVO distribution directory. This compressed archive contains these files:
|
||
|
|
<ul>
|
||
|
|
<li><code>vivo.war</code> -- a WAR file for the main VIVO application.</li>
|
||
|
|
<li><code>vivosolr.war</code> -- a WAR file for the Solr application.</li>
|
||
|
|
<li><code>solrhome.tar</code> -- a Solr home directory that is configured for use with VIVO.</li>
|
||
|
|
</ul>
|
||
|
|
The WAR files will be deployed to your servlet container. They may be renamed as desired when deployed.
|
||
|
|
The TAR file will be unpacked to become your Solr home directory.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<h3 id="deploy_solr">3. Deploying Solr</h3>
|
||
|
|
<p>
|
||
|
|
The Solr application is packaged in <code>vivosolr.war</code>
|
||
|
|
(see <a href="#build_script">Running the build script</a>). Deploy this file
|
||
|
|
as required by your servlet container. The filename is not significant,
|
||
|
|
and the file may be renamed as required by your container.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The Solr home directory is packaged in <code>solrhome.tar</code>
|
||
|
|
(see <a href="#build_script">Running the build script</a>). Create a Solr
|
||
|
|
home directory on your machine, and unpack this file into that
|
||
|
|
directory. It is customary to use a <code>solr</code> sub-directory in your
|
||
|
|
Vitro home directory, but this is not required. Note that the Solr home directory
|
||
|
|
will contain VIVO's search index, so it may grow to be quite large.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
You must tell Solr where to find the home directory. You can use one of two
|
||
|
|
methods:
|
||
|
|
<ol>
|
||
|
|
<li>Set the sytem property <code>solr.solr.home</code> to the path of
|
||
|
|
your Solr home directory.</li>
|
||
|
|
<li>Set a JNDI value at <code>java:comp/env/solr/home</code> to the
|
||
|
|
path of your Solr home directory. For servlet containers, a JNDI
|
||
|
|
prefix of <code>java:comp/env/</code> is assumed for all environment
|
||
|
|
entries, so you will likely just specify a value for <code>solr/home</code>.
|
||
|
|
</li>
|
||
|
|
</ol>
|
||
|
|
Which of these methods should you use? In general, it is easier to set a
|
||
|
|
system property than an environment entry. However, a system property
|
||
|
|
applies across the entire servlet container. If you want to deploy
|
||
|
|
two instances of Solr in the same container, you will need to use environment
|
||
|
|
entries to give each instance its own home directory.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The Solr application must be authorized to read and write to the Solr home directory.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3 id="deploy_vivo">4. Deploying VIVO</h3>
|
||
|
|
<p>
|
||
|
|
The VIVO application is packaged in <code>vivo.war</code>
|
||
|
|
(see <a href="#build_script">Running the build script</a>). Deploy this file
|
||
|
|
as required by your servlet container. The filename is not significant,
|
||
|
|
and the file may be renamed as required by your container.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
You must create a Vitro home directory.
|
||
|
|
You must create a <code>runtime.properties</code> file in the Vitro home directory.
|
||
|
|
The contents of this file are exactly as specified in the standard installaion
|
||
|
|
instructions. Pay attention to the value of <code>vitro.local.solr.url</code>.
|
||
|
|
This must point to the base of the Solr application, as you have deployed it.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
You must tell VIVO where to find the Vitro home directory.
|
||
|
|
If you did not specify this in <code>build.properties</code>, you can use
|
||
|
|
one of two methods:
|
||
|
|
<ol>
|
||
|
|
<li>Set the sytem property <code>vitro.vitro.home</code> to the path of
|
||
|
|
your Vitro home directory.</li>
|
||
|
|
<li>Set a JNDI value at <code>java:comp/env/vitro/home</code> to the
|
||
|
|
path of your Vitro home directory. For servlet containers, a JNDI
|
||
|
|
prefix of <code>java:comp/env/</code> is assumed for all environment
|
||
|
|
entries, so you will likely just specify a value for <code>vitro/home</code>.
|
||
|
|
</li>
|
||
|
|
</ol>
|
||
|
|
Which of these methods should you use? In general, it is easier to set a
|
||
|
|
system property than an environment entry. However, a system property
|
||
|
|
applies across the entire servlet container. If you want to deploy
|
||
|
|
two instances of VIVO in the same container, you will need to use environment
|
||
|
|
entries to give each instance its own home directory.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
The VIVO application must be authorized to read and write to the Vitro home directory.
|
||
|
|
</p>
|
||
|
|
<p><em>
|
||
|
|
Note: Session object in VIVO are not serializable, and therefore cannot be
|
||
|
|
made persistent. The standard build process tells Tomcat not to attempt to
|
||
|
|
persist Sessions. You may need to set a similar configuration option in your
|
||
|
|
servlet container.
|
||
|
|
</em></p>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|