litvinovg/vivo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

VIVO-2 Modify the build so installers can create a container-neutral VIVO.

Browse source 
Split deploy.properties into build.properties and runtime.properties, with runtime.properties going into the Vitro home directory. Modify ConfigurationProperties to locate the Vitro home directory, either by System property or JNDI Environment variable, or from build.properties, and to read from both build.properties and runtime.properties. Revise the install and upgrade documents for VIVO and Vitro. Change comments and error messages that referred to deploy.properties by name.
This commit is contained in:
j2blake 2013-01-16 14:52:35 -05:00
parent aab76220c7
commit 89f759fcbc
14 changed files with 942 additions and 221 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.gitignore vendored
View file

@ -4,3 +4,5 @@
/.settings /.settings
/bin/ /bin/
/deploy.properties /deploy.properties
/build.properties
/runtime.properties

22
build.xml
View file

@ -5,13 +5,15 @@
<!-- ====================================================================== <!-- ======================================================================
Build script for the NIH VIVO product. Build script for the NIH VIVO product.
The deploy.properties file contains both build properties and runtime The build.properties file contains build properties
properties. The runtime.properties file contains runtime properties.
The required build properties are: The required build properties are:
vitroCore.dir vitroCore.dir
tomcat.home
webapp.name webapp.name
A standard tomcat deploy also requires:
vitro.home
tomcat.home
====================================================================== --> ====================================================================== -->
<project name="nihvivo" default="describe"> <project name="nihvivo" default="describe">
@ -23,18 +25,18 @@
<property name="appbase.dir" location="${build.dir}/appBase" /> <property name="appbase.dir" location="${build.dir}/appBase" />
<!-- <!--
Load the properties from deploy.properties. Load the properties from build.properties.
--> -->
<property name="deploy.properties.file" location="deploy.properties" /> <property name="build.properties.file" location="build.properties" />
<fail message="You must create a &quot;${deploy.properties.file}&quot; file."> <fail message="You must create a &quot;${build.properties.file}&quot; file.">
<condition> <condition>
<not> <not>
<available file="${deploy.properties.file}" /> <available file="${build.properties.file}" />
</not> </not>
</condition> </condition>
</fail> </fail>
<property file="${deploy.properties.file}" /> <property file="${build.properties.file}" />
<fail unless="vitro.core.dir" message="${deploy.properties.file} must contain a value for vitro.core.dir" /> <fail unless="vitro.core.dir" message="${build.properties.file} must contain a value for vitro.core.dir" />
<!-- <!--
Base it all on the core build file. Base it all on the core build file.
@ -46,7 +48,7 @@
Override the core version, so we can merge the two levels before building. Override the core version, so we can merge the two levels before building.
- - - - - - - - - - - - - - - - - --> - - - - - - - - - - - - - - - - - -->
<target name="prepare" depends="compileUtilities,product-prepare,vitroCore.prepare" /> <target name="prepare" depends="product-prepare,vitroCore.prepare" />
<!-- - - - - - - - - - - - - - - - - - <!-- - - - - - - - - - - - - - - - - -
target: product-prepare target: product-prepare

12
doc/developers.txt
View file

@ -10,23 +10,23 @@ instructions in "install.html", in this directory.
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
If you are working from the VIVO source files, checked out from the Subversion If you are working from the VIVO source files, checked out from the Git
repository, then your working area does not contain the "vitro-core" directory. repository, then your working area does not contain the "vitro-core" directory.
Follow these steps: Follow these steps:
1) In the VIVO working area, create deploy.properties as a copy of 1) In the VIVO working area, create build.properties as a copy of
example.deploy.properties example.build.properties
2) Check out the Vitro source files from Subversion into a separate working 2) Check out the Vitro source files from Git into a separate working
area. area.
3) Modify deploy.properties (created in step 1) so vitro.core.dir points to 3) Modify build.properties (created in step 1) so vitro.core.dir points to
the Vitro working area (created in step 2). For example: the Vitro working area (created in step 2). For example:
vitro.core.dir = ../vitro vitro.core.dir = ../vitro
4) Follow the instructions in "install.html" to complete the installation, 4) Follow the instructions in "install.html" to complete the installation,
omitting step III. omitting step 3.
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
Answers to Frequently Asked Questions: Answers to Frequently Asked Questions:

272
doc/install.html
View file

@ -33,7 +33,11 @@
install over an existing installation of an earlier version. install over an existing installation of an earlier version.
</p><p> </p><p>
If you are going to upgrade an existing service, please consult If you are going to upgrade an existing service, please consult
the <a href="upgrades.html">upgrade</a> in this directory. the <a href="upgrades.html">latest upgrade file</a> in this directory.
</p><p>
Other servlet containers: If you want to use a servlet container
other than Tomcat, please consult <a href="other_servlet_containers.html">
instructions for other servlet containers</a> in this directory.
</p><p> </p><p>
VIVO Developers: If you are working on the VIVO source code from VIVO Developers: If you are working on the VIVO source code from
Subversion, the instructions are slightly different. Please consult Subversion, the instructions are slightly different. Please consult
@ -48,30 +52,33 @@
<h4>The VIVO distribution directory</h4> <h4>The VIVO distribution directory</h4>
<p> <p>
This is created when you unpack the VIVO distribution file This is created when you unpack the VIVO distribution file
(see <a href="#download_code">Step III</a>, below). This is where you will (see <a href="#download_code">Step 3</a>, below). This is where you will
create your deploy.properties file (see <a href="#deploy_properties">Step create your build.properties file (see <a href="#build_properties">Step
IV</a>, below), and where you will make any modifications to the VIVO 4</a>, below), and where you will make any modifications to the VIVO
theme or code. You can create this wherever you choose. theme or code. You can create this wherever you choose.
</p> </p>
<h4>VIVO inside Tomcat</h4> <h4>VIVO inside Tomcat</h4>
<p> <p>
When you run the build script to compile and deploy VIVO When you run the build script to compile and deploy VIVO
(see <a href="#deploy">Step VI</a>, below), the files will be deployed to a (see <a href="#deploy">Step 6</a>, below), the files will be deployed to a
directory inside Tomcat. This is the actual executing code for VIVO, directory inside Tomcat. This is the actual executing code for VIVO,
but you won’t need to look at it or change it. If you need to change but you won’t need to look at it or change it. If you need to change
VIVO, make the changes in the distribution directory, and run the build VIVO, make the changes in the distribution directory, and run the build
script again. Tell the build script where to find Tomcat by setting <code>tomcat.home</code> script again. Tell the build script where to find Tomcat by setting <code>tomcat.home</code>
in the deploy.properties file (see <a href="#deploy_properties">Step IV</a>, in the build.properties file (see <a href="#build_properties">Step 4</a>,
below). below).
</p> </p>
<h4>The VIVO home directory</h4> <h4>The VIVO home directory</h4>
<p> <p>
VIVO will use this area to store some of the data it uses. Uploaded This directory contains the runtime configuration properties for VIVO.
VIVO will also use this area to store some of its data. Uploaded
image files are stored here, and the Solr home directory is stored here also. image files are stored here, and the Solr home directory is stored here also.
You can create this wherever you choose. Tell VIVO where to find the You can create this wherever you choose. Tell VIVO where to find the
home directory by setting <code>vitro.home.directory</code> home directory by setting <code>vitro.home</code>
in the deploy.properties file (see <a href="#deploy_properties">Step IV</a>, in the build.properties file (see <a href="#build_properties">Step 4</a>,
below). You must create this directory before starting VIVO, and you below). You must create this directory before starting VIVO,
you must create the <code>runtime.properties</code> file in this directory
(see <a href="#runtime_properties">Step 5</a>, below), and you
must ensure that Tomcat has permission to read and write to this must ensure that Tomcat has permission to read and write to this
directory when it runs. directory when it runs.
</p> </p>
@ -79,13 +86,13 @@
<p> <p>
Essentially all of the data that you store in VIVO will be given to Essentially all of the data that you store in VIVO will be given to
MySQL for storage. The actual location of this data depends on what MySQL for storage. The actual location of this data depends on what
system you have, and on how you install MySQL (see <a href="#required_software">Step I</a>, below). but you won’t need to system you have, and on how you install MySQL (see <a href="#required_software">Step 1</a>, below). but you won’t need to
know the location. You will access the data through VIVO, or know the location. You will access the data through VIVO, or
occasionally through the MySQL client application. occasionally through the MySQL client application.
</p> </p>
<toc> <toc>
<h3>Steps to Installation</h3> <h3>Steps to Installation</h3>
<ol class="roman1"> <ol>
<li> <li>
<a href="#required_software">Install required software</a> <a href="#required_software">Install required software</a>
</li> </li>
@ -96,7 +103,10 @@
<a href="#download_code">Download the VIVO Application Source</a> <a href="#download_code">Download the VIVO Application Source</a>
</li> </li>
<li> <li>
<a href="#deploy_properties">Specify deployment properties</a> <a href="#build_properties">Specify build properties</a>
</li>
<li>
<a href="#runtime_properties">Specify runtime properties</a>
</li> </li>
<li> <li>
<a href="#deploy">Compile and deploy</a> <a href="#deploy">Compile and deploy</a>
@ -132,7 +142,7 @@
</li> </li>
</ol> </ol>
</toc> </toc>
<h3 id="required_software">I. Install required software </h3> <h3 id="required_software">1. Install required software </h3>
<p> <p>
Before installing VIVO, make sure that the following software is Before installing VIVO, make sure that the following software is
installed on the desired machine: installed on the desired machine:
@ -186,7 +196,7 @@
</li> </li>
</ul> </ul>
<h3 id="create_database">II. Create an empty MySQL database </h3> <h3 id="create_database">2. Create an empty MySQL database </h3>
<p> <p>
Decide on a database name, username, and password. Log into your Decide on a database name, username, and password. Log into your
MySQL server and create a new database in MySQL that uses <code>UTF-8 MySQL server and create a new database in MySQL that uses <code>UTF-8
@ -208,7 +218,7 @@
Keep track of the database name, username, and password for Step Keep track of the database name, username, and password for Step
IV. IV.
</p> </p>
<h3 id="download_code">III. Download the VIVO Application Source <h3 id="download_code">3. Download the VIVO Application Source
<br> <br>
</h3> </h3>
<p> <p>
@ -218,11 +228,19 @@
<br> <br>
<a href="http://vivoweb.org/download">http://vivoweb.org/download</a> <a href="http://vivoweb.org/download">http://vivoweb.org/download</a>
</p> </p>
<h3 id="deploy_properties">IV. Specify deployment properties </h3> <h3 id="build_properties">4. Specify build properties </h3>
<p> <p>
At the top level of the VIVO distribution directory, copy the file <code>example.deploy.properties</code> At the top level of the VIVO distribution directory,
to a file named simply <code>deploy.properties</code>. This file sets copy the file <code>example.build.properties</code>
several properties used in compilation and deployment. to a file named simply <code>build.properties</code>.
Edit the file to suit your installation, as described in the following table.
</p>
<p>
These properties are used in compilation and deployment.
They will be incorporated into VIVO when it is compiled in
<a href="#deploy">Step 6</a>. If you want to change these properties at
a later date, you will need to stop Tomcat, repeat <a href="#deploy">Step 6</a>,
and restart Tomcat.
</p> </p>
<p> <p>
<em>Windows:</em> <em>Windows:</em>
@ -230,14 +248,7 @@
system, include the windows drive and use the forward slash "/" and not system, include the windows drive and use the forward slash "/" and not
the back slash "\" in the directory locations, e.g. <code>c:/tomcat</code>. the back slash "\" in the directory locations, e.g. <code>c:/tomcat</code>.
</p> </p>
<p>
<em>External authentication:</em>
If you want to use an external
authentication system like Shibboleth or CUWebAuth, you will need to
set two additional properties in this file. See the step below
entitled <a href="#external_auth">Using an External Authentication
System with VIVO</a>.
</p>
<table border='1' bordercolor="#CCCCCC" cellspacing="5"> <table border='1' bordercolor="#CCCCCC" cellspacing="5">
<tbody> <tbody>
<tr> <tr>
@ -248,30 +259,6 @@
Example Value Example Value
</th> </th>
</tr> </tr>
<tr>
<td colspan="2">
Default namespace: VIVO installations make their
RDF resources available for harvest using linked data. Requests for RDF
resource URIs redirect to HTML or RDF representations as specified by
the client. To make this possible, VIVO's default namespace must have a
certain structure and begin with the public web address of the VIVO
installation. For example, if the web address of a VIVO installation is
"http://vivo.example.edu/" the default namespace must be set to
"http://vivo.example.edu/individual/" in order to support linked data.
Similarly, if VIVO is installed at "http://www.example.edu/vivo" the
default namespace must be set to
"http://www.example.edu/vivo/individual/"<h5>* The namespace must end with "individual/" (including the
trailing slash).</h5>
</td>
</tr>
<tr class="odd_row">
<td>
Vitro.defaultNamespace
</td>
<td>
http://vivo.mydomain.edu/individual/
</td>
</tr>
<tr> <tr>
<td colspan="2"> <td colspan="2">
Directory where Vitro code is located. In most Directory where Vitro code is located. In most
@ -313,6 +300,90 @@
vivo vivo
</td> </td>
</tr> </tr>
<tr>
<td colspan="2">
Directory where the VIVO application will store
the data that it creates. This includes uploaded files (usually images)
and the Solr search index. Be sure this directory exists and is
writable by the user who the Tomcat service is running as.
</td>
</tr>
<tr class="odd_row">
<td>
vitro.home
</td>
<td>
/usr/local/vivo/home
</td>
</tr>
</tbody>
</table>
<h3 id="runtime_properties">5. Specify runtime properties </h3>
<p>
In <a href="#build_properties">Step 4</a>, you defined the location of the Vitro home directory,
by specifying <code>vitro.home</code> in the <code>build.properties</code> file.
Create that directory now.
</p>
<p>
At the top level of the VIVO distribution directory, you will find a file called
<code>example.runtime.properties</code>. Copy this to the Vitro home directory you have created,
renaming the copy to <code>runtime.properties</code>.
Edit the file to suit your installation, as described in the following table.
</p>
<p>
These properties are loaded when VIVO starts up. If you want to change these
properties at a later date, you will need to restart Tomcat for them to take
effect. You will not need to repeat <a href="#deploy">Step 6</a>.
</p>
<p>
<em>Windows:</em>
For those installing on Windows operating
system, include the windows drive and use the forward slash "/" and not
the back slash "\" in the directory locations, e.g. <code>c:/tomcat</code>.
</p>
<p>
<em>External authentication:</em>
If you want to use an external
authentication system like Shibboleth or CUWebAuth, you will need to
set additional properties in this file. See the step below
entitled <a href="#external_auth">Using an External Authentication
System with VIVO</a>.
</p>
<table border='1' bordercolor="#CCCCCC" cellspacing="5">
<tbody>
<tr>
<th>
Property Name
</th>
<th>
Example Value
</th>
</tr>
<tr>
<td colspan="2">
Default namespace: VIVO installations make their
RDF resources available for harvest using linked data. Requests for RDF
resource URIs redirect to HTML or RDF representations as specified by
the client. To make this possible, VIVO's default namespace must have a
certain structure and begin with the public web address of the VIVO
installation. For example, if the web address of a VIVO installation is
"http://vivo.example.edu/" the default namespace must be set to
"http://vivo.example.edu/individual/" in order to support linked data.
Similarly, if VIVO is installed at "http://www.example.edu/vivo" the
default namespace must be set to
"http://www.example.edu/vivo/individual/"<h5>* The namespace must end with "individual/" (including the
trailing slash).</h5>
</td>
</tr>
<tr class="odd_row">
<td>
Vitro.defaultNamespace
</td>
<td>
http://vivo.mydomain.edu/individual/
</td>
</tr>
<tr> <tr>
<td colspan="2"> <td colspan="2">
URL of Solr context used in local VIVO search. URL of Solr context used in local VIVO search.
@ -330,53 +401,6 @@
http://localhost:8080/vivosolr http://localhost:8080/vivosolr
</td> </td>
</tr> </tr>
<tr>
<td colspan="2">
Restricts access to the Solr search platform.
One or more regular expressions, separated by commas. When a request is
made to Solr, the IP address of the requestor must match one of the
patterns, or the request will be rejected.
<br>
Examples:<code>
<ul>
<li>
vitro.local.solr.ipaddress.mask = 127\.0\.0\.1
</li>
<li>
vitro.local.solr.ipaddress.mask =
127\.0\.0\.1,0:0:0:0:0:0:0:1
</li>
<li>
vitro.local.solr.ipaddress.mask = 169.254.*
</li>
</ul>
</code>
</td>
</tr>
<tr class="odd_row">
<td>
vitro.local.solr.ipaddress.mask
</td>
<td>
127\.0\.0\.1|[0:]+:1
</td>
</tr>
<tr>
<td colspan="2">
Directory where the VIVO application will store
the data that it creates. This includes uploaded files (usually images)
and the Solr search index. Be sure this directory exists and is
writable by the user who the Tomcat service is running as.
</td>
</tr>
<tr class="odd_row">
<td>
vitro.home.directory
</td>
<td>
/usr/local/vivo/data
</td>
</tr>
<tr> <tr>
<td colspan="2"> <td colspan="2">
Specify an SMTP host that the application will Specify an SMTP host that the application will
@ -692,7 +716,7 @@
<td colspan="2"> <td colspan="2">
These values are used when deploying VIVO as an OpenSocial container These values are used when deploying VIVO as an OpenSocial container
and integrating with OpenSocial gadgets and integrating with OpenSocial gadgets
(see <a href="#opensocial">Step XII</a>, below). If you are creating (see <a href="#opensocial">Step 13</a>, below). If you are creating
a VIVO installation that does not use OpenSocial gadgets, these values are omitted. a VIVO installation that does not use OpenSocial gadgets, these values are omitted.
</td> </td>
</tr> </tr>
@ -711,7 +735,7 @@
</tbody> </tbody>
</table> </table>
<h3 id="deploy">V. Compile and deploy</h3> <h3 id="deploy">6. Compile and deploy</h3>
<p> <p>
At the command line, from the top level of the VIVO distribution At the command line, from the top level of the VIVO distribution
directory, type: directory, type:
@ -720,7 +744,7 @@
<p> <p>
to build VIVO and deploy to Tomcat's webapps directory. to build VIVO and deploy to Tomcat's webapps directory.
</p> </p>
<h3 id="tomcat_settings">VI. Configure Tomcat</h3> <h3 id="tomcat_settings">7. Configure Tomcat</h3>
<h4>Set JVM parameters</h4> <h4>Set JVM parameters</h4>
<p> <p>
VIVO copies small sections of your RDF database into VIVO copies small sections of your RDF database into
@ -763,7 +787,7 @@
accepting percent-encoded UTF-8. accepting percent-encoded UTF-8.
</p> </p>
<p> <p>
Edit Tomcat's conf/server.xml and add the following attribute to each of the Edit Tomcat's <code>conf/server.xml</code> and add the following attribute to each of the
Connector elements: URIEncoding="UTF-8". Connector elements: URIEncoding="UTF-8".
</p> </p>
<pre> <pre>
@ -775,6 +799,9 @@
&lt;/Service&gt; &lt;/Service&gt;
&lt;/Server&gt; &lt;/Server&gt;
</pre> </pre>
<p>
Note: some versions of Tomcat already include this attribute as the default.
</p>
<h4>Take care when creating Context elements</h4> <h4>Take care when creating Context elements</h4>
<p> <p>
Each of the webapps in the VIVO distribution (VIVO and Each of the webapps in the VIVO distribution (VIVO and
@ -789,11 +816,11 @@
from the overridden context fragment. from the overridden context fragment.
</p> </p>
<p> <p>
See <a href="#tomcat_connector">Step X</a> below, See <a href="#tomcat_connector">Step 11</a> below,
for an example of overriding the VIVO context fragment. for an example of overriding the VIVO context fragment.
</p> </p>
<h3 id="start_tomcat">VII. Start Tomcat </h3> <h3 id="start_tomcat">8. Start Tomcat </h3>
<p> <p>
Most Tomcat installations can be started by running <code>startup.sh</code> Most Tomcat installations can be started by running <code>startup.sh</code>
or <code>startup.bat</code> in Tomcat's bin directory. Point your or <code>startup.bat</code> in Tomcat's bin directory. Point your
@ -805,9 +832,9 @@
problem is detected the normal VIVO pages will redirect problem is detected the normal VIVO pages will redirect
to a startup status page describing the problem. You to a startup status page describing the problem. You
can stop tomcat, attempt to fix the problem and can stop tomcat, attempt to fix the problem and
proceeded from <a href="#deploy">Step V</a>. The proceeded from <a href="#deploy">Step 6</a>. The
startup status page may offer a continue link which startup status page may offer a continue link which
will allow you to use VIVO inspite of the problems. will allow you to use VIVO in spite of the problems.
<p> <p>
If Tomcat does not start up, or the VIVO application If Tomcat does not start up, or the VIVO application
@ -817,7 +844,7 @@
or <code>tomcat/logs/vivo.all.log</code> or <code>tomcat/logs/vivo.all.log</code>
or <code>tomcat/logs/localhost.log</code> or <code>tomcat/logs/localhost.log</code>
</p> </p>
<h3 id="add_rdf">VIII. Log in and add RDF data </h3> <h3 id="add_rdf">9. Log in and add RDF data </h3>
<p> <p>
If the startup was successful, you will see a welcome If the startup was successful, you will see a welcome
message informing you that you have successfully message informing you that you have successfully
@ -863,7 +890,7 @@
See more documentation for configuring VIVO, ingesting data, and See more documentation for configuring VIVO, ingesting data, and
manually adding data at <a href="http://vivoweb.org/support">http://vivoweb.org/support</a>. manually adding data at <a href="http://vivoweb.org/support">http://vivoweb.org/support</a>.
</p> </p>
<h3 id="contact_email">IX. Set the Contact Email Address (if using <h3 id="contact_email">10. Set the Contact Email Address (if using
"Contact Us" form)</h3> "Contact Us" form)</h3>
<p> <p>
If you have configured your application to use the "Contact Us" If you have configured your application to use the "Contact Us"
@ -885,7 +912,7 @@
provide an email address in this step, your users will receive a java provide an email address in this step, your users will receive a java
error in the interface. error in the interface.
</p> </p>
<h3 id="tomcat_connector">X. Set up Apache Tomcat Connector </h3> <h3 id="tomcat_connector">11. Set up Apache Tomcat Connector </h3>
<p> <p>
It is recommended that a Tomcat Connector such as mod_jk be used to It is recommended that a Tomcat Connector such as mod_jk be used to
ensure that the site address does not include the port number (e.g. ensure that the site address does not include the port number (e.g.
@ -937,17 +964,12 @@
cookies="true" &gt; cookies="true" &gt;
&lt;Manager pathname="" /&gt; &lt;Manager pathname="" /&gt;
&lt;Environment type="java.lang.String" override="false"
name="path.configuration"
value="deploy.properties"
/&gt;
&lt;/Context&gt; &lt;/Context&gt;
... ...
</pre> </pre>
<h3 id="external_auth">XI. Using an External Authentication System <h3 id="external_auth">12. Using an External Authentication System
with VIVO </h3> with VIVO </h3>
<p> <p>
</p> </p>
@ -984,7 +1006,7 @@
<h4>Configuring VIVO</h4> <h4>Configuring VIVO</h4>
<p> <p>
To enable external authentication, VIVO requires three values in To enable external authentication, VIVO requires three values in
the <code>deploy.properties</code> the <code>runtime.properties</code>
file. file.
</p> </p>
<ul> <ul>
@ -999,7 +1021,7 @@
</p> </p>
<p> <p>
You need to tell VIVO the name of that HTTP header. Insert a You need to tell VIVO the name of that HTTP header. Insert a
line like this in the deploy.properties file: line like this in the runtime.properties file:
</p> </p>
<pre>externalAuth.netIdHeaderName = [the header name]</pre> <pre>externalAuth.netIdHeaderName = [the header name]</pre>
<p> <p>
@ -1013,7 +1035,7 @@
the VIVO login form. You need to tell VIVO what text should appear in the VIVO login form. You need to tell VIVO what text should appear in
that button. that button.
<p> <p>
Put a line like this in the deploy.properties file: Put a line like this in the runtime.properties file:
externalAuth.buttonText = [the text for your login button] For example: externalAuth.buttonText = [the text for your login button] For example:
</p> </p>
<pre>externalAuth.buttonText = Log in using BearCat Shibboleth</pre> <pre>externalAuth.buttonText = Log in using BearCat Shibboleth</pre>
@ -1030,7 +1052,7 @@
data model for a person with a property that matches the User’s network data model for a person with a property that matches the User’s network
ID (the value of the property must be either a String literal or an ID (the value of the property must be either a String literal or an
untyped literal). You need to tell VIVO what property should be used untyped literal). You need to tell VIVO what property should be used
for matching. Insert a line like this in the deploy.properties file: for matching. Insert a line like this in the runtime.properties file:
</p> </p>
<pre>selfEditing.idMatchingProperty = [the URI of the property]</pre> <pre>selfEditing.idMatchingProperty = [the URI of the property]</pre>
<p> <p>
@ -1040,7 +1062,7 @@
</li> </li>
</ul> </ul>
<h3 id="opensocial">XII. Using VIVO as an OpenSocial platform </h3> <h3 id="opensocial">13. Using VIVO as an OpenSocial platform </h3>
<p> <p>
VIVO now supports an extension of the OpenSocial API, VIVO now supports an extension of the OpenSocial API,
known as Open Research Networking Gadgets, or ORNG (pronounced "ORNG") known as Open Research Networking Gadgets, or ORNG (pronounced "ORNG")
@ -1056,18 +1078,18 @@
<a href="setting_up_orng.html">setting_up_orng.html</a> in this directory. <a href="setting_up_orng.html">setting_up_orng.html</a> in this directory.
</p> </p>
<h3 id="installation_check">XIII. Was the installation successful? </h3> <h3 id="installation_check">14. Was the installation successful? </h3>
<p> <p>
If you have completed the previous steps, you have good indications If you have completed the previous steps, you have good indications
that the installation was successful. that the installation was successful.
</p> </p>
<ul> <ul>
<li> <li>
Step VII showed that Tomcat recognized the webapp, and that the Step 8 showed that Tomcat recognized the webapp, and that the
webapp was able to present the initial page. webapp was able to present the initial page.
</li> </li>
<li> <li>
Step VIII verified that you can log in to the administrator Step 9 verified that you can log in to the administrator
account. account.
</li> </li>
</ul> </ul>
@ -1149,7 +1171,7 @@
index</strong>. index</strong>.
</li> </li>
</ul> </ul>
<h3 id="termsofuse">XIII. Review the VIVO Terms of Use</h3> <h3 id="termsofuse">15. Review the VIVO Terms of Use</h3>
<p> <p>
VIVO comes with a "Terms of Use" statement linked from the footer. VIVO comes with a "Terms of Use" statement linked from the footer.
The "Site Name" you assign in the "Site Information" form under the <strong>Site Admin</strong> The "Site Name" you assign in the "Site Information" form under the <strong>Site Admin</strong>

254
doc/other_servlet_containers.html Normal file
View file

@ -0,0 +1,254 @@
<!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>

32
doc/setting_up_orng.html
View file

@ -33,6 +33,11 @@
These instructions tell you how to install the Shindig-ORNG web application, These instructions tell you how to install the Shindig-ORNG web application,
and how to configure it to work with VIVO. and how to configure it to work with VIVO.
</p> </p>
<p><em>
Note: these instructions assume that you will be installing VIVO on Tomcat
using the standard installation procedure. VIVO does not yet support ORNG
on containers other than Tomcat.
</em></p>
<hr/> <hr/>
<h2 id="tableofcontents">Table of Contents</h2> <h2 id="tableofcontents">Table of Contents</h2>
@ -183,7 +188,7 @@ set CATALINA_OPTS=-Dshindig.host=localhost -Dshindig.port=8080 -Djava.awt.headle
<h3 id="vivo_settings">I.iv Configure VIVO</h3> <h3 id="vivo_settings">I.iv Configure VIVO</h3>
<p> <p>
In the VIVO distribution directory, the file called <em>deploy.properties</em> In the VIVO home directory, the file called <em>runtime.properties</em>
contains configuration options for the VIVO application. contains configuration options for the VIVO application.
You must set some additional parameters so VIVO will be able to communicate with Shindig-ORNG. You must set some additional parameters so VIVO will be able to communicate with Shindig-ORNG.
</p> </p>
@ -240,11 +245,8 @@ set CATALINA_OPTS=-Dshindig.host=localhost -Dshindig.port=8080 -Djava.awt.headle
to configure the Shindig-ORNG application and deploy it to Tomcat's webapps directory. to configure the Shindig-ORNG application and deploy it to Tomcat's webapps directory.
</p> </p>
<p> <p>
The main VIVO application must also be re-deployed in order to accept the new settings You must restart Tomcat so the main VIVO application will load the new settings
in <em>deploy.properties</em>. At the command line, from the top level of the VIVO distribution in <em>runtime.properties</em>.
directory, type:
<pre> ant deploy</pre>
to re-deploy VIVO with the new settings.
</p> </p>
<h3 id="confirm">I.vi Does it work?</h3> <h3 id="confirm">I.vi Does it work?</h3>
@ -267,7 +269,7 @@ set CATALINA_OPTS=-Dshindig.host=localhost -Dshindig.port=8080 -Djava.awt.headle
<p> <p>
If one of the OpenSocial tests fails, you may continue to use VIVO, but it is If one of the OpenSocial tests fails, you may continue to use VIVO, but it is
likely that no gadgets will be shown. likely that no gadgets will be shown.
You can review the warning message by seleting the "Startup Status" You can review the warning message by selecting the "Startup Status"
link from the "Site Admin" page. link from the "Site Admin" page.
</p> </p>
@ -286,7 +288,7 @@ set CATALINA_OPTS=-Dshindig.host=localhost -Dshindig.port=8080 -Djava.awt.headle
</p> </p>
<p> <p>
The first time you bring up the search page, it may take several seconds for the gadget to The first time you bring up the search page, it may take several seconds for the gadget to
appear. After the first time, the gadget response should be must faster. appear. After the first time, the gadget response should be much faster.
</p> </p>
<h4>Profile page</h4> <h4>Profile page</h4>
@ -331,7 +333,7 @@ set CATALINA_OPTS=-Dshindig.host=localhost -Dshindig.port=8080 -Djava.awt.headle
<ul> <ul>
<li> <li>
VIVO was not re-deployed with <tt>ant deploy</tt> after the OpenSocial VIVO was not re-deployed with <tt>ant deploy</tt> after the OpenSocial
values were set in <em>deploy.properties</em> values were set in <em>runtime.properties</em>
</li> </li>
</ul> </ul>
</td> </td>
@ -403,7 +405,7 @@ set CATALINA_OPTS=-Dshindig.host=localhost -Dshindig.port=8080 -Djava.awt.headle
<td> <td>
<ul> <ul>
<li> <li>
<em>OpenSocial.tokenKeyFile</em> is not set in <em>deploy.properties</em>, <em>OpenSocial.tokenKeyFile</em> is not set in <em>runtime.properties</em>,
or the file does not exist at the specified location. or the file does not exist at the specified location.
</li> </li>
</ul> </ul>
@ -447,7 +449,7 @@ set CATALINA_OPTS=-Dshindig.host=localhost -Dshindig.port=8080 -Djava.awt.headle
<td> <td>
<ul> <ul>
<li> <li>
In <em>deploy.properties</em>, <em>OpenSocial.tokenService</em> is not set correctly. In <em>runtime.properties</em>, <em>OpenSocial.tokenService</em> is not set correctly.
</li> </li>
</ul> </ul>
</td> </td>
@ -690,11 +692,11 @@ set CATALINA_OPTS=-Dshindig.host=localhost -Dshindig.port=8080 -Djava.awt.headle
<h3 id="redeploying">III.i. Re-running the deployment script</h2> <h3 id="redeploying">III.i. Re-running the deployment script</h2>
<p> <p>
The OpenSocial framework relies on several of the settings in the <em>deploy.properties</em> file, The OpenSocial framework relies on several of the settings in the <em>runtime.properties</em> file,
in addition to the ones that are explicitly linked to it. in addition to the ones that are explicitly linked to it.
</p> </p>
<p> <p>
Each time you change the settings in <em>deploy.properties</em>, you should re-deploy Each time you change the settings in <em>runtime.properties</em>, you should re-deploy
the framework with the framework with
<pre> ant orng</pre> <pre> ant orng</pre>
</p> </p>
@ -748,12 +750,12 @@ set CATALINA_OPTS=-Dshindig.host=localhost -Dshindig.port=8080 -Djava.awt.headle
Disabling the gadgets, as above, will remove essentially all of the OpenSocial processing Disabling the gadgets, as above, will remove essentially all of the OpenSocial processing
within VIVO. To remove the remainder of it, you can disable the connection between within VIVO. To remove the remainder of it, you can disable the connection between
VIVO and the OpenSocial service. Do this by removing or commenting VIVO and the OpenSocial service. Do this by removing or commenting
the <em>OpenSocial</em> properties in <em>deploy.properties</em> the <em>OpenSocial</em> properties in <em>runtime.properties</em>
(see <a href="#vivo_settings">section I.iv. Configure VIVO</a>). (see <a href="#vivo_settings">section I.iv. Configure VIVO</a>).
</p> </p>
<p> <p>
To make this change take effect, re-deploy VIVO and restart Tomcat. Restart Tomcat to make this change take effect.
</p> </p>
<h4>Remove the OpenSocial webapp from Tomcat</h4> <h4>Remove the OpenSocial webapp from Tomcat</h4>

444
doc/upgrade-1.6.html Normal file
View file

@ -0,0 +1,444 @@
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>VIVO Release 1 V1.6 Upgrade Guide</title>
<link rel="stylesheet" href="./css/doc.css" media="screen">
</head>
<body>
<div id="branding" role="banner">
<h1 class="vivo-logo"><a href="/"><span class="displace">VIVO</span></a></h1>
</div>
<!-- Start of content -->
<div id="wrapper-content" role="main">
<h1>VIVO Release 1 V1.6 Upgrade Guide</h1>
<small>
BOGUS DATE, 2013 - Upgrading from Release 1 V1.5 to Release 1 V1.6
</small>
<p>
This document contains instructions on how to upgrade your
installation of VIVO from Version 1.5 (or 1.5.1) to Version 1.6.
This and other documentation can be found on the <a href="http://vivoweb.org/support">support page</a>
at <a href="http://vivoweb.org/">VIVOweb.org</a>
</p>
<p>
If you need to do a fresh install, please consult the VIVO Release V1.6 Installation
Guide found on <a href="http://vivoweb.org/support">vivoweb.org</a>
or the install.html file located in the <code>doc</code>
directory of the VIVO source code distribution. The installation document also has a
list of the required software and versions.
</p>
<p>
For a description of the release contents see the <a href="./release.html">Release announcement for V1.6</a>.
</p>
<hr/>
<h3 id="tableofcontents">Table of Contents</h3>
<toc>
<ol class="roman2">
<li><a href="#preparation">Before Performing the Upgrade</a></li>
<li>
<a href="#changes">Noteworthy Changes</a>
<ol class="roman2">
<li><a href="#more_portable">VIVO becomes more portable</a></li>
<li><a href="#solr_insecure">Solr is no longer secured</a></li>
<li><a href="#BOGUS">ANYTHING ELSE?</a></li>
</ol>
</li>
<li><a href="#upgrade_process">Upgrade Instructions</a></li>
<li><a href="#kbm">Knowledge Base Migration</a></li>
<li><a href="#termsofuse">Review the VIVO Terms of Use</a></li>
<li><a href="#nextsteps">Next Steps</a></li>
</ol>
</toc>
<hr/>
<h3 id="preparation">I. Before Performing the Upgrade</h3>
<br/>
Create backups of:
<ul style="list-style-type: square;">
<li>
The VIVO distribution directory (which contains the source for VIVO 1.5 or VIVO 1.5.1)
</li>
<li>
The VIVO home directory (pointed to by your deploy.properties file)
</li>
<li>
The webapps directory in Tomcat
</li>
<li>
MySQL database (most people use mysqldump to create the backup)
</li>
</ul>
<p>
The upgrade process is similar to the initial install process
with
the following exceptions:
</p>
<ul>
<li>
You do not need to reinstall MySQL or recreate the MySQL database. Please
backup your MySQL database as noted above.
</li>
<li>
First-time login of the root account after the upgrade
process is complete will use the password previously set (not the
default password used on the first login after the initial
installation.)
</li>
<li>
The first time Apache Tomcat starts up after the upgrade, an automated
process will modify the knowledge base to align the
data with any ontology updates made for the new release. See the section on the <a href="#kbm">Knowledge Base Migration</a>
below for more information.
</li>
</ul>
<h3 id="changes">II. Noteworthy Changes</h3>
<ul>
<li>
<h4 id="more_portable">VIVO becomes more portable</h4>
<p>
The VIVO build script now includes a <code>distribute</code> target that will produce
a file called <code>distribution.tar.gz</code>. This compressed archive contains
these files:
<ol>
<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>
</ol>
These files can be used with Tomcat, or with any container that supports
the Java Servlet 2.4 Specification.
</p>
<p>
To permit this portability, the <code>deploy.properties</code> file
has been split in two. <code>build.properties</code> contains only the properties
that are required for building VIVO. <code>runtime.properties</code>,
which must be created in the Vitro home directory, contains the properties
that VIVO uses while running.
</p>
<p>
If you are building to <code>deploy</code> to Tomcat (as with previous releases),
then <code>build.properties</code> must contain these properties:
<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>
</p>
<p>
If you are building to <code>distribute</code>, the <code>build.properties</code>
file requires only these properties:
<ul>
<li><code>vitro.core.dir</code></li>
<li><code>webapp.name</code></li>
</ul>
</p>
<h4 id="solr_insecure">Solr is no longer secured</h4>
<p>
In previous releases, Solr was deployed to Tomcat with a <code>RemoteAddrValve</code>
that would only permit access from certain IP addresses.
Acceptable IP addresses were those which matched the regular expression pattern in
the <code>vitro.local.solr.ipaddress.mask</code> property.
</p>
<p>
This has been removed because:
<ul>
<li>It caused repeated problems for sites who were experimenting with VIVO.</li>
<li>It was not standards-based, but specific to Tomcat.</li>
<li>It was redundant. Production instances of VIVO are
usually hidden behind a firewall and accessed through an Apache Http server.</li>
</ul>
</p>
<p>
Sites that need to secure Solr are now left to their own devices.
</p>
<h4 id="BOGUS">ANYTHING ELSE?</h4>
<p>
</p>
</li>
<li>
<h4 id="browsers">Supported Browsers</h4>
<p>
For this release, the following browsers are supported.
BOGUS IS THIS LIST CURRENT?
</p>
<p>
Mac:
</p>
<ul>
<li>Chrome 8.0.552.237</li>
<li>FireFox 3.6.13</li>
<li>Opera 10.6.2</li>
<li>Safari 5.0.3</li>
</ul>
<p>
PC:
</p>
<ul>
<li>Chrome 8.0.552.273</li>
<li>FireFox 10.0.2</li>
<li>Internet Explorer 7, 8, 9</li>
<li>Opera 10.6.2</li>
</ul>
</li>
</ul>
<h3 id="#upgrade_process">III. Upgrade Instructions</h3>
<p>
1. Download the new distribution file and unpack it into a new
source directory.
</p>
<p>
2. Separate your existing <code>deploy.properties</code> file into two files,
as described below. The new <code>build.properties</code> file is stored in
the top level of the VIVO distribution directory. The new <code>runtime.properties</code>
file is stored in your Vitro home directory.
<br>
</p>
<table border='1' bordercolor="#CCCCCC" cellspacing="5">
<tbody>
<tr>
<th width="50%">
Properties in <code>build.properties</code>
</th>
<th>
Properties in <code>runtime.properties</code>
</th>
</tr>
<tr class="odd_row blue">
<td>
<code>vitro.core.dir</code><br>
<code>vitro.home</code><br>
<code>tomcat.home</code><br>
<code>webapp.name</code><br>
</td>
<td>
All other properties from <code>deploy.properties</code>
</td>
</tr>
<tr>
<td colspan="2">
<em>Note that <code>vitro.home</code> replaces <code>vitro.home.directory</code></em>
<br>
<em>Note that <code>vitro.local.solr.ipaddress.mask</code> is no longer used.</em>
</td>
</tr>
</tbody>
</table>
<br>
If you prefer, you may start with <code>example.build.properties</code>
and <code>example.runtime.properties</code>, make copies,
and edit them to suit your installation.
<p>
<!-- runtime.properties table from install.html -->
</p>
<table border='1' bordercolor="#CCCCCC" cellspacing="5">
<tbody>
<tr>
<th>
Property Name
</th>
<th>
Example Value
</th>
</tr>
<tr>
<td colspan="2">
BOGUS: ANY NEW PROPERTIES TO ADD?
</td>
</tr>
<tr class="odd_row blue">
<td>
BOGUS.PROPERTYNAME
</td>
<td>
BOGUS EXAMPLE VALUE
</td>
</tr>
</tbody>
</table>
<p>
3. Apply any previous changes you have made to the new source
directory.
</p>
<blockquote>
<strong>Special notes regarding source files</strong>
<ul>
<li>
This process assumes any changes made to the application were
made in the source directory and deployed, and were not made directly
within the Tomcat webapps directory.
</li>
<li>
In many cases, simply copying the modified files from your
original source directory will not work since the files on which they
are based have changed. It will be necessary to inspect the new source
files and add any changes to them at that time.
</li>
<li>
NIH-funded VIVO implementations will need to apply the
Google Analytics Tracking Code (GATC) to <code>googleAnalytics.ftl</code>
in the theme:<pre>[new_source_directory]/themes/[theme_dir]/templates/googleAnalytics.ftl</pre>
A sample <code>googleAnalytics.ftl</code> is included in the built-in
theme. This file serves only as an example, and you must replace the
tracking code shown with your institution's own tracking code. For
additional information about the GATC for the NIH-funded VIVO
implementation sites and a copy of your institution's tracking code,
see the <a href="https://confluence.cornell.edu/display/ennsrd/Google+Analytics+for+UI">VIVO
Google
Analytics
wiki
page</a>.
</li>
</ul>
</blockquote>
<p>
5. Stop Apache Tomcat and from your VIVO source directory, run
ant
by typing: <code>ant all</code>
</p>
<p>
6. Start Apache Tomcat and log into VIVO as the root user when the upgrade is
completed. Depending on the size of your database, the migration process may
take up to several hours. When it is complete, you will
see a message in the catalina.log file that the server has started.<pre>INFO: Server startup in XXXXX ms</pre>
</p>
<p>
7. As root or an administrator, request a rebuild of the Solr search index:
Go to the "Site Admin" page and click on "Rebuild Search Index" under the
heading "Refresh Content".
</p>
<p>
8. Review and save aside the knowledge base migration logs.
The knowledge base migration process described in the next section will generate logs.
These logs will be overwritten if you redeploy the VIVO application (but not if you restart tomcat), and since
they may be a useful reference if questions come up about your 1.6 VIVO data after deployment,
you should save them aside.
The logs are created in the Tomcat <code>webapps/vivo/WEB-INF directory</code>:
</p>
<dl>
<dt>
<code>ontologies/update/logs/knowledgeBaseUpdate.(timestamp).log</code>
</dt>
<dd>
A log of a summary of updates that were made to the knowledge
base. This file should end with "Finished knowledge base migration".
If this file contains any warnings they should be reviewed with your
implementation team representative to see whether any corrective action needs to be taken.
</dd>
</dl>
<dl>
<dt>
<code>ontologies/update/logs/knowledgeBaseUpdate.(timestamp).error.log</code>
</dt>
<dd>
A log of errors that were encountered during the upgrade
process. This file should be empty if the upgrade was successful. If any errors are encountered
you will need to rerun the knowledge base migration.
</dd>
</dl>
<h3 id="#kbm">IV. Knowledge Base Migration</h3>
<p>
Changes to the VIVO core ontology may require corresponding
modifications to the knowledge base instance data and ontology annotations.
When VIVO first starts up following the upgrade, it will
initiate a process to examine the knowledge base and apply necessary
changes. The knowledge base migration process for release 1.6 will make
the following types of changes:
</p>
<dl>
<dt>
BOGUS CHANGES
</dt>
</dl>
<dl>
<dt>
Annotation property default values
</dt>
<dd>
If a site has modified the value of a vitro annotation (such as
displayRankAnnot or displayLimitAnnot) so that it is no longer using
the default, then that setting will be left unchanged.
<br>
If a site is using the default value of a vitro annotation, and the
default has been changed in the new version of the ontology, then the
new default value will be propagated to the knowledge base.
</dd>
</dl>
<p>
In addition to the logs described in <strong>step 8</strong> of the <a href="#upgrade_process">previous section</a>, the knowledge base migration
process will log copies of all additions and deletions that were made to the knowledge base in the following files:
</p>
<dl>
<dt>
<code>webapps/vivo/WEB-INF/ontologies/update/changedData/removedData.n3</code>
</dt>
<dd>
An N3 file containing all the statements that were removed from the knowledge base.
</dd>
</dl>
<dl>
<dt>
<code>webapps/vivo/WEB-INF/ontologies/update/changedData/addedData.n3</code>
</dt>
<dd>
An N3 file containing all the statements that were added to the knowledge base.
</dd>
</dl>
<h3 id="termsofuse">V. Review the VIVO Terms of Use</h3>
<p>
VIVO comes with a "Terms of Use" statement linked from the footer. The "Site Name"
you assign in the "Site Information" form under the <strong>Site Admin</strong>
area will be
inserted into the "Terms of Use" statement. If you want to edit the text content more than just
the "Site Name", the file can be found here:<pre>[vivo_source_dir]/vitro-core/webapp/web/templates/freemarker/body/termsOfUse.ftl</pre>
Be sure to make the changes in your source files and deploy them to your tomcat so you don't lose
your changes next time you deploy for another reason.
</p>
<h3 id="nextsteps">Next Steps</h3>
<p>
Now that you have VIVO up and running, please refer to the
<a href="https://wiki.duraspace.org/display/VIVO/Site+Administrator+Guide">Site Administrator's Guide</a>
for information about its operation.
</p>
</div>
<!-- #wrapper-content -->
<div id="footer" role="contentinfo">
<p class="copyright">
<small>
&copy;2013 All Rights Reserved
</small>
| Powered
by <a class="powered-by-vivo" href="http://vivoweb.org" target="_blank"><strong>VIVO</strong></a>
</p>
<div id="nav" role="navigation">
<ul id="footer-nav" role="list">
<li role="listitem">
<a href="http://vivoweb.org/about">About</a>
</li>
<li role="listitem">
<a href="http://vivoweb.org/contact">Contact Us</a>
</li>
<li role="listitem">
<a href="http://www.vivoweb.org/support" target="blank">Support</a>
</li>
</ul>
</div>
</div>
<!-- #footer -->
</div>
</body>
</html>

1
doc/upgrades.html
View file

@ -27,6 +27,7 @@
<li><a href="upgrade-1.3.html">upgrade-1.3.html</a></li> <li><a href="upgrade-1.3.html">upgrade-1.3.html</a></li>
<li><a href="upgrade-1.4.html">upgrade-1.4.html</a></li> <li><a href="upgrade-1.4.html">upgrade-1.4.html</a></li>
<li><a href="upgrade-1.5.html">upgrade-1.5.html</a></li> <li><a href="upgrade-1.5.html">upgrade-1.5.html</a></li>
<li><a href="upgrade-1.6.html">upgrade-1.6.html</a></li>
</ul> </ul>
</div> </div>

39
example.build.properties Normal file
View file

@ -0,0 +1,39 @@
# -----------------------------------------------------------------------------
#
# VIVO build properties
#
# This file is provided as example.build.properties.
#
# Save a copy of this file as build.properties, and edit the properties as
# needed for your deployment.
#
# -----------------------------------------------------------------------------
#
# Where is the Vitro core directory?
# In most deployments, this is set to ./vitro-core (It is not uncommon for this
# setting to point elsewhere in development environments).
# Examples:
# vitro.core.dir = ./vitro-core
# vitro.core.dir = ../vitro
# vitro.core.dir = /usr/local/vitro/trunk
vitro.core.dir = ./vitro-core
#
# The base install directory for your Tomcat server. The VIVO application
# will be deployed in the /webapps directory below this base.
#
tomcat.home = /usr/local/tomcat
#
# The name of the VIVO application. This will be used as the name of the
# subdirectory within your Tomcat server's /webapps directory. It also appears
# in the URL for the application. For example, http://my.vivo.server/vivo
#
webapp.name = vivo
#
# The location where the VIVO application will store the data that it creates.
# This includes uploaded files (usually images) and the search index.
#
vitro.home = /usr/local/vivo/home

53
example.deploy.properties → example.runtime.properties
View file

@ -1,11 +1,11 @@
# ----------------------------------------------------------------------------- # -----------------------------------------------------------------------------
# #
# VIVO deployment properties # VIVO runtime properties
# #
# This file is provided as example.deploy.properties. # This file is provided as example.runtime.properties.
# #
# Save a copy of this file as deploy.properties, and edit the properties as # Save a copy of this file as runtime.properties in your Vitro home directory,
# needed for your deployment. # and edit the properties as needed for your installation.
# #
# ----------------------------------------------------------------------------- # -----------------------------------------------------------------------------
@ -22,29 +22,6 @@
# #
Vitro.defaultNamespace = http://vivo.mydomain.edu/individual/ Vitro.defaultNamespace = http://vivo.mydomain.edu/individual/
#
# Where is the Vitro core directory?
# In most deployments, this is set to ./vitro-core (It is not uncommon for this
# setting to point elsewhere in development environments).
# Examples:
# vitro.core.dir = ./vitro-core
# vitro.core.dir = ../vitro
# vitro.core.dir = /usr/local/vitro/trunk
vitro.core.dir = ./vitro-core
#
# The base install directory for your Tomcat server. The VIVO application
# will be deployed in the /webapps directory below this base.
#
tomcat.home = /usr/local/tomcat
#
# The name of the VIVO application. This will be used as the name of the
# subdirectory within your Tomcat server's /webapps directory. It also appears
# in the URL for the application. For example, http://my.vivo.server/vivo
#
webapp.name = vivo
# #
# URL of Solr context used in local VIVO search. This will usually consist of: # URL of Solr context used in local VIVO search. This will usually consist of:
# scheme + server_name + port + vivo_webapp_name + "solr" # scheme + server_name + port + vivo_webapp_name + "solr"
@ -55,28 +32,6 @@ webapp.name = vivo
# vitro.local.solr.url = http://localhost:8080/vivosolr # vitro.local.solr.url = http://localhost:8080/vivosolr
vitro.local.solr.url = http://localhost:8080/vivosolr vitro.local.solr.url = http://localhost:8080/vivosolr
#
# Restricts access to the Solr search platform. The value is a regular expression.
# When a request is made to Solr, the IP address of the requestor must match the
# regular expression, or the request will be rejected.
#
# NOTE: don't leave a space on the end of the line, unless you want it to be
# part of the expression.
# Examples:
# vitro.local.solr.ipaddress.mask = 127\.0\.0\.1
# vitro.local.solr.ipaddress.mask = 127\.0\.0\.1|0:0:0:0:0:0:0:1
# vitro.local.solr.ipaddress.mask = 169\.254\..*
# If this line is removed, your Solr server will respond to requests from any
# location. This may be useful for experimenting but would likely be considered
# a security problem in a production environment.
vitro.local.solr.ipaddress.mask = 127\.0\.0\.1|[0:]+:1
#
# The location where the VIVO application will store the data that it creates.
# This includes uploaded files (usually images) and the search index.
#
vitro.home.directory = /usr/local/vivo/data
# #
# Email parameters which VIVO can use to send mail. If these are left empty, # Email parameters which VIVO can use to send mail. If these are left empty,
# the "Contact Us" form will be disabled and users will not be notified of # the "Contact Us" form will be disabled and users will not be notified of

6
productMods/templates/freemarker/body/harvester/fileharvest.ftl
View file

@ -16,7 +16,7 @@
<h2><a class="ingestMenu" href="${urls.base}/ingest" title="Return to the Data Ingest Tools menu">Ingest Menu</a> > ${jobSpecificHeader}</h2> <h2><a class="ingestMenu" href="${urls.base}/ingest" title="Return to the Data Ingest Tools menu">Ingest Menu</a> > ${jobSpecificHeader}</h2>
<#-- check to ensure harvester.location is set in deploy.properties --> <#-- check to ensure harvester.location is set in runtime.properties -->
<#if harvesterLocation?has_content> <#if harvesterLocation?has_content>
<script type="text/javascript"> <script type="text/javascript">
@ -181,7 +181,7 @@
<ol> <ol>
<li>VIVO Harvester is installed.</li> <li>VIVO Harvester is installed.</li>
<li>The <em>harvester.location</em> property in deploy.properties is pointed to the Harvester installation directory.</li> <li>The <em>harvester.location</em> property in runtime.properties is pointed to the Harvester installation directory.</li>
<li>In VIVO Harvester, the web server user (typically tomcat6) has read and write access to the <em>vivo/</em> directory and all of its children.</li> <li>In VIVO Harvester, the web server user (typically tomcat6) has read and write access to the <em>vivo/</em> directory and all of its children.</li>
<li>In VIVO Harvester, the <em>logs/</em> directory exists and the web server user has read and write access to it.</li> <li>In VIVO Harvester, the <em>logs/</em> directory exists and the web server user has read and write access to it.</li>
<li>In VIVO Harvester, the file <em>vivo/config/vivo.xml</em> is properly configured with your database information and namespace.</li> <li>In VIVO Harvester, the file <em>vivo/config/vivo.xml</em> is properly configured with your database information and namespace.</li>
@ -265,7 +265,7 @@
<#else> <#else>
<div id="fileHarvestErrorHelp"> <div id="fileHarvestErrorHelp">
<p>The <em>harvester.location</em> property in deploy.properties is undefined.</p> <p>The <em>harvester.location</em> property in runtime.properties is undefined.</p>
<p>In order to use this feature, please define a value for this property that points to the Harvester installation directory before redeploying and restarting the application.</p> <p>In order to use this feature, please define a value for this property that points to the Harvester installation directory before redeploying and restarting the application.</p>
</div> </div>

2
src/edu/cornell/mannlib/vitro/webapp/controller/harvester/FileHarvestController.java
View file

@ -180,7 +180,7 @@ public class FileHarvestController extends FreemarkerHttpServlet {
{ {
String pathToHarvester = ConfigurationProperties.getBean(req).getProperty("harvester.location"); String pathToHarvester = ConfigurationProperties.getBean(req).getProperty("harvester.location");
if (pathToHarvester == null) { if (pathToHarvester == null) {
log.error("The deploy.properties file does not contain a value for 'harvester.location'"); log.error("The runtime.properties file does not contain a value for 'harvester.location'");
return ""; return "";
} }
return pathToHarvester; return pathToHarvester;

2
src/edu/cornell/mannlib/vitro/webapp/visualization/temporalgraph/OrganizationUtilityFunctions.java
View file

@ -120,7 +120,7 @@ public class OrganizationUtilityFunctions {
.getProperty("visualization.topLevelOrg"); .getProperty("visualization.topLevelOrg");
/* /*
* First checking if the staff has provided highest level organization in deploy.properties * First checking if the staff has provided highest level organization in runtime.properties
* if so use to temporal graph vis. * if so use to temporal graph vis.
*/ */
if (StringUtils.isNotBlank(staffProvidedHighestLevelOrganization)) { if (StringUtils.isNotBlank(staffProvidedHighestLevelOrganization)) {

22
utilities/pre-compileJSPs/jsp-build.xml
View file

@ -10,23 +10,23 @@
".build/war" directory is current. ".build/war" directory is current.
====================================================================== --> ====================================================================== -->
<project name="Check JSPs for compile errors" default="all" basedir="../.."> <project name="Check JSPs for compile errors" default="all" basedir="../..">
<!-- Get tomcat.home and webapp.name from the deploy.properties file. --> <!-- Get tomcat.home and webapp.name from the build.properties file. -->
<property name="deploy.properties.file" location="deploy.properties" /> <property name="build.properties.file" location="build.properties" />
<fail message="You must create a &quot;${deploy.properties.file}&quot; file."> <fail message="You must create a &quot;${build.properties.file}&quot; file.">
<condition> <condition>
<not> <not>
<available file="${deploy.properties.file}" /> <available file="${build.properties.file}" />
</not> </not>
</condition> </condition>
</fail> </fail>
<property file="${deploy.properties.file}" /> <property file="${build.properties.file}" />
<fail unless="tomcat.home" <fail unless="tomcat.home"
message="${deploy.properties.file} must contain a value for tomcat.home" /> message="${build.properties.file} must contain a value for tomcat.home" />
<fail unless="webapp.name" <fail unless="webapp.name"
message="${deploy.properties.file} must contain a value for webapp.name" /> message="${build.properties.file} must contain a value for webapp.name" />
<property name="build.jsp.dir" location=".build/jsp" /> <property name="build.jsp.dir" location=".build/jsp" />
<property name="build.war.dir" location=".build/war" /> <property name="build.webapp.dir" location=".build/main/webapp" />
<!-- Where are the Tomcat classes? --> <!-- Where are the Tomcat classes? -->
<path id="jasper.classpath"> <path id="jasper.classpath">
@ -41,8 +41,8 @@
<!-- Add in the project classes --> <!-- Add in the project classes -->
<path id="compile.classpath"> <path id="compile.classpath">
<path refid="jasper.classpath" /> <path refid="jasper.classpath" />
<pathelement location="${build.war.dir}/WEB-INF/classes" /> <pathelement location="${build.webapp.dir}/WEB-INF/classes" />
<fileset dir="${build.war.dir}/WEB-INF/lib"> <fileset dir="${build.webapp.dir}/WEB-INF/lib">
<include name="*.jar" /> <include name="*.jar" />
</fileset> </fileset>
</path> </path>
@ -65,7 +65,7 @@
<target name="jspc" depends="prepare"> <target name="jspc" depends="prepare">
<jasper2 validateXml="false" <jasper2 validateXml="false"
uriroot="${build.war.dir}" uriroot="${build.webapp.dir}"
webXmlFragment="${build.jsp.dir}generated_web.xml" webXmlFragment="${build.jsp.dir}generated_web.xml"
outputDir="${build.jsp.dir}/src" outputDir="${build.jsp.dir}/src"
trimSpaces="true" trimSpaces="true"