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
Download patch file Download diff file Expand all files Collapse all files

272
doc/install.html
View file

@ -33,7 +33,11 @@
install over an existing installation of an earlier version.
</p><p>
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>
VIVO Developers: If you are working on the VIVO source code from
Subversion, the instructions are slightly different. Please consult
@ -48,30 +52,33 @@
<h4>The VIVO distribution directory</h4>
<p>
This is created when you unpack the VIVO distribution file
(see <a href="#download_code">Step III</a>, below). This is where you will
create your deploy.properties file (see <a href="#deploy_properties">Step
IV</a>, below), and where you will make any modifications to the VIVO
(see <a href="#download_code">Step 3</a>, below). This is where you will
create your build.properties file (see <a href="#build_properties">Step
4</a>, below), and where you will make any modifications to the VIVO
theme or code. You can create this wherever you choose.
</p>
<h4>VIVO inside Tomcat</h4>
<p>
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,
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
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).
</p>
<h4>The VIVO home directory</h4>
<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.
You can create this wherever you choose. Tell VIVO where to find the
home directory by setting <code>vitro.home.directory</code>
in the deploy.properties file (see <a href="#deploy_properties">Step IV</a>,
below). You must create this directory before starting VIVO, and you
home directory by setting <code>vitro.home</code>
in the build.properties file (see <a href="#build_properties">Step 4</a>,
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
directory when it runs.
</p>
@ -79,13 +86,13 @@
<p>
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
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
occasionally through the MySQL client application.
</p>
<toc>
<h3>Steps to Installation</h3>
<ol class="roman1">
<ol>
<li>
<a href="#required_software">Install required software</a>
</li>
@ -96,7 +103,10 @@
<a href="#download_code">Download the VIVO Application Source</a>
</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>
<a href="#deploy">Compile and deploy</a>
@ -132,7 +142,7 @@
</li>
</ol>
</toc>
<h3 id="required_software">I. Install required software </h3>
<h3 id="required_software">1. Install required software </h3>
<p>
Before installing VIVO, make sure that the following software is
installed on the desired machine:
@ -186,7 +196,7 @@
</li>
</ul>
<h3 id="create_database">II. Create an empty MySQL database </h3>
<h3 id="create_database">2. Create an empty MySQL database </h3>
<p>
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
@ -208,7 +218,7 @@
Keep track of the database name, username, and password for Step
IV.
</p>
<h3 id="download_code">III. Download the VIVO Application Source
<h3 id="download_code">3. Download the VIVO Application Source
<br>
</h3>
<p>
@ -218,11 +228,19 @@
<br>
<a href="http://vivoweb.org/download">http://vivoweb.org/download</a>
</p>
<h3 id="deploy_properties">IV. Specify deployment properties </h3>
<h3 id="build_properties">4. Specify build properties </h3>
<p>
At the top level of the VIVO distribution directory, copy the file <code>example.deploy.properties</code>
to a file named simply <code>deploy.properties</code>. This file sets
several properties used in compilation and deployment.
At the top level of the VIVO distribution directory,
copy the file <code>example.build.properties</code>
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>
<em>Windows:</em>
@ -230,14 +248,7 @@
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 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">
<tbody>
<tr>
@ -248,30 +259,6 @@
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>
<td colspan="2">
Directory where Vitro code is located. In most
@ -313,6 +300,90 @@
vivo
</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
</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>
<td colspan="2">
URL of Solr context used in local VIVO search.
@ -330,53 +401,6 @@
http://localhost:8080/vivosolr
</td>
</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>
<td colspan="2">
Specify an SMTP host that the application will
@ -692,7 +716,7 @@
<td colspan="2">
These values are used when deploying VIVO as an OpenSocial container
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.
</td>
</tr>
@ -711,7 +735,7 @@
</tbody>
</table>
<h3 id="deploy">V. Compile and deploy</h3>
<h3 id="deploy">6. Compile and deploy</h3>
<p>
At the command line, from the top level of the VIVO distribution
directory, type:
@ -720,7 +744,7 @@
<p>
to build VIVO and deploy to Tomcat's webapps directory.
</p>
<h3 id="tomcat_settings">VI. Configure Tomcat</h3>
<h3 id="tomcat_settings">7. Configure Tomcat</h3>
<h4>Set JVM parameters</h4>
<p>
VIVO copies small sections of your RDF database into
@ -763,7 +787,7 @@
accepting percent-encoded UTF-8.
</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".
</p>
<pre>
@ -775,6 +799,9 @@
&lt;/Service&gt;
&lt;/Server&gt;
</pre>
<p>
Note: some versions of Tomcat already include this attribute as the default.
</p>
<h4>Take care when creating Context elements</h4>
<p>
Each of the webapps in the VIVO distribution (VIVO and
@ -789,11 +816,11 @@
from the overridden context fragment.
</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.
</p>
<h3 id="start_tomcat">VII. Start Tomcat </h3>
<h3 id="start_tomcat">8. Start Tomcat </h3>
<p>
Most Tomcat installations can be started by running <code>startup.sh</code>
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
to a startup status page describing the problem. You
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
will allow you to use VIVO inspite of the problems.
will allow you to use VIVO in spite of the problems.
<p>
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/localhost.log</code>
</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>
If the startup was successful, you will see a welcome
message informing you that you have successfully
@ -863,7 +890,7 @@
See more documentation for configuring VIVO, ingesting data, and
manually adding data at <a href="http://vivoweb.org/support">http://vivoweb.org/support</a>.
</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>
<p>
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
error in the interface.
</p>
<h3 id="tomcat_connector">X. Set up Apache Tomcat Connector </h3>
<h3 id="tomcat_connector">11. Set up Apache Tomcat Connector </h3>
<p>
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.
@ -937,17 +964,12 @@
cookies="true" &gt;
&lt;Manager pathname="" /&gt;
&lt;Environment type="java.lang.String" override="false"
name="path.configuration"
value="deploy.properties"
/&gt;
&lt;/Context&gt;
...
</pre>
<h3 id="external_auth">XI. Using an External Authentication System
<h3 id="external_auth">12. Using an External Authentication System
with VIVO </h3>
<p>
</p>
@ -984,7 +1006,7 @@
<h4>Configuring VIVO</h4>
<p>
To enable external authentication, VIVO requires three values in
the <code>deploy.properties</code>
the <code>runtime.properties</code>
file.
</p>
<ul>
@ -999,7 +1021,7 @@
</p>
<p>
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>
<pre>externalAuth.netIdHeaderName = [the header name]</pre>
<p>
@ -1013,7 +1035,7 @@
the VIVO login form. You need to tell VIVO what text should appear in
that button.
<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:
</p>
<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
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
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>
<pre>selfEditing.idMatchingProperty = [the URI of the property]</pre>
<p>
@ -1040,7 +1062,7 @@
</li>
</ul>
<h3 id="opensocial">XII. Using VIVO as an OpenSocial platform </h3>
<h3 id="opensocial">13. Using VIVO as an OpenSocial platform </h3>
<p>
VIVO now supports an extension of the OpenSocial API,
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.
</p>
<h3 id="installation_check">XIII. Was the installation successful? </h3>
<h3 id="installation_check">14. Was the installation successful? </h3>
<p>
If you have completed the previous steps, you have good indications
that the installation was successful.
</p>
<ul>
<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.
</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.
</li>
</ul>
@ -1149,7 +1171,7 @@
index</strong>.
</li>
</ul>
<h3 id="termsofuse">XIII. Review the VIVO Terms of Use</h3>
<h3 id="termsofuse">15. 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>