883 lines
42 KiB
HTML
883 lines
42 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>VIVO</title>
|
||
<link rel="stylesheet" href="./css/doc.css" />
|
||
</head>
|
||
<body>
|
||
<header id="branding" role="banner">
|
||
<h1 class="vivo-logo"><a href="/"><span class="displace">VIVO</span></a></h1>
|
||
</header>
|
||
<!-- Start of content -->
|
||
<div id="wrapper-content" role="main">
|
||
<h1>VIVO Release 1 V1.2 Installation Guide</h1>
|
||
<small>
|
||
January 28, 2011
|
||
</small>
|
||
<div style="background: #EEEEEE">
|
||
<b>Missing pieces and fixes</b>
|
||
<ul>
|
||
<li>
|
||
Add release announcemnet
|
||
</li>
|
||
<li>
|
||
Link to upgrade pdf online at SF
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<toc>
|
||
<ul>
|
||
<li>
|
||
<a href="#announcement">Release announcement for V1.2</a>
|
||
</li>
|
||
<li>
|
||
<a href="#installation">Installation process for V1.2</a>
|
||
</li>
|
||
</ul>
|
||
</toc>
|
||
<!-- Release Announcement --><h2 id="announcement">Release anouncement for V1.2</h2>
|
||
<p>
|
||
Text from the wiki page
|
||
</p>
|
||
<!-- Installation process for V1.2 --><h2 id="installation">Installation process for V1.2</h2>
|
||
<p>
|
||
This document is a summary of the VIVO installation process. 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>
|
||
<ul>
|
||
<li>
|
||
These instructions assume that you are performing a clean install, including
|
||
emptying an existing database and removing a previous installation from the
|
||
Tomcat webapps directory. Product functionality may not be as expected if you
|
||
install over an existing installation of an earlier version.
|
||
</li>
|
||
<li>
|
||
If you are going to upgrade an existing service, please consult the upgrade.txt
|
||
in this directory.
|
||
</li>
|
||
</ul>
|
||
<p>
|
||
VIVO Developers: If you are working on the VIVO source code from Subversion,
|
||
the instructions are slightly different. Please consult developers.txt in this directory.
|
||
</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="#download_code">Download the VIVO Application Source</a>
|
||
</li>
|
||
<li>
|
||
<a href="#deploy_properties">Specify deployment properties</a>
|
||
</li>
|
||
<li>
|
||
<a href="#deploy">Compile and deploy</a>
|
||
</li>
|
||
<li>
|
||
<a href="#tomcat_settings">Set Tomcat JVM parameters and security limits</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="#tomcat_connector">Setup Apache Tomcat Connector</a>
|
||
</li>
|
||
<li>
|
||
<a href="#pellet">Configure Pellet Reasoner</a>
|
||
</li>
|
||
<li>
|
||
<a href="#external_auth">Using an External Authentication System with VIVO</a>
|
||
</li>
|
||
<li>
|
||
<a href="#installation_check">Was the installation successful?</a>
|
||
</li>
|
||
</ol>
|
||
</toc>
|
||
<h3 id="required_software">I. Install required software </h3>
|
||
<p>
|
||
Before installing VIVO, make sure that the following software is
|
||
installed on the desired machine:
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
Java (SE) 1.6 or higher, <a href="http://java.sun.com">http://java.sun.com</a>
|
||
(Not OpenJDK)
|
||
</li>
|
||
<li>
|
||
Apache Tomcat 6.x or higher, <a href="http://tomcat.apache.org">http://tomcat.apache.org</a>
|
||
</li>
|
||
<li>
|
||
Apache Ant 1.7 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 setup the environment variables for <code 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 web sites.
|
||
</p>
|
||
<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;
|
||
</pre>
|
||
<p>
|
||
Grant access to a database user.
|
||
For example:
|
||
</p>
|
||
<pre>
|
||
GRANT ALL ON dbname.* TO 'username'@'hostname' IDENTIFIED BY 'password';
|
||
</pre>
|
||
<p>
|
||
Keep track of the database name, username, and password for Step IV.
|
||
</p>
|
||
<h3 id="download_code">III. Download the VIVO Application Source
|
||
<br>
|
||
</h3>
|
||
<p>
|
||
Download the VIVO application source as either <code>rel-1.2.zip</code>
|
||
or <code>rel-1.2.gz</code>
|
||
file and unpack it on your web server:
|
||
<br/>
|
||
<a href="http://vivoweb.org/download">http://vivoweb.org/download</a>
|
||
</p>
|
||
<h3 id="deploy_properties">IV. Specify deployment properties </h3>
|
||
<p>
|
||
At the top level of the unpacked distribution, 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.
|
||
</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 two additional properties in this file.
|
||
See the section below entitled <a href="#external_auth">Using an External Authentication System with VIVO</a>.
|
||
</p>
|
||
<table>
|
||
<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 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 deployments, this is set to
|
||
./vitro-core, but it commonly points elsewhere during development.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
vitro.core.dir
|
||
</td>
|
||
<td>
|
||
./vitro-core
|
||
</td>
|
||
</tr>
|
||
<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 VIVO application.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
webapp.name
|
||
</td>
|
||
<td>
|
||
vivo
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Directory where uploaded files will be stored. You must create this directory ahead of time.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
upload.directory
|
||
</td>
|
||
<td>
|
||
/usr/local/vivo/data/uploads
|
||
</td>
|
||
<tr>
|
||
<td colspan="2">
|
||
Directory where the Lucene search index will be built. Depending on your
|
||
permissions and who Tomcat is running as, you may need to create this directory
|
||
ahead of time.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
LuceneSetup.indexDir
|
||
</td>
|
||
<td>
|
||
/usr/local/vivo/data/luceneIndex
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Specify an SMTP host that the form will use for sending e-mail (Optional). If
|
||
this is left blank, the contact form will be hidden and disabled.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
Vitro.smtpHost
|
||
</td>
|
||
<td>
|
||
smtp.servername.edu
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Specify the JDBC URL of your database. Change the end of theURL to reflect your
|
||
database name (if it is not "vivo").
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
VitroConnection.DataSource.url
|
||
</td>
|
||
<td>
|
||
jdbc:mysql://localhost/vivo
|
||
</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 Jena triple store technology to use. SDB is Jena's
|
||
SPARQL database; this setting allows RDF data to scale beyond the
|
||
limits of the JVM heap. Set to RDB to use the older Jena RDB
|
||
store with in-memory caching.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
VitroConnection.DataSource.tripleStoreType
|
||
</td>
|
||
<td>
|
||
SDB
|
||
</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. It is not necessary to adjust this value when
|
||
using the RDB configuration.
|
||
</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 name of your first admin user for the VIVO application. This user
|
||
will have an initial temporary password of 'defaultAdmin'. You will be prompted to
|
||
create a new password on first login.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
initialAdminUser
|
||
</td>
|
||
<td>
|
||
defaultAdmin
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
The name 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 editthat Individual.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
selfEditing.idMatchingProperty
|
||
</td>
|
||
<td>
|
||
http://vivo.mydomain.edu/ns#networkId
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="2">
|
||
Temporal Graph Visualization is used to compare different
|
||
organizations/people within an organization on different parameters like
|
||
number of publications, grants. This parameter will be used as a default
|
||
in case a URI is not provided. It will be also used whenever this
|
||
visualization is to be rendered for top level organization.
|
||
In absence of this parameter a SPARQL query will be fired which will
|
||
attempt to provide a top level organization. The name 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.
|
||
</td>
|
||
</tr>
|
||
<tr class="odd_row">
|
||
<td>
|
||
visualization.topLevelOrg
|
||
</td>
|
||
<td>
|
||
http://vivo-trunk.indiana.edu/individual/topLevelOrgURI
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<h3 id="deploy">V. Compile and deploy</h3>
|
||
<p>
|
||
At the command line, from the top level of the unpacked distribution
|
||
directory, type:
|
||
</p>
|
||
<pre>
|
||
ant all
|
||
</pre>
|
||
<p>
|
||
to build VIVO and deploy to Tomcat's webapps
|
||
directory.
|
||
</p>
|
||
<h3 id="tomcat_settings">VI. Set Tomcat JVM parameters and security limits</h3>
|
||
<p>
|
||
Currently, VIVO copies the contents of your RDF database into memory
|
||
in order to serve Web requests quickly (the in-memory copy and the
|
||
underlying databaseare kept in synch as edits are performed).
|
||
<p>
|
||
VIVO will 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.
|
||
<br/>
|
||
For example:
|
||
</p>
|
||
<pre>
|
||
export CATALINA_OPTS="-Xms2048m -Xmx1024m -XX:MaxPermSize=128m"
|
||
</pre>
|
||
<p>
|
||
This sets Tomcat to allocate an initial heap of 2048 megabytes, a
|
||
maximum heap of 1024 megabytes, and a PermGen space of 128 megs. 1024
|
||
megabytes is a minimum practical heap size for production
|
||
installations storing data for large academic institutions, and
|
||
additional heap space is preferable. For testing with small sets of
|
||
data, 256m to 512m should be sufficient.
|
||
</p>
|
||
<p>
|
||
If an OutOfMemoryError is encountered during VIVO execution, it can
|
||
be remedied by increasing the heap parameters and restarting Tomcat.
|
||
</p>
|
||
<p>
|
||
Security limits: VIVO 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
|
||
tomcat6 hard nproc 1500
|
||
</pre>
|
||
<h3 id="start_tomcat">VII. 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/vivo/" to test the application. If Tomcat does not
|
||
start up, or the VIVO application is not visible, check the <code>catalina.out</code>
|
||
file in Tomcat's logs directory.
|
||
</p>
|
||
<h3 id="add_rdf">VIII. 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 VIVO. Click the "Log in" link
|
||
near the upper right corner. Log in with the <code>initialAdminUser</code>
|
||
username you set up in Step IV. The initial password for the <code>initialAdminUser</code>
|
||
account is "defaultAdmin" (without the quotes). On first login, you will be
|
||
prompted to select a new password and verify it a second time.
|
||
</p>
|
||
<p>
|
||
After verifying your new password, 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 a number of visibility and display options
|
||
available for each ontology entity. VIVO comes with a core VIVO
|
||
ontology, but you may also upload other 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 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 left of
|
||
the page will show a simple index of the knowledge base.
|
||
</p>
|
||
<p>
|
||
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>
|
||
</p>
|
||
<h3 id="contact_email">IX. 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>Vitro.smtpHost</code>), you will also need to add an email address
|
||
to the VIVO application. This is the email that the contact form
|
||
submits to. 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>Vitro.smtpHost</code>
|
||
in Step IV and do NOT provide an email addressin this
|
||
step, your users will receive a java error in the interface.
|
||
</p>
|
||
<h3 id="tomcat_connector">X. 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.
|
||
8080) and an additional reference to the Tomcat context name (e.g.
|
||
/vivo).
|
||
</p>
|
||
<p>
|
||
This will make VIVO available at "http://example.com" instead of
|
||
"http://example.com:8080/vivo"
|
||
</p>
|
||
<p>
|
||
Using the mod_jk connector allows for communication between Tomcat
|
||
and the primary web server. The <a href="http://tomcat.apache.org/connectors-doc/generic_howto/quick.html">Quick Start HowTo</a>
|
||
on the Apache site describes the minimum server configurations
|
||
for several popular web servers.
|
||
</p>
|
||
<p>
|
||
After setting up the mod_jk connector above, you will need to
|
||
modify the Tomcat's server.xml (located in <code>[tomcat root]/conf/</code>) to respond to
|
||
requests from Apache via the connector. Look for the
|
||
<connector> directive and add the following properties:
|
||
</p>
|
||
<pre>
|
||
connectionTimeout="20000" maxThreads="320" keepAliveTimeout="20000"
|
||
</pre>
|
||
<p>
|
||
Note: the value for maxThreads (320) is equal to the value for MaxClients
|
||
in the apache's <code>httpd.conf</code>
|
||
file.
|
||
</p>
|
||
<p>
|
||
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/vivo"
|
||
reloadable="true"
|
||
cookies="true" >
|
||
<Manager pathname="" />
|
||
<Environment type="java.lang.String" override="false"
|
||
name="path.configuration"
|
||
value="deploy.properties"
|
||
/>
|
||
</Context>
|
||
...
|
||
</pre>
|
||
<h3 id="pellet">XI. Configure Pellet Reasoner </h3>
|
||
<p>
|
||
<em>Do we need this section still? - elly</em>
|
||
</p>
|
||
<p>
|
||
VIVO uses the Pellet engine to perform reasoning, which runs in the
|
||
background at startup and also when the knowledge base is edited. VIVO
|
||
continues serving pages while the reasoner continues working; when the
|
||
reasoner finishes, the new inferences appear. Inferred statements are
|
||
cached in a database graph so that they are available immediately when
|
||
VIVO is restarted.
|
||
</p>
|
||
<p>
|
||
By default, Pellet is fed only an incomplete view of
|
||
your ontology and only certain inferences are materialized. These
|
||
include rdf:type, rdfs:subClassOf, owl:equivalentClass, and
|
||
owl:disjointWith. This mode is typically suitable for ontologies with a
|
||
lot of instance data. If you would like to keep the default mode,
|
||
skip to the next step.
|
||
</p>
|
||
<p>
|
||
To enable "complete" OWL inference (materialize
|
||
all significant entailed statements), open
|
||
"vitro-core/webapp/config/web.xml" and search for PelletReasonerSetup.
|
||
</p>
|
||
<p>
|
||
Then change the name of the listener class to
|
||
PelletReasonerSetupComplete. Because "complete" reasoning can be very
|
||
resource intensive, there is also an option to materialize nearly
|
||
all inferences except owl:sameAs and owl:differentFrom.
|
||
</p>
|
||
<p>
|
||
This is enabled by specifying PelletReasonerSetupPseudocomplete. For ontologies
|
||
with large numbers of individuals, this mode can offer enormous performance
|
||
improvements over the "complete" mode.
|
||
</p>
|
||
<p>
|
||
Finally, a class called PelletReasonerSetupPseudocompleteIgnoreDataproperties
|
||
is provided to improve performance on ontologies with large literals where data
|
||
property entailments are not needed.
|
||
</p>
|
||
</p>
|
||
<h3 id="external_auth">XII. Using an External Authentication System with VIVO </h3>
|
||
<p>
|
||
<p>
|
||
VIVO can be configured to work with an external authentication system like
|
||
Shibboleth or CUWebAuth.
|
||
</p>
|
||
<p>
|
||
VIVO 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 VIVO,
|
||
to identify the user.
|
||
</p>
|
||
<p>
|
||
If VIVO has an account for that user, the user will be logged in with the
|
||
privileges of that account. In the absence of an account, VIVO 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
|
||
VIVO. When a user reaches this secured page, the Apache server will invoke the
|
||
external authentication system.
|
||
</p>
|
||
<p>
|
||
For VIVO, 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 VIVO</h4>
|
||
<p>
|
||
To enable external authentication, VIVO requires three values in the <code>deploy.properties</code>
|
||
file.
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
<h5>The name of the HTTP header that will hold the external user's network ID.</h5>
|
||
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>
|
||
You need to tell VIVO the name of that HTTP header. Insert a line like
|
||
this in the deploy.properties file: <pre>externalAuth.netIdHeaderName = [the header name]</pre>
|
||
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 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:
|
||
externalAuth.buttonText = [the text for your login button]
|
||
For example:
|
||
</p>
|
||
<pre>externalAuth.buttonText = Log in using BearCat Shibboleth</pre>
|
||
The VIVO login form will display a button labelled "Log in using BearCat
|
||
Shibboleth".
|
||
</li>
|
||
<li>
|
||
<h5>Associating a User with a profile page</h5>
|
||
If VIVO has an account for the user, the user will be given the privileges
|
||
assigned to that account.
|
||
<p>
|
||
In addition, VIVO will try to associate the user with a profile page, so
|
||
the user may edit his own profile data. VIVO will search the data model
|
||
for a person with a property that matches the User’s network ID.
|
||
You need to tell VIVO what property should be used for matching. Insert
|
||
a line like this in the deploy.properties file:
|
||
</p>
|
||
<pre>selfEditing.idMatchingProperty = [the URI of the property]</pre>
|
||
For example:<pre>selfEditing.idMatchingProperty = http://vivo.mydomain.edu/ns#networkId</pre>
|
||
</li>
|
||
</ul>
|
||
</p>
|
||
<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 VII 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 account.
|
||
</li>
|
||
</ul>
|
||
<p>
|
||
Here is a simple test to see whether the ontology files were loaded:
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
Click on the "Index" link on the upper left, below the logo. You should see
|
||
a "locations" section, with links for "Country" and "Geographic Location."
|
||
The index is built in a background thread, so on your first login, you may
|
||
see an empty index instead. Refresh the page periodically to see whether
|
||
the index will be populated. This may take some time: with VIVO installed
|
||
on a modest laptop computer, loading the ontology files and building the
|
||
index took more than 5 minutes from the time that Tomcat was started.
|
||
</li>
|
||
<li>
|
||
Click on the "Country" link. You should see an alphabetical list of the
|
||
countries of the world.
|
||
</li>
|
||
</ul>
|
||
<p>
|
||
Here is a test to see whether your system is configured to serve linked data:
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
Point your browser to the home page of your website, and click the "Log in" link
|
||
near the upper right corner. Log in with the <code>initialAdminUser</code>
|
||
username you
|
||
set up in Step IV. If this is your first time logging in, you will be
|
||
prompted to change the password.
|
||
</li>
|
||
<li>
|
||
After you have successfully logged in, click "site admin" in the upper right
|
||
corner. In the drop down under "Data Input" select "Faculty Member(core)"
|
||
and click the "Add individual of this class" button.
|
||
</li>
|
||
<li>
|
||
Enter the name "test individual" under the field "Individual Name," scroll to
|
||
the bottom, and click "Create New Record." You will be taken to the "Individual
|
||
Control Panel." Make note of the value of the field "URI" it will be used in
|
||
the next step.
|
||
</li>
|
||
<li>
|
||
Open a new web browser or browser tab to the page <a href="http://marbles.sourceforge.net/">http://marbles.sourceforge.net/</a>.
|
||
In the pink box on that page enter the URI of the individual you created in the
|
||
previous step and click "open."
|
||
</li>
|
||
<li>
|
||
In the resulting page search for the URI of the "test individual." You should
|
||
find it towards the bottom of the page next to a red dot followed by "redirect
|
||
(303)." This indicates that you are successfully serving linked RDF data.
|
||
If the URI of the "test individual" is followed by "failed (400)" you are not
|
||
successfully serving linked data.
|
||
</li>
|
||
</ul>
|
||
<p>
|
||
Finally, test the search index.
|
||
</p>
|
||
<ul>
|
||
<li>
|
||
Type the word "Australia" into the search box, and click on the Search
|
||
button.You should see a page of results, with links to countries that
|
||
border Australia, individuals that include Australia, and to
|
||
Australia itself. To trigger the search index, you can log in as a site
|
||
administrator and go to "http://your-vivo-url/SearchIndex".
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<!-- #wrapper-content -->
|
||
<footer role="contentinfo">
|
||
<p class="copyright">
|
||
<small>
|
||
©2011
|
||
All Rights Reserved | <a class="terms" href="/termsOfUse">Terms of Use</a>
|
||
</small>
|
||
| Powered by <a class="powered-by-vivo" href="http://vivoweb.org" target="_blank"><strong>VIVO</strong></a>
|
||
</p>
|
||
<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>
|
||
</nav>
|
||
</footer>
|
||
</body>
|
||
</html>
|