1160 lines
55 KiB
HTML
1160 lines
55 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
||
<meta charset="utf-8">
|
||
<title>Vitro Version 1.6 Installation Guide</title>
|
||
<link rel="stylesheet" href="./css/doc.css" media="screen">
|
||
</head>
|
||
<body>
|
||
<div id="branding" role="banner">
|
||
<h1 class="vitro-logo"><a href="/"><span class="displace">Vitro</span></a></h1>
|
||
</div>
|
||
<!-- Start of content -->
|
||
<div id="wrapper-content" role="main">
|
||
<h1>Vitro Version 1.6. Installation Guide</h1>
|
||
<small>
|
||
October 9, 2013
|
||
</small>
|
||
<toc>
|
||
<ul>
|
||
<li>
|
||
<a href="#introduction">Introduction to the Vitro installation</a>
|
||
</li>
|
||
<li>
|
||
<a href="#installation">Installation process for Version 1.6</a>
|
||
</li>
|
||
</ul>
|
||
</toc>
|
||
|
||
<br>
|
||
<p>
|
||
This document is a summary of the Vitro installation process.
|
||
</p>
|
||
<p>
|
||
These instructions assume that you are performing a clean install,
|
||
starting with an empty database, an empty Vitro home directory,
|
||
and a Tomcat installation with no Vitro webapp.
|
||
If you are upgrading a previous installation of Vitro,
|
||
you may need to adjust your procedure accordingly.
|
||
</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>
|
||
|
||
<hr><h2 id="introduction">Introduction to the Vitro installation</h2>
|
||
|
||
<p>
|
||
Before beginning the installation,
|
||
let’s discuss some of the major concepts relating to the Vitro installation.
|
||
</p>
|
||
|
||
<h3>Where does Vitro live on your computer?</h3>
|
||
<p>
|
||
Vitro exists in four locations on your computer, from the distribution to the runtime to the data storage.
|
||
</p>
|
||
<h4>The Vitro distribution directory</h4>
|
||
<p>
|
||
This is created when you checkout the Vitro source code
|
||
(see <a href="#checkout_code">installation step III</a>, below).
|
||
This is where you will create your build.properties file
|
||
(see <a href="#build_properties">installation step IV</a>, below),
|
||
and where you will make any modifications to the Vitro
|
||
theme or code. You can create this wherever you choose.
|
||
</p>
|
||
<h4>Vitro inside Tomcat</h4>
|
||
<p>
|
||
When you run the build script to compile and deploy Vitro
|
||
(see <a href="#deploy">installation step V</a>, below),
|
||
the files will be deployed to a
|
||
directory inside Tomcat. This is the actual executing code for Vitro,
|
||
but you won’t need to look at it or change it. If you need to change
|
||
Vitro, 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 build.properties file (see <a href="#build_properties">installation step IV</a>,
|
||
below).
|
||
</p>
|
||
<h4>The Vitro home directory</h4>
|
||
<p>
|
||
This directory contains the runtime configuration properties for Vitro.
|
||
Vitro will also use this area to store some of the data it uses. Uploaded
|
||
image files are stored here, and the Solr home directory is stored here also.
|
||
You can create this wherever you choose. Tell Vitro where to find the
|
||
home directory by setting <code>vitro.home</code> in the
|
||
build.properties file (see <a href="#build_properties">installation step IV</a>,
|
||
below). You must create this directory before starting Vitro,
|
||
you must create the <code>runtime.properties</code> file in this directory
|
||
(see <a href="#runtime_properties">Step VI</a>, below), and you
|
||
must ensure that Tomcat has permission to read and write to this
|
||
directory when it runs.
|
||
</p>
|
||
<h4>The MySQL database</h4>
|
||
<p>
|
||
Essentially all of the data that you store in Vitro 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">installation step I</a>, below).
|
||
but you won’t need to
|
||
know the location. You will access the data through Vitro, or
|
||
occasionally through the MySQL client application.
|
||
</p>
|
||
|
||
<h3>The relationship between Vitro and VIVO</h3>
|
||
|
||
<h4>“Vitro Inside”</h4>
|
||
<p>
|
||
Vitro was developed as a
|
||
“general-purpose web-based ontology and instance editor with customizable public browsing.”
|
||
It is useful on its own, but also serves as the basis for several products,
|
||
including VIVO. [http://sourceforge.net/projects/vivo/]
|
||
</p>
|
||
<p>
|
||
In 2009, the National Institutes of Health (NIH) awarded a major grant to advance the development of VIVO.
|
||
Much of the recent development on Vitro has been in support of that grant.
|
||
However, Vitro retains its own identity,
|
||
and still serves as the core of many projects and products.
|
||
Some of these are currently in use, and some are still in the planning stages.
|
||
</p>
|
||
<p>
|
||
Because VIVO was so well funded, and because it is widely used,
|
||
someone seeking help with Vitro might find information that applies to VIVO instead.
|
||
In many cases, that information will apply to Vitro as well.
|
||
However, there are some notable exceptions:
|
||
<ul>
|
||
<li>
|
||
<h5>Ontology</h5>
|
||
<p>
|
||
Vitro is essentially a blank slate, and is suitable for use with almost any ontology.
|
||
It is packaged with a minimal ontology, sufficient to run the application itself.
|
||
</p>
|
||
<p>
|
||
VIVO is packaged with a rich ontology, tailored to scientists and educators.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<h5>Theme</h5>
|
||
<p>
|
||
Vitro and VIVO are each packaged with their own default theme.
|
||
The VIVO theme is more extensive,
|
||
since it includes custom pages and custom list views that apply to the VIVO ontology.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<h5>Visualizations</h5>
|
||
<p>
|
||
VIVO includes some rich visualization tools that are specific to the VIVO ontology.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<h5>Harvester</h5>
|
||
<p>
|
||
VIVO includes an RDF Harvester tool for importing data from sources of record.
|
||
The Harvester may be useful for Vitro as well, but it was developed for VIVO,
|
||
and may have some dependencies on VIVO.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</p>
|
||
|
||
<h4>Release schedule and names</h4>
|
||
<p>
|
||
Currently, the Vitro release schedule is coordinated with the VIVO releases,
|
||
so version 1.6 of Vitro forms the basis of version 1.6 of VIVO.
|
||
In the Vitro code repository, the release tags illustrate this relationship.
|
||
For example, the Vitro revision that was tagged for version 1.6 of VIVO is named “rel-vivo-1.6”
|
||
</p>
|
||
|
||
<hr><!-- Page break --><!-- Installation process for Version 1.6 --><h2 id="installation">Installation process for Version 1.6</h2>
|
||
<p>
|
||
This document is a summary of the Vitro installation process.
|
||
</p>
|
||
<toc>
|
||
<h3>Steps to Installation</h3>
|
||
<ol class="roman1">
|
||
<li>
|
||
<a href="#required_software">Install required software</a>
|
||
</li>
|
||
<li>
|
||
<a href="#create_database">Create an empty MySQL database</a>
|
||
</li>
|
||
<li>
|
||
<a href="#checkout_code">Check out the Vitro Source Code</a>
|
||
</li>
|
||
<li>
|
||
<a href="#build_properties">Specify build properties</a>
|
||
</li>
|
||
<li>
|
||
<a href="#deploy">Compile and deploy</a>
|
||
</li>
|
||
<li>
|
||
<a href="#runtime_properties">Specify runtime properties</a>
|
||
</li>
|
||
<li>
|
||
<a href="#tomcat_settings">Configure Tomcat</a>
|
||
</li>
|
||
<li>
|
||
<a href="#start_tomcat">Start Tomcat</a>
|
||
</li>
|
||
<li>
|
||
<a href="#add_rdf">Log in and add RDF data</a>
|
||
</li>
|
||
<li>
|
||
<a href="#contact_email">Set the Contact Email Address (if
|
||
using "Contact Us" form)</a>
|
||
</li>
|
||
<li>
|
||
<a href="#httpd">Set up Apache HTTPD</a>
|
||
</li>
|
||
<li>
|
||
<a href="#external_auth">Using an External Authentication
|
||
System with Vitro</a>
|
||
</li>
|
||
<li>
|
||
<a href="#installation_check">Was the installation successful?</a>
|
||
</li>
|
||
<li>
|
||
<a href="#termsofuse">Review the Vitro Terms of Use</a>
|
||
</li>
|
||
</ol>
|
||
</toc>
|
||
<h3 id="required_software">I. Install required software </h3>
|
||
<p>
|
||
Before installing Vitro, make sure that the following software is
|
||
installed on the desired machine:
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
Java (SE) 1.7.x <a href="http://java.sun.com">http://java.sun.com</a>
|
||
<ul>
|
||
<li>VIVO has not been tested with OpenJDK</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
Apache Tomcat 6.x or 7.x <a href="http://tomcat.apache.org">http://tomcat.apache.org</a>
|
||
</li>
|
||
<li>
|
||
Apache Ant 1.8 or higher, <a href="http://ant.apache.org">http://ant.apache.org</a>
|
||
</li>
|
||
<li>
|
||
MySQL 5.1 or higher, <a href="http://www.mysql.com">http://www.mysql.com</a>
|
||
</li>
|
||
</ul>
|
||
<p>
|
||
Be sure to set up the environment variables for <code java_home="">JAVA_HOME</code>
|
||
and <code>ANT_HOME</code>
|
||
and add the executables to your path per
|
||
your operating system and installation directions from the software
|
||
support websites.
|
||
</p>
|
||
|
||
<p>
|
||
The following browsers are supported for this release
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
Mac:
|
||
<ul>
|
||
<li>Chrome 30.0.1599.69 and above</li>
|
||
<li>FireFox 3.6.28, 10.0.12, 24</li>
|
||
<li>Opera 12.02</li>
|
||
<li>Safari 5.0.3</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
PC:
|
||
<ul>
|
||
<li>Chrome 25.1364.2 and above</li>
|
||
<li>FireFox 10.0.12, 24</li>
|
||
<li>Internet Explorer 8, 9, 10</li>
|
||
<li>Opera 12.02</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h3 id="create_database">II. 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
|
||
encoding</code>. You will need these values for Step IV when you
|
||
configure the deployment properties. At the MySQL command line you can
|
||
create the database and user with these commands substituting your
|
||
values for <code>dbname</code>, <code>username</code>, and <code>password</code>.
|
||
Most
|
||
of
|
||
the
|
||
time, the hostname will equal <code>localhost</code>.
|
||
</p>
|
||
<pre> CREATE DATABASE dbname CHARACTER SET utf8;<br></pre>
|
||
<p>
|
||
Grant access to a database user. For example:
|
||
</p>
|
||
<pre> GRANT ALL ON dbname.* TO 'username'@'hostname' IDENTIFIED BY 'password';<br></pre>
|
||
<p>
|
||
Keep track of the database name, username, and password for Step
|
||
IV.
|
||
</p>
|
||
<h3 id="checkout_code">III. Check out the Vitro Source Code
|
||
<br>
|
||
</h3>
|
||
<p>
|
||
Download the latest stable release of Vitro from SourceForge:
|
||
go to
|
||
<pre> http://sourceforge.net/projects/vivo/files/Vitro%20Application%20Source/</pre>
|
||
and download either <code>vitro-rel-1.6.zip</code> or <code>vitro-rel-1.6.tar.gz</code>
|
||
</p>
|
||
<p>
|
||
If you want the very latest Vitro source, you can use subversion to check it out from SourceForge:
|
||
<pre> svn checkout svn://svn.code.sf.net/p/vivo/vitro/code/trunk</code> <em>[Vitro_distribution_dir]</em></pre>
|
||
</p>
|
||
|
||
<h3 id="build_properties">IV. Specify build properties </h3>
|
||
<p>
|
||
In the <code>webapp/config</code> directory of the Vitro distribution,
|
||
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 Vitro when it is compiled in
|
||
<a href="#deploy">Step V</a>. If you want to change these properties at
|
||
a later date, you will need to stop Tomcat, repeat <a href="#deploy">Step V</a>,
|
||
and restart Tomcat.
|
||
</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>
|
||
<table border='1' bordercolor="#CCCCCC" cellspacing="5">
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="2">
|
||
Directory where tomcat is installed.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
tomcat.home
|
||
</td>
|
||
<td>
|
||
/usr/local/tomcat
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Name of your Vitro application.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
webapp.name
|
||
</td>
|
||
<td>
|
||
vitro
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Directory where the Vitro 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/vitro/home
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Languages (in addition to American English) that will be built into your
|
||
Vitro site. The languages must be found in the
|
||
<code>languages</code> directory of the Vitro distribution.
|
||
See <a href="https://wiki.duraspace.org/display/VIVO/Building+a+multi-language+VIVO+instance">
|
||
the VIVO Wiki</a> for more information.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
languages.addToBuild
|
||
</td>
|
||
<td>
|
||
es_MX
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h3 id="deploy">V. Compile and deploy</h3>
|
||
<p>
|
||
In <a href="#build_properties">Step IV</a>, you defined the location of the VIVO home directory,
|
||
by specifying <code>vitro.home</code> in the <code>build.properties</code> file.
|
||
Create that directory now.
|
||
</p>
|
||
<p>
|
||
At the command line, change to the <code>webapp</code> directory inside the Vitro distribution
|
||
directory. Then type:
|
||
</p>
|
||
<pre> ant all<br> </pre>
|
||
<p>
|
||
to build Vitro and deploy to Tomcat's webapps directory.
|
||
</p>
|
||
<p>
|
||
The build script may run for as much as five minutes,
|
||
and creates more than 100 lines of output.
|
||
The process comprises several steps:
|
||
<ul>
|
||
<li>collecting the source files from the distribution directory,</li>
|
||
<li>compiling the Java source code,</li>
|
||
<li>compiling and running unit tests,</li>
|
||
<li>preparing the Solr search engine,</li>
|
||
<li>deploying Vitro and Solr to Tomcat.</li>
|
||
</ul>
|
||
</p>
|
||
<p>
|
||
The output of the build may include a variety of warning messages.
|
||
The Java compiler may warn of code that is outdated.
|
||
Unit tests may produce warning messages,
|
||
and some tests may be ignored if they do not produce consistent results.
|
||
</p>
|
||
<table align="center"><tr><td>
|
||
BUILD SUCCESSFUL<br>Total time: 1 minute 49 seconds
|
||
</td></tr></table>
|
||
<p>
|
||
If the output ends with a success message, the build was successful.
|
||
Proceed to the next step.
|
||
</p>
|
||
<table align="center"><tr><td>
|
||
BUILD FAILED<br>Total time: 35 seconds
|
||
</td></tr></table>
|
||
<p>
|
||
If the output ends with a failure message, the build has failed.
|
||
Find the cause of the failure, fix the problem, and run the script again.
|
||
</p>
|
||
|
||
<h3 id="runtime_properties">VI. Specify runtime properties </h3>
|
||
<p>
|
||
The build process in <a href="deploy">Step V</a> created a file called <code>example.runtime.properties</code>
|
||
in your Vitro home directory (<code>vitro.home</code> in the <code>build.properties</code> file).
|
||
Rename this file to <code>runtime.properties</code>, and
|
||
edit the file to suit your installation, as described in the following table.
|
||
</p>
|
||
<p>
|
||
These properties are loaded when Vitro 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 V</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 an additional property in this file. See the section below
|
||
entitled <a href="#external_auth">Using an External Authentication System with Vitro</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: Vitro 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, Vitro's default namespace must have a
|
||
certain structure and begin with the public web address of the Vitro
|
||
installation. For example, if the web address of a Vitro installation is
|
||
"http://vitro.example.edu/" the default namespace must be set to
|
||
"http://vitro.example.edu/individual/" in order to support linked data.
|
||
Similarly, if Vitro is installed at "http://www.example.edu/vitro" the
|
||
default namespace must be set to
|
||
"http://www.example.edu/vitro/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://vitro.mydomain.edu/individual/
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
URL of Solr context used in local Vitro search.
|
||
Should consist of:<pre> scheme + servername + port + vitro_webapp_name + "solr"</pre>
|
||
In the standard installation, the Solr context will be on the same
|
||
server as Vitro, and in the same Tomcat instance. The path will be the
|
||
Vitro webapp.name (specified above) + "solr"
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
vitro.local.solr.url
|
||
</td>
|
||
<td>
|
||
http://localhost:8080/vitrosolr
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Specify an SMTP host that the application will
|
||
use for sending e-mail (Optional). If this is left blank, the contact
|
||
form will be hidden and disabled, and users will not be notified of
|
||
changes to their accounts.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
email.smtpHost
|
||
</td>
|
||
<td>
|
||
smtp.servername.edu
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Specify an email address which will appear as
|
||
the sender in e-mail notifications to users (Optional). If a user
|
||
replies to the notification, this address will receive the reply. If a
|
||
user's e-mail address is invalid, this address will receive the error
|
||
notice. If this is left blank, users will not be notified of changes to
|
||
their accounts.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
email.replyTo
|
||
</td>
|
||
<td>
|
||
vitroAdmin@my.domain.edu
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Specify the JDBC URL of your database. Change
|
||
the end of the URL to reflect your database name (if it is not "vitro").
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
VitroConnection.DataSource.url
|
||
</td>
|
||
<td>
|
||
jdbc:mysql://localhost/vitro
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Change the username to match the authorized user
|
||
you created in MySQL.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
VitroConnection.DataSource.username
|
||
</td>
|
||
<td>
|
||
username
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Change the password to match the password you
|
||
created in MySQL.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
VitroConnection.DataSource.password
|
||
</td>
|
||
<td>
|
||
password
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Specify the maximum number of active connections
|
||
in the database connection pool to support the anticipated number of
|
||
concurrent page requests.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
VitroConnection.DataSource.pool.maxActive
|
||
</td>
|
||
<td>
|
||
40
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Specify the maximum number of database
|
||
connections that will be allowed to remain idle in the connection pool.
|
||
Default is 25% of the maximum number of active connections.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
VitroConnection.DataSource.pool.maxIdle
|
||
</td>
|
||
<td>
|
||
10
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Change the dbtype setting to use a database
|
||
other than MySQL. Otherwise, leave this value unchanged. Possible
|
||
values are DB2, derby, HSQLDB, H2, MySQL, Oracle, PostgreSQL, and
|
||
SQLServer. Refer to http://openjena.org/wiki/SDB/Databases_Supported
|
||
for additional information.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
VitroConnection.DataSource.dbtype
|
||
</td>
|
||
<td>
|
||
MySQL
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Specify a driver class name to use a database
|
||
other than MySQL. Otherwise, leave this value unchanged. This JAR file
|
||
for this driver must be added to the the webapp/lib directory within
|
||
the vitro.core.dir specified above.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
VitroConnection.DataSource.driver
|
||
</td>
|
||
<td>
|
||
com.mysql.jdbc.Driver
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Change the validation query used to test
|
||
database connections only if necessary to use a database other than
|
||
MySQL. Otherwise, leave this value unchanged.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
VitroConnection.DataSource.validationQuery
|
||
</td>
|
||
<td>
|
||
SELECT 1
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Specify the email address of the root user
|
||
account for the Vitro application. This user will have an initial
|
||
temporary password of 'rootPassword'. You will be prompted to create a
|
||
new password on first login.
|
||
<p>
|
||
NOTE: The root user account has access to all data and all
|
||
operations in Vitro. Data views may be surprising when logged in as the
|
||
root user. It is best to create a Site Admin account to use for every
|
||
day administrative tasks.
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
rootUser.emailAddress
|
||
</td>
|
||
<td>
|
||
vitroAdmin@my.domain.edu
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
The URI of a property that can be used to
|
||
associate an Individual with a user account. When a user logs in with a
|
||
name that matches the value of this property, the user will be
|
||
authorized to edit that Individual
|
||
(the value of the property must be either a String literal or an untyped literal).
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
selfEditing.idMatchingProperty
|
||
</td>
|
||
<td>
|
||
http://vitro.mydomain.edu/ns#networkId
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
If an external authentication system like Shibboleth or CUWebAuth is to be
|
||
used, this property says which HTTP header will contain the user ID from
|
||
the authentication system. If such a system is not to be used,
|
||
leave this commented out.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
externalAuth.netIdHeaderName
|
||
</td>
|
||
<td>
|
||
remote_userID
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td colspan="2">
|
||
Tell Vitro to generate HTTP headers on its responses to facilitate caching the
|
||
profile pages that it creates. This can improve performance, but it can also
|
||
result in serving stale data. Default is false if not set.
|
||
For more information, see the VIVO wiki page:
|
||
<a href="https://wiki.duraspace.org/display/VIVO/Use+HTTP+caching+to+improve+performance">
|
||
Use HTTP caching to improve performance </a>
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
http.createCacheHeaders
|
||
</td>
|
||
<td>
|
||
true
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td colspan="2">
|
||
Show only the most appropriate data values based on the Accept-Language
|
||
header supplied by the browser. Default is false if not set.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
RDFService.languageFilter
|
||
</td>
|
||
<td>
|
||
false
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td colspan="2">
|
||
Force VIVO to use a specific language or Locale instead of those
|
||
specified by the browser.
|
||
This affects RDF data retrieved from the model, if RDFService.languageFilter is true.
|
||
This also affects the text of pages that have been modified to support multiple languages.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
languages.forceLocale
|
||
</td>
|
||
<td>
|
||
en_US
|
||
</td>
|
||
</tr>
|
||
|
||
<tr>
|
||
<td colspan="2">
|
||
A list of supported languages or Locales that the user may choose to
|
||
use instead of the one specified by the browser. Selection images must
|
||
be available in the i18n/images directory of the theme.
|
||
This affects RDF data retrieved from the model, if RDFService.languageFilter is true.
|
||
This also affects the text of pages that have been modified to support multiple languages.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
languages.selectableLocales
|
||
</td>
|
||
<td>
|
||
en, es, fr_FR
|
||
</td>
|
||
</tr>
|
||
|
||
</tbody>
|
||
</table>
|
||
|
||
<h3 id="tomcat_settings">VII. Configure Tomcat</h3>
|
||
<h4>Set JVM parameters</h4>
|
||
<p>
|
||
Vitro may require more memory than that allocated to Tomcat by
|
||
default. With most installations of Tomcat, the "setenv.sh" or
|
||
"setenv.bat" file in Tomcat's bin directory is a convenient place to
|
||
set the memory parameters. <em>If this file does not exist in Tomcat's
|
||
bin directory, you can create it.</em>
|
||
<br>
|
||
For example:
|
||
</p>
|
||
<pre> export CATALINA_OPTS="-Xms512m -Xmx512m -XX:MaxPermSize=128m"<br> </pre>
|
||
<p>
|
||
This sets Tomcat to allocate an initial heap of 512 megabytes, a
|
||
maximum heap of 512 megabytes, and a PermGen space of 128 megs. Lower
|
||
values may suffice, especially for small test installations.
|
||
</p>
|
||
<p>
|
||
If an OutOfMemoryError is encountered during Vitro execution, it can
|
||
be remedied by increasing the heap parameters and restarting Tomcat.
|
||
</p>
|
||
<h4>Set security limits</h4>
|
||
<p>
|
||
Vitro is a multithreaded web application that may
|
||
require more threads than are permitted under your Linux installation's
|
||
default configuration. Ensure that your installation can support the
|
||
required number of threads by making the following edits to <code>/etc/security/limits.conf</code>:
|
||
</p>
|
||
<pre> apache hard nproc 400<br> tomcat6 hard nproc 1500 <br> </pre>
|
||
<h4>Set URI encoding</h4>
|
||
<p>
|
||
In order for VIVO to correctly handle international characters,
|
||
you must configure Tomcat to conform to the URI standard by
|
||
accepting percent-encoded UTF-8.
|
||
</p>
|
||
<p>
|
||
Edit Tomcat's <code>conf/server.xml</code> and add the following attribute to each of the
|
||
Connector elements: URIEncoding="UTF-8".
|
||
</p>
|
||
<pre>
|
||
<Server ...>
|
||
<Service ...>
|
||
<Connector ... URIEncoding="UTF-8"/>
|
||
...
|
||
</Connector>
|
||
</Service>
|
||
</Server>
|
||
</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 Vitro distribution (Vitro and Solr) includes a "context fragment" file,
|
||
containing some of the deployment information for that webapp.
|
||
</p>
|
||
<p>
|
||
Tomcat allows you to override these context fragments by adding Context elements to "server.xml".
|
||
If you decide to do this, be sure that your new Context element includes the necessary
|
||
deployment parameters from the overridden context fragment.
|
||
</p>
|
||
<p>
|
||
See <a href="#httpd">Section XI</a> below,
|
||
for an example of overriding the Vitro context fragment.
|
||
</p>
|
||
|
||
<h3 id="start_tomcat">VIII. 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
|
||
browser to "http://localhost:8080/vitro/" to test the application.
|
||
</p>
|
||
<p>
|
||
On start up Vitro will run some diagnostic tests. If a
|
||
problem is detected, the normal Vitro pages will redirect
|
||
to a startup status page describing the problem. You
|
||
can stop tomcat, attempt to fix the problem and
|
||
proceed from <a href="#deploy">Step V</a>. If the problem is not serious, the
|
||
startup status page may offer a <code>continue</code> link which
|
||
will allow you to use VIVO in spite of the problems.
|
||
</p>
|
||
<p>
|
||
If Tomcat does not start up, or the Vitro application is not visible, check
|
||
the files in Tomcat's <code>logs</code> directory. Error messages are commonly found
|
||
in <code>catalina.out</code>
|
||
or <code>localhost.log</code>
|
||
</p>
|
||
|
||
</p>
|
||
<h3 id="add_rdf">IX. 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 installed Vitro. Click the "Log
|
||
in" link near the upper right corner. Log in with the <code>rootUser.emailAddress</code>
|
||
you set up in Step IV. The initial password for the root account is
|
||
"rootPassword" (without the quotes). On first login, you will be
|
||
prompted to select a new password and verify it a second time. When login is
|
||
complete, the search index is checked and, if it is empty,
|
||
a full index build will be triggered in the background, in order to ensure
|
||
complete functionality throughout the site.
|
||
</p>
|
||
<p>
|
||
After logging in, you will be presented with a
|
||
menu of editing options. Here you can create OWL classes, object
|
||
properties, data properties, and configure the display of data.
|
||
Currently, any classes you wish to make visible on your website must be
|
||
part of a class group, and there are a number of visibility and display
|
||
options available for each ontology entity. Vitro comes with a minimal
|
||
ontology. You will likely want to upload additional ontologies from an RDF file.
|
||
</p>
|
||
<p>
|
||
Under the "Advanced Data Tools" click "Add/Remove RDF Data." Note
|
||
that Vitro currently works best with OWL-DL ontologies and has only
|
||
limited support for pure RDF data. You can enter a URL pointing to the
|
||
RDF data you wish to load or upload from a file on your local machine.
|
||
Ensure that the "add RDF" radio button is selected. You will also
|
||
likely want to check "create classgroups automatically."
|
||
</p>
|
||
<p>
|
||
Clicking the "Index" tab in the navigation bar at the top right of
|
||
the page will show a simple index of the knowledge base.
|
||
</p>
|
||
|
||
<h3 id="contact_email">X. Set the Contact Email Address (if using
|
||
"Contact Us" form)</h3>
|
||
<p>
|
||
If you have configured your application to use the "Contact Us"
|
||
feature in Step IV (<code>email.smtpHost</code>), you will also need to
|
||
add an email address to the Vitro application. This is the email
|
||
to which the contact form will submit. It can be a list server or an
|
||
individual's email address.
|
||
</p>
|
||
<p>
|
||
Log in as a system administrator. Navigate to the "Site Admin"
|
||
table of contents (link in the right side of the header). Go to "Site
|
||
Information" (under "Site Configuration"). In the "Site Information
|
||
Editing Form," enter a functional email address in the field "Contact
|
||
Email Address" and submit the change.
|
||
</p>
|
||
<p>
|
||
If you set the <code>email.smtpHost</code>
|
||
in Step IV and do NOT
|
||
provide an email address in this step, your users will receive a java
|
||
error in the interface.
|
||
</p>
|
||
<h3 id="httpd">XI. Set up Apache HTTPD </h3>
|
||
<p>
|
||
It is recommended to run an Apache HTTPD web server to accept requests
|
||
and then proxy them to the VIVO Tomcat context. This will make Vitro
|
||
available at "http://example.com" instead of "http://example.com:8080/vitro".
|
||
It will also allow the use of external authentication.
|
||
</p>
|
||
<p>
|
||
Setup HTTPD to send all of the requests that it receives to Tomcat's AJP
|
||
connector. This can be done in HTTPD 2.x with a simple directive in httpd.conf:
|
||
</p>
|
||
<pre> ProxyPass / ajp://localhost:8009/ <br><br></pre>
|
||
<p>
|
||
Modify the <Host> in Tomcat server.xml (located in <code>[tomcat root]/conf/</code>)
|
||
so that the context path is empty to allow VIVO to be servred from the root path.
|
||
Locate the <code><Host name="localhost"...></code> directive and update as follows:
|
||
</p>
|
||
<pre> <Host name="localhost" appBase="webapps"
|
||
DeployOnStartup="false"
|
||
unpackWARs="true" autoDeploy="false"
|
||
xmlValidation="false" xmlNamespaceAware="false">
|
||
|
||
<Alias>example.com</Alias>
|
||
|
||
<Context path=""
|
||
docBase="/usr/local/tomcat/webapps/vitro"
|
||
reloadable="true"
|
||
cookies="true" >
|
||
|
||
<Manager pathname="" />
|
||
</Context>
|
||
|
||
...
|
||
</pre>
|
||
<p>
|
||
After setting up the above, it is recommended that you modify the Tomcat AJP connector
|
||
parameters in server.xml. Look for the <connector> directive and add the
|
||
following properties:
|
||
</p>
|
||
<pre> connectionTimeout="20000" maxThreads="320" keepAliveTimeout="20000" <br><br></pre>
|
||
<p>
|
||
Note: the value for maxThreads (320) is equal or greater than the value for
|
||
MaxClients in the apache's <code>httpd.conf</code> file.
|
||
</p>
|
||
|
||
<h3 id="external_auth">XII. Using an External Authentication System
|
||
with Vitro </h3>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
Vitro can be configured to work with an external authentication
|
||
system like Shibboleth or CUWebAuth.
|
||
</p>
|
||
<p>
|
||
Vitro must be accessible only through an Apache HTTP server. The
|
||
Apache server will be configured to invoke the external authentication
|
||
system. When the user completes the authentication, the Apache server
|
||
will pass a network ID to Vitro, to identify the user.
|
||
</p>
|
||
<p>
|
||
If Vitro has an account for that user, the user will be logged in
|
||
with the privileges of that account. In the absence of an account, Vitro
|
||
will try to find a page associated with the user. If such a page is
|
||
found, the user can log in to edit his own profile information.
|
||
</p>
|
||
<h4>Configuring the Apache server</h4>
|
||
<p>
|
||
Your institution will provide you with instructions for setting up
|
||
the external authentication system. The Apache server must be
|
||
configured to secure a page in Vitro. When a user reaches this secured
|
||
page, the Apache server will invoke the external authentication system.
|
||
</p>
|
||
<p>
|
||
For Vitro, this secured page is named: <code>/loginExternalAuthReturn</code>
|
||
</p>
|
||
<p>
|
||
When your instructions call for the location of the secured page,
|
||
this is the value you should use.
|
||
</p>
|
||
<h4>Configuring Vitro</h4>
|
||
<p>
|
||
To enable external authentication, Vitro requires three values in
|
||
the <code>runtime.properties</code>
|
||
file.
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
<h5>The name of the HTTP header that will hold the external user's
|
||
network ID.</h5>
|
||
<p>
|
||
When a user completes the authentication process, the Apache
|
||
server will put the user's network ID into one of the headers of the
|
||
HTTP request. The instructions from your institution should tell you
|
||
which header is used for this purpose.
|
||
</p>
|
||
<p>
|
||
You need to tell Vitro the name of that HTTP header. Insert a
|
||
line like this in the runtime.properties file:
|
||
</p>
|
||
<pre>externalAuth.netIdHeaderName = [the header name]</pre>
|
||
<p>
|
||
For example:
|
||
</p>
|
||
<pre>externalAuth.netIdHeaderName = remote_userID</pre>
|
||
</li>
|
||
<li>
|
||
<h5>The text for the Login button.</h5>
|
||
To start the authentication process, the user will click on a button in
|
||
the Vitro login form. You need to tell Vitro what text should appear in
|
||
that button.
|
||
<p>
|
||
In your theme, add a line to the <code>all.properties</code> file,
|
||
like this one:
|
||
<pre>external_login_text = <em>[the text for your login button]</em></pre>
|
||
For example:
|
||
<pre>external_login_text = Log in using BearCat Shibboleth</pre>
|
||
The Vitro login form will display a button labelled "Log in
|
||
using BearCat Shibboleth".
|
||
</p>
|
||
<p>
|
||
If your site supports additional languages, add lines to the corresponding files.
|
||
For example, <code>all_es.properties</code> might contain this line:
|
||
<pre>external_login_text = Entrar usando Shibboleth GatoOso</pre>
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<h5>Associating a User with a profile page.</h5>
|
||
<p>
|
||
Vitro will try to associate the user with a profile
|
||
page, so the user may edit his own profile data. Vitro will search the
|
||
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 Vitro what property should be used
|
||
for matching. Insert a line like this in the runtime.properties file:
|
||
</p>
|
||
<pre>selfEditing.idMatchingProperty = [the URI of the property]</pre>
|
||
<p>
|
||
For example:
|
||
</p>
|
||
<pre>selfEditing.idMatchingProperty = http://vitro.mydomain.edu/ns#networkId</pre>
|
||
</li>
|
||
</ul>
|
||
<h3 id="installation_check">XIII. 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 VIII showed that Tomcat recognized the webapp, and that the
|
||
webapp was able to present the initial page.
|
||
</li>
|
||
<li>
|
||
Step IX verified that you can log in to the administrator
|
||
account.
|
||
</li>
|
||
</ul>
|
||
<p>
|
||
Step VIII also shows that the Vitro self-tests ran successfully.
|
||
When Tomcat starts the Vitro webapp, it runs several tests.
|
||
If any of these tests produce warnings or error message,
|
||
you would see them instead of the Vitro home page.
|
||
</p>
|
||
<p>
|
||
Among other things, the self-tests check
|
||
<ul>
|
||
<li>The Vitro home directory exists and Vitro can write to it.</li>
|
||
<li>Vitro can connect to the database.</li>
|
||
<li>Vitro can connect to the Solr search application.</li>
|
||
</ul>
|
||
If you saw the Vitro home page in Step VII, you know that your installation passed all of these tests.
|
||
</p>
|
||
|
||
<h3 id="termsofuse">XIV. Review the Vitro Terms of Use</h3>
|
||
<p>
|
||
Vitro 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>[vitro_source_dir]/webapp/web/templates/freemarker/body/termsOfUse.ftl</pre>
|
||
</p>
|
||
<p>
|
||
Your "Terms of Use" statement is also referenced in the Linked Open Data (RDF)
|
||
that your site produces, so you should be sure that it accurately reflects
|
||
the way that your data may be used.
|
||
</p>
|
||
<p>
|
||
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>Next Steps</h3>
|
||
<p>
|
||
For more information about Vitro see the <a href="http://vitro.mannlib.cornell.edu/">Vitro public website</a>.
|
||
In addition, you may find helpful information in the
|
||
<a href="http://sourceforge.net/apps/mediawiki/vivo/index.php?title=Site_Administrator_Guide">VIVO Site Administrator's Guide</a>.
|
||
</p>
|
||
<p>
|
||
Send questions or comments to Vitro developers and designers at <strong>vivo-dev-all@lists.sourceforge.net</strong>.
|
||
</p>
|
||
<p>
|
||
</p>
|
||
</div>
|
||
<!-- #wrapper-content -->
|
||
<div id="footer" role="contentinfo">
|
||
<p class="copyright">
|
||
<small>
|
||
©2013 All Rights Reserved
|
||
</small>
|
||
</p>
|
||
</div>
|
||
</body>
|
||
</html>
|