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

Convert install instructions and upgrade instructions to Wiki pages and PDF.

Browse source
This commit is contained in:
j2blake 2014-01-21 18:14:09 -05:00
parent 5d64c5acc4
commit 36087a25c0
20 changed files with 300 additions and 8312 deletions
Download patch file Download diff file Expand all files Collapse all files

441
config/example.runtime.properties
View file

@ -9,140 +9,277 @@
# #
# ----------------------------------------------------------------------------- # -----------------------------------------------------------------------------
#
# This namespace will be used when generating URIs for objects created in the # -----------------------------------------------------------------------------
# editor. In order to serve linked data, the default namespace must be composed # BASIC PROPERTIES
# as follows (optional elements in parentheses): # -----------------------------------------------------------------------------
#
# scheme + server_name (+ port) (+ servlet_context) + "/individual/" #
# # This namespace will be used when generating URIs for objects created in the
# For example, Cornell's default namespace is: # editor. In order to serve linked data, the default namespace must be composed
# # as follows (optional elements in parentheses):
# http://vivo.cornell.edu/individual/ #
# # scheme + server_name (+ port) (+ servlet_context) + "/individual/"
#
# For example, Cornell's default namespace is:
#
# http://vivo.cornell.edu/individual/
#
Vitro.defaultNamespace = http://vivo.mydomain.edu/individual/ Vitro.defaultNamespace = http://vivo.mydomain.edu/individual/
# #
# URL of Solr context used in local VIVO search. This will usually consist of: # The email address of the root user for the VIVO application. The password
# scheme + server_name + port + vivo_webapp_name + "solr" # for this user is initially set to "rootPassword", but you will be asked to
# In the standard installation, the Solr context will be on the same server as VIVO, # change the password the first time you log in.
# and in the same Tomcat instance. The path will be the VIVO webapp.name (specified #
# above) + "solr" rootUser.emailAddress = vivo_root@mydomain.edu
# Example:
# vitro.local.solr.url = http://localhost:8080/vivosolr
vitro.local.solr.url = http://localhost:8080/vivosolr
# #
# Email parameters which VIVO can use to send mail. If these are left empty, # The basic parameters for a database connection. Change the end of the
# the "Contact Us" form will be disabled and users will not be notified of # URL to reflect your database name (if it is not "vitrodb"). Change the username
# changes to their accounts. # and password to match the authorized database user you created.
# #
email.smtpHost = smtp.mydomain.edu
email.replyTo = vivoAdmin@mydomain.edu
#
# The basic parameters for a database connection. Change the end of the
# URL to reflect your database name (if it is not "vitrodb"). Change the username
# and password to match the authorized database user you created.
#
VitroConnection.DataSource.url = jdbc:mysql://localhost/vitrodb VitroConnection.DataSource.url = jdbc:mysql://localhost/vitrodb
VitroConnection.DataSource.username = vitrodbUsername VitroConnection.DataSource.username = vitrodbUsername
VitroConnection.DataSource.password = vitrodbPassword VitroConnection.DataSource.password = vitrodbPassword
# #
# The maximum number of active connections in the database connection pool. # Email parameters which VIVO can use to send mail. If these are left empty,
# Increase this value to support a greater number of concurrent page requests. # the "Contact Us" form will be disabled and users will not be notified of
# # changes to their accounts.
#
email.smtpHost = smtp.mydomain.edu
email.replyTo = vivoAdmin@mydomain.edu
#
# URL of Solr context used in local VIVO search. This will usually consist of:
# scheme + server_name + port + vivo_webapp_name + "solr"
# In the standard installation, the Solr context will be on the same server as VIVO,
# and in the same Tomcat instance. The path will be the VIVO webapp.name (specified
# above) + "solr"
# Example:
# vitro.local.solr.url = http://localhost:8080/vivosolr
#
vitro.local.solr.url = http://localhost:8080/vivosolr
# -----------------------------------------------------------------------------
# LINKING USER ACCOUNTS TO PROFILE PAGES
# -----------------------------------------------------------------------------
#
# How is a logged-in user associated with a particular Individual? One way is
# for the Individual to have a property whose value is the username of the user.
# This value should be the URI for that property.
#
selfEditing.idMatchingProperty = http://vivo.mydomain.edu/ns#networkId
# -----------------------------------------------------------------------------
# USING AN EXTERNAL AUTHENTICATION SYSTEM
# -----------------------------------------------------------------------------
#
# 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. Consult the installation instructions for more details.
#
#externalAuth.netIdHeaderName = remote_userID
# -----------------------------------------------------------------------------
# TUNING THE DATABASE CONNECTION POOL
# -----------------------------------------------------------------------------
#
# The maximum number of active connections in the database connection pool.
# Increase this value to support a greater number of concurrent page requests.
#
VitroConnection.DataSource.pool.maxActive = 40 VitroConnection.DataSource.pool.maxActive = 40
# #
# The maximum number of database connections that will be allowed # The maximum number of database connections that will be allowed
# to remain idle in the connection pool. Default is 25% # to remain idle in the connection pool. Default is 25%
# of the maximum number of active connections. # of the maximum number of active connections.
# #
VitroConnection.DataSource.pool.maxIdle = 10 VitroConnection.DataSource.pool.maxIdle = 10
#
# Parameters to change in order to use VIVO with a database other than # -----------------------------------------------------------------------------
# MySQL. # USING A DIFFERENT DATA STORE
# # -----------------------------------------------------------------------------
#
# Parameters to change in order to use VIVO with a database other than
# MySQL.
#
VitroConnection.DataSource.dbtype = MySQL VitroConnection.DataSource.dbtype = MySQL
VitroConnection.DataSource.driver = com.mysql.jdbc.Driver VitroConnection.DataSource.driver = com.mysql.jdbc.Driver
VitroConnection.DataSource.validationQuery = SELECT 1 VitroConnection.DataSource.validationQuery = SELECT 1
# #
# Optional URI of a SPARQL endpoint from which VIVO should display data. # Optional URI of a SPARQL endpoint from which VIVO should display data.
# If set, VIVO will use this endpoint as its triple store instead of the # If set, VIVO will use this endpoint as its triple store instead of the
# SDB database. # SDB database.
# #
#VitroConnection.DataSource.endpointURI = #VitroConnection.DataSource.endpointURI =
# #
# Optional URI to use for modifying the above endpoint via SPARQL UPDATE. # Optional URI to use for modifying the above endpoint via SPARQL UPDATE.
# This setting is only necessary if the endpoint does not support updates via # This setting is only necessary if the endpoint does not support updates via
# its main URI. (This may be done for access control purposes.) # its main URI. (This may be done for access control purposes.)
# If the endpointURI above is not set, this setting has no effect. # If the endpointURI above is not set, this setting has no effect.
# #
#VitroConnection.DataSource.updateEndpointURI = #VitroConnection.DataSource.updateEndpointURI =
#
# The email address of the root user for the VIVO application. The password
# for this user is initially set to "rootPassword", but you will be asked to
# change the password the first time you log in.
#
rootUser.emailAddress = vivo_root@mydomain.edu
# # -----------------------------------------------------------------------------
# How is a logged-in user associated with a particular Individual? One way is # ADDING OPENSOCIAL GADGETS TO VIVO
# for the Individual to have a property whose value is the username of the user. # -----------------------------------------------------------------------------
# This value should be the URI for that property.
#
selfEditing.idMatchingProperty = http://vivo.mydomain.edu/ns#networkId
# #
# If an external authentication system like Shibboleth or CUWebAuth is to be # For OpenSocial integration
# used, this property says which HTTP header will contain the user ID from # The base URL of the ORNG Shindig server. Usually, this is the same host and port
# the authentication system. If such a system is not to be used, leave this # number as VIVO itself, with a context path of "shindigorng".
# commented out. Consult the installation instructions for more details. #
# #OpenSocial.shindigURL = http://localhost:8080/shindigorng
#externalAuth.netIdHeaderName = remote_userID
# #
# The temporal graph visualization can require extensive machine resources. # For OpenSocial integration
# This can have a particularly noticeable impact on memory usage if # The host name and port number of the service that provides security tokens for VIVO and
# - The organization tree is deep, # Shindig to share. For now, the host name must be the actual host, not "localhost" or "127.0.0.1"
# - The number of grants and publications is large. # The port number must be 8777
# VIVO 1.3 release mitigates this problem by the way of a caching mechanism & #
# hence we can safely set this to be enabled by default. #OpenSocial.tokenService = myhost.mydomain.edu:8777
#
visualization.temporal = enabled
# #
# The temporal graph visualization is used to compare different organizations/people # For OpenSocial integration
# within an organization on parameters like number of publications or grants. # The path to the key file that will be used qwhen generating security tokens for VIVO and
# By default, the app will attempt to make its best guess at the top level # shindig to share.
# organization in your instance. If you're unhappy with this selection, uncomment out #
# the property below and set it to the URI of the organization individual you want to #OpenSocial.tokenKeyFile = /usr/local/vivo/data/shindig/openssl/securitytokenkey.txt
# identify as the top level organization. It will be used as the default whenever the
# temporal graph visualization is rendered without being passed an explicit org.
# For example, to use "Ponce School of Medicine" as the top organization:
# visualization.topLevelOrg = http://vivo.psm.edu/individual/n2862
#
# visualization.topLevelOrg = http://vivo.mydomain.edu/individual/topLevelOrgURI
# #
# Absolute path on the server of the Harvester root directory. # For OpenSocial integration
# You must include the final slash. # Only set sandbox to True for dev/test environments. Comment out or set to False in production
# Setting a value for harvester.location indicates that the Harvester is installed at #
# this path. This will enable the Harvester functions in the Ingest Tools page. #OpenSocial.sandbox = True
#
# -----------------------------------------------------------------------------
# ADDING LANGUAGES TO VIVO
# -----------------------------------------------------------------------------
#
# Show only the most appropriate data values based on the Accept-Language
# header supplied by the browser. Default is false if not set.
#
# RDFService.languageFilter = false
#
# 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.
#
# languages.forceLocale = en_US
#
# 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.
#
# This should not be used with languages.forceLocale, which will override it.
#
# languages.selectableLocales = en_US, es_GO
# -----------------------------------------------------------------------------
# OTHER OPTIONS
# -----------------------------------------------------------------------------
#
# When the following flag is set to enabled, the VIVO home page displays a
# global map highlighting the geographical focus of foaf:person individuals.
# For information on the maps, refer to this wiki page:
# https://wiki.duraspace.org/display/VIVO/Home+Page+Customizations#HomePageCustomizations-TheGeographicFocusMap
#
#homePage.geoFocusMaps=enabled
#
# VIVO supports the simultaneous use of a full foaf:Person profile page view
# and a "quick" page view that emphasizes the individual's webpage presence.
# Implementing this feature requires an installation to develop a web service
# that captures images of web pages or to use an existing service outside of VIVO.
#
# For more information on implementing multiple profile pages, refer to this
# wiki page: https://wiki.duraspace.org/display/VIVO/Multiple+foaf%3APerson+Profile+Pages.
#
#multiViews.profilePageTypes=enabled
#
# Tell VIVO to generate HTTP headers on its responses to facilitate caching the
# profile pages that it creates.
#
# For more information, see this wiki page:
# https://wiki.duraspace.org/display/VIVO/Use+HTTP+caching+to+improve+performance
#
# Developers will likely want to leave caching disabled, since a change to a
# Freemarker template or to a Java class would not cause the page to be
# considered stale.
#
# http.createCacheHeaders = true
#
# Absolute path on the server of the Harvester root directory.
# You must include the final slash.
#
# Setting a value for harvester.location indicates that the Harvester is installed at
# this path. This will enable the Harvester functions in the Ingest Tools page.
#
# harvester.location = /usr/local/vivo/harvester/ # harvester.location = /usr/local/vivo/harvester/
# #
# Default type(s) for Google Refine Reconciliation Service # The temporal graph visualization is used to compare different organizations/people
# The format for this property is id, name; id1, name1; id2, name2 etc. # within an organization on parameters like number of publications or grants.
# See Service Metadata from this page http://code.google.com/p/google-refine/wiki/ReconciliationServiceApi # By default, the app will attempt to make its best guess at the top level
# for more information. # organization in your instance. If you're unhappy with this selection, uncomment out
# the property below and set it to the URI of the organization individual you want to
# identify as the top level organization. It will be used as the default whenever the
# temporal graph visualization is rendered without being passed an explicit org.
# For example, to use "Ponce School of Medicine" as the top organization:
# visualization.topLevelOrg = http://vivo.psm.edu/individual/n2862
#
# visualization.topLevelOrg = http://vivo.mydomain.edu/individual/topLevelOrgURI
#
# The temporal graph visualization can require extensive machine resources.
# This can have a particularly noticeable impact on memory usage if
# - The organization tree is deep,
# - The number of grants and publications is large.
# VIVO 1.3 release mitigates this problem by the way of a caching mechanism &
# hence we can safely set this to be enabled by default.
#
visualization.temporal = enabled
#
# Types of individual for which we can create proxy editors.
# If this is omitted, defaults to http://www.w3.org/2002/07/owl#Thing
#
proxy.eligibleTypeList = http://xmlns.com/foaf/0.1/Person, http://xmlns.com/foaf/0.1/Organization
#
# Default type(s) for Google Refine Reconciliation Service
# The format for this property is id, name; id1, name1; id2, name2 etc.
# For more information, see Service Metadata from this page:
# http://code.google.com/p/google-refine/wiki/ReconciliationServiceApi
#
Vitro.reconcile.defaultTypeList = http://vivoweb.org/ontology/core#Role, core:Role; \ Vitro.reconcile.defaultTypeList = http://vivoweb.org/ontology/core#Role, core:Role; \
http://vivoweb.org/ontology/core#AcademicDegree, core:Academic Degree; \ http://vivoweb.org/ontology/core#AcademicDegree, core:Academic Degree; \
http://purl.org/NET/c4dm/event.owl#Event, event:Event; \ http://purl.org/NET/c4dm/event.owl#Event, event:Event; \
@ -150,91 +287,3 @@ Vitro.reconcile.defaultTypeList = http://vivoweb.org/ontology/core#Role, core:Ro
http://xmlns.com/foaf/0.1/Organization, foaf:Organization; \ http://xmlns.com/foaf/0.1/Organization, foaf:Organization; \
http://xmlns.com/foaf/0.1/Person, foaf:Person; \ http://xmlns.com/foaf/0.1/Person, foaf:Person; \
http://purl.obolibrary.org/obo/IAO_0000030, obo:IAO_0000030 http://purl.obolibrary.org/obo/IAO_0000030, obo:IAO_0000030
#
# Types of individual for which we can create proxy editors.
# If this is omitted, defaults to http://www.w3.org/2002/07/owl#Thing
#
proxy.eligibleTypeList = http://xmlns.com/foaf/0.1/Person, http://xmlns.com/foaf/0.1/Organization
#
# Show only the most appropriate data values based on the Accept-Language
# header supplied by the browser. Default is false if not set.
#
# RDFService.languageFilter = false
#
# 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.
#
# languages.forceLocale = en_US
#
# 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.
#
# This should not be used with languages.forceLocale, which will override it.
#
# languages.selectableLocales = en_US, es_GO
#
# Tell VIVO to generate HTTP headers on its responses to facilitate caching the
# profile pages that it creates.
#
# For more information, see
# https://wiki.duraspace.org/display/VIVO/Use+HTTP+caching+to+improve+performance
#
# Developers will likely want to leave caching disabled, since a change to a
# Freemarker template or to a Java class would not cause the page to be
# considered stale.
#
# http.createCacheHeaders = true
#
# For OpenSocial integration
# The base URL of the ORNG Shindig server. Usually, this is the same host and port
# number as VIVO itself, with a context path of "shindigorng".
#
#OpenSocial.shindigURL = http://localhost:8080/shindigorng
#
# For OpenSocial integration
# The host name and port number of the service that provides security tokens for VIVO and
# Shindig to share. For now, the host name must be the actual host, not "localhost" or "127.0.0.1"
# The port number must be 8777
#
#OpenSocial.tokenService = myhost.mydomain.edu:8777
#
# For OpenSocial integration
# The path to the key file that will be used qwhen generating security tokens for VIVO and
# shindig to share.
#
#OpenSocial.tokenKeyFile = /usr/local/vivo/data/shindig/openssl/securitytokenkey.txt
#
# For OpenSocial integration
# Only set sandbox to True for dev/test environments. Comment out or set to False in production
#
#OpenSocial.sandbox = True
# MultiViews
# VIVO supports the simultaneous use of a full foaf:Person profile page view and a "quick" page
# view that emphasizes the individual's webpage presence. Implementing this feature requires an
# installation to develop a web service that captures images of web pages or to use an existing
# service outside of VIVO. For more information on implementing multiple profile pages, refer to
# this wiki page: https://wiki.duraspace.org/display/VIVO/Multiple+foaf%3APerson+Profile+Pages.
#multiViews.profilePageTypes=enabled
# Geo Focus Maps
# When the following flag is set to enabled, the VIVO home page displays a global map highlighting the
# geographical focus of foaf:person individuals. For information on the maps, refer to this wiki page:
# https://wiki.duraspace.org/display/VIVO/Home+Page+Customizations#HomePageCustomizations-TheGeographicFocusMap
#homePage.geoFocusMaps=enabled

19
doc/README.txt Normal file
View file

@ -0,0 +1,19 @@
Welcome to VIVO!
======================
If you obtained this file from a distributed release of VIVO, you should
find these files in this directory:
VIVO Installation Instructions.pdf
Instructions for installing VIVO on your machine, including
a simple installation and several options.
Upgrade Instructions for VIVO release 1.6.pdf
Instructions for migrating a VIVO installation from release
1.5 to release 1.6
If these files are not present, or to obtain the latest version of the
instructions, go to:
https://wiki.duraspace.org/display/VIVO/VIVO+Documentation

255
doc/css/doc.css
View file

@ -1,255 +0,0 @@
/* $This file is distributed under the terms of the license in /doc/license.txt$ */
@charset "UTF-8";
/* CSS Document */
/* Tell the browser to render HTML 5 elements as block */
header,
toc,
hgroup,
section,
nav,
article,
aside,
footer{
display: block;
}
time{
font-weight: normal;
}
html,
body{
margin: 0;
padding: 0;
height: 100%; /* needed for container min-height */
font-family: 'Arimo', "Lucida Sans Unicode","Lucida Grande", Geneva, helvetica, sans-serif;
font-size: 1em;
height: auto !important; /* real browsers */
height: 100%; /* IE6: treaded as min-height*/;
min-height: 100%; /* real browsers */
margin: 0 auto;
}
body{
background: #f3f3f0 url(../images/header-background.png) center 0 no-repeat;
}
/* h1,h2,h3,h4,h5,h6 ------> */
h1 {
padding: 8px 0 6px 0;
margin: 0;
font-size: 1.5em;
}
h2 {
padding: 8px 0 6px 0;
margin: 0;
font-size: 1.4em;
color: #2485ae;
}
h2 a{
color: #2485ae;
}
h2 a:link, h2 a:visited{
text-decoration: underline;
}
h2 a:hover, h2 a:active{
text-decoration: none;
}
h3{
padding: 8px 0 6px 0;
margin: 0;
font-size: 1.2em;
color: #2485ae;
}
h4{
padding: 4px 0 4px 0;
margin: 0;
font-size: 1.1em;
color: #000000;
}
h5{
padding: 3px 0 2px 0;
margin: 0;
font-size: 1em;
color: #2485ae;
}
a {
text-decoration: underline;
color: #2485ae;
}
a:visited {
text-decoration: underline;
color: #5e6363;
}
code, pre {
font-size: 1.1em;
}
blockquote {
padding: 5px;
font-size: .9em;
background-color: #EEEEEE;
}
/* HEADER ------> */
#branding {
position: relative;
width: 970px;
height: 114px;
margin: 0 auto;
}
/* BRANDING ------> */
h1.vivo-logo {
position: absolute;
width: 442px;
height: 59px;
top: 28px;
left: 0;
background: url(../images/VIVO-logo.png) 0 0 no-repeat;
}
h1.vivo-logo a {
display: block;
width: 386px;
height: 59px;
}
/* WRAPPER CONTENT------> */
#wrapper-content {
clear: both;
width: 930px;
margin: 0 auto;
background: #fff;
min-height: 550px;
padding: 20px;
}
/* TOC -------> */
ol {
margin: 0 0 10px 10px;
}
/* TABLE --------> */
table {
margin: 10px auto;
border-width: 1px;
border-spacing: 2px;
border-style: outset;
border-color: gray;
border-collapse: collapse;
}
th {
border-width: 1px;
padding: 4px;
border-style: inset;
border-color: white;
background: #2485ae;
color: #FFFFFF;
}
td {
border-width: 1px;
padding: 4px 4px 4px 6px;
border-style: inset;
border-color: #EEEEEE;
-moz-border-radius: 0px 0px 0px 0px;
}
tr {
background: #EEEEEE;
}
tr.odd_row {
background: #FFFFFF;
border-bottom: 1px solid #999999;
font-weight: bold;
}
/* FOOTER------> */
div#footer {
clear: both;
width: 970px;
height: 88px;
margin: 0 auto;
font-size: 0.7em;
color: #4e5051;
background-color: #fff;
}
div#footer p.copyright {
float: left;
padding-top: 50px;
padding-left: 30px;
width: 500px;
}
ul#footer-nav {
float: right;
list-style: none;
width: 300px;
height: 20px;
margin: 0;
padding: 0;
padding-top: 50px;
padding-right: 20px;
}
ul#footer-nav li {
float: left;
display: block;
padding-left: 10px;
padding-right: 10px;
border-right: 1px solid #c9c8c8;
}
ul#footer-nav li:last-child {
border-right: none
}
#footer-nav a {
color: #4e5051
}
#footer-nav a:hover {
color: #09C;
text-decoration: none;
}
a.terms {
color: #09C;
text-decoration: none;
}
a.terms:hover {
color: #4e5051;
text-decoration: none;
}
a.powered-by-vivo {
color: #09C;
text-decoration: none;
}
a.powered-by-vivo:hover {
color: #4e5051;
text-decoration: none;
}
/* GENERAL STYLE------> */
p{
margin-bottom: 1.3em;
}
/* MISCELLANEOUS ------> */
.blue{
color: #2485ae;
}
.grey{
color: #5e6363;
}
.green{
color: #b2d15a;
}
.displace {
position: absolute;
left: -9999px;
}
ol.roman1 {
list-style-type: upper-roman;
}
ol.roman2 {
list-style-type: lower-roman;
}

45
doc/developers.txt
View file

@ -1,45 +0,0 @@
-------------------------------------------------------------------------------
Instructions for VIVO developers
-------------------------------------------------------------------------------
If you are working from the VIVO distribution files, you should follow the
instructions in "install.html", in this directory.
-------------------------------------------------------------------------------
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.
Follow these steps:
1) In the VIVO working area, create build.properties as a copy of
example.build.properties
2) Check out the Vitro source files from Git into a separate working
area.
3) Modify build.properties (created in step 1) so vitro.core.dir points to
the Vitro working area (created in step 2). For example:
vitro.core.dir = ../vitro
4) Follow the instructions in "install.html" to complete the installation,
omitting step 3.
-------------------------------------------------------------------------------
Answers to Frequently Asked Questions:
-------------------------------------------------------------------------------
Q: I'm running VIVO in Tomcat on a MacIntosh. When I upload an image file, a
strange icon appears in the dock. What's up with that?
A: The image processing code in VIVO uses javax.imageio.ImageIO, which in turn
uses code in the java.awt package. By default, this package will open a work
area on your screen, producing this icon even though no visible window is
created.
You can prevent this by editing {tomcat}/conf/setenv.sh, and adding the
"java.awt.headless" option. For example,
export CATALINA_OPTS="-Xms1024m -Xmx1024m -XX:MaxPermSize=64m -Djava.awt.headless=true"

BIN
doc/images/VIVO-logo.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 6.6 KiB

BIN
doc/images/header-background.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 52 KiB

1370
doc/install.html
View file

File diff suppressed because it is too large Load diff

254
doc/other_servlet_containers.html
View file

@ -1,254 +0,0 @@
<!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/log4j.properties</code>.
<em>(Note: if <code>debug.log4j.properties</code> exists,
it will override <code>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>

242
doc/release.html
View file

@ -1,242 +0,0 @@
<!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.5 Announcement</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>VIVO Release 1 V1.5 Announcement</h1>
<small> July 11, 2012 </small>
<toc>
<ul>
<!-- filled out by js -->
</ul>
</toc>
<div class="wiki-content">
<h4>
<a name="VIVORelease1.5Announcement-Overview"></a>Overview
</h4>
<p>VIVO 1.5 introduces a number of new features addressing
extensibility and interoperability, reasoning, page customization,
and a first step toward internationalization. VIVO's profile
management has been improved with a number of new custom forms, and
there are significant improvements to ontology browsing and editing.</p>
<p>The VIVO 1.5 development cycle has also included extensive
design work on features anticipated for implementation beginning
with version 1.6, including increased modularity, the introduction
of a separate ontology for display and editing controls, and the
addition of a graphical ontology class expression editor.</p>
<h4>
<a name="VIVORelease1.5Announcement-Extensibility"></a>Extensibility
</h4>
<p>Since version 1.2, VIVO’s use of the Jena Semantic Web
framework (1) has allowed implementation sites to use any database
supported by Jena, including MySQL, PostgreSQL, and Oracle. VIVO
Release 1.5 extends this flexibility a major step further by making
it much easier to extend VIVO to use any triple store, and include
an experimental feature that supports connecting to any triple store
that exposes a SPARQL endpoint that supports SPARQL update. Initial
tests with Sesame are quite promising.</p>
<h4>
<a name="VIVORelease1.5Announcement-VIVOisnowanOpenSocialcontainer"></a>VIVO
is now an OpenSocial container
</h4>
<p>The OpenSocial standard (2) defines a web-based container
environment for hosting third-party components in a web application
and provides a set of common application programming interfaces for
developing these components by leveraging the Google Gadgets (3)
framework. Eric Meeks and colleagues at the University of
California–San Francisco and other institutions have developed
OpenSocial gadgets designed to work with RDF expressed using the
VIVO ontology. For VIVO 1.5, Eric has adapted the Apache Shindig (4)
OpenSocial reference implementation to communicate with VIVO and
collaborated with the VIVO development team in extending VIVO itself
to support OpenSocial gadgets referencing data in VIVO or bringing
additional data to VIVO based on page being viewed.</p>
<h4>
<a name="VIVORelease1.5Announcement-Reasoning"></a>Reasoning
</h4>
<p>The simple reasoner built into VIVO now has support for sameAs
reasoning to allow joint display of statements associated with two
URIs that have been asserted or inferred to be sameAs each other.
The VIVO reasoner will also now maintain inverse property statements
based on presence or absence of inverse property declarations in an
ontology. Although the VIVO application has previously added and
removed property inverse statements during interactive editing, this
feature had been requested to simplify the preparation of data for
ingest with the VIVO Harvester or other tools. Recomputing
inferences will trigger the reasoner to supply any missing inverse
property statements.</p>
<h4>
<a name="VIVORelease1.5Announcement-Newpagetypes"></a>New page types
</h4>
<p>The VIVO 1.5 release expands the flexibility of VIVO as a web
application by adding additional dynamic content features. Sites may
create arbitrary HTML pages or web pages that display the results of
SPARQL queries and link to those from any template in the
application; these new pages may optionally be top-level menu pages
and may include multiple sections featuring the results of
parameterized SPARQL queries and static HTML content as well as data
filtered by class group and type. New page specifications are
typically paired with page template modifications to provide the
desired level of control over display of dynamic content. These
changes significantly augment VIVO's native reporting capabilities
and enable sites to demonstrate aggregation, interconnectivity, and
network effects in VIVO data. Queries and report templates will be
useful to share across sites and a SPARQL resource page has already
been established on the VIVO wiki (5).</p>
<h4>
<a name="VIVORelease1.5Announcement-Customizedshortviews"></a>Customized
short views
</h4>
<p>Site maintainers may also customize the way that individuals
are displayed on VIVO index pages, browse pages, or search results -
all without modifying the basic VIVO code. Custom templates,
populated by custom queries, can be assigned to classes of
individuals in any of these contexts.</p>
<h4>
<a name="VIVORelease1.5Announcement-Languagefilter"></a>Language
filter
</h4>
<p>VIVO 1.5 will respect a user's browser language preference
setting and filter labels and data property text strings to only
display values matching that language setting whenever versions in
multiple languages are available. This is an important first step
toward internationalization of the VIVO application, an effort we
expect to continue in future releases.</p>
<h4>
<a name="VIVORelease1.5Announcement-Improvedediting"></a>Improved
editing
</h4>
<p>VIVO 1.5 includes new forms to simplify entry and editing of
awards, advising relationships, and additional types of
publications. Forms make greater use of autocomplete functionality,
and very large pick lists are converted to autocomplete
functionality by the application on the fly.</p>
<h4>
<a
name="VIVORelease1.5Announcement-ImprovedMapofSciencevisualization"></a>Improved
Map of Science visualization
</h4>
<p>VIVO's Map of Science visualizations benefit from improved
labeling and color coding as well as additional explanation; the
maps also now support dynamic interchange between discipline and
sub-discipline sliders.</p>
<h4>
<a name="VIVORelease1.5Announcement-Ontologychanges"></a>Ontology
changes
</h4>
<p>
Ontology changes from 1.4 to 1.5 include identifying primary job
appointments, modeling citation information for publications, and
adding new types of publications to better align with PubMed.
Changes for each release are documented on the VIVO wiki on
Sourceforge at <a
href="http://sourceforge.net/apps/mediawiki/vivo/index.php?title=Ontology"
class="external-link" rel="nofollow">http://sourceforge.net/apps/mediawiki/vivo/index.php?title=Ontology</a>.
</p>
<p>
The VIVO ontology is now available via the Bioportal (<a
href="http://www.bioontology.org/bioportal" class="external-link"
rel="nofollow">http://www.bioontology.org/bioportal</a>), an open
repository of ontologies hosted by the National Center for
Biomedical Ontology.
</p>
<h4>
<a name="VIVORelease1.5Announcement-Acknowledgements"></a>Acknowledgements
</h4>
<p>This release represents the work of the entire VIVO team and
contributions of feature requests, requirements development and
design, ontology design reviews, software development, and testing
from the larger VIVO open source community.</p>
<p>The VIVO project is funded by the National Institutes of
Health, U24 RR029822, "VIVO: Enabling National Networking of
Scientists".</p>
<h4>
<a name="VIVORelease1.5Announcement-References"></a>References
</h4>
<ol>
<li><a href="http://jena.apache.org/" class="external-link"
rel="nofollow">http://jena.apache.org/</a></li>
<li><a href="http://docs.opensocial.org/display/OS/Home"
class="external-link" rel="nofollow">http://docs.opensocial.org/display/OS/Home</a></li>
<li><a href="https://developers.google.com/gadgets/"
class="external-link" rel="nofollow">https://developers.google.com/gadgets/</a></li>
<li><a href="http://shindig.apache.org/" class="external-link"
rel="nofollow">http://shindig.apache.org/</a></li>
<li><a
href="http://sourceforge.net/apps/mediawiki/vivo/index.php?title=SPARQL_Resources"
class="external-link" rel="nofollow">http://sourceforge.net/apps/mediawiki/vivo/index.php?title=SPARQL_Resources</a></li>
</ol>
</div>
<!-- wiki content -->
<div id="footer" role="contentinfo">
<p class="copyright">
<small> All Rights Reserved <a href="license.txt">see
license</a>
</small>
</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>
<script>
function init() {
//fill out TOC
var tocList = document.querySelector('toc>ul');
var h4Anchors = document.querySelectorAll('a[name]');
for ( var i = 0; i < h4Anchors.length; i++) {
var a = document.createElement('a');
a.href = '#' + h4Anchors[i].name;
a.textContent = h4Anchors[i].parentNode.textContent
var li = document.createElement('li');
li.appendChild(a);
tocList.appendChild(li);
}
}
window.onload = init;
</script>
</body>
</html>

807
doc/setting_up_orng.html
View file

@ -1,807 +0,0 @@
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>Setting up VIVO to use OpenSocial Gadgets</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>Setting up VIVO to use OpenSocial Gadgets</h1>
<small>
Instructions for connecting VIVO and Open Research Networking Gadgets
</small>
<p>
This document contains instructions on how to configure your VIVO
installation to use OpenSocial gadgets.
</p>
<p>
VIVO uses an extension of the OpenSocial protocols called
Open Research Networking Gadgets, or ORNG.
ORNG is a project of the Clinical & Translational Science Institute at the
University of California, San Francisco.
You can find out more about the ORNG project at their web site,
<a href="http://www.opengadgets.org/index.html">http://www.opengadgets.org/index.html</a>
</p>
<p>
ORNG supports gadgets using a modified version of Apache Shindig.
These instructions tell you how to install the Shindig-ORNG web application,
and how to configure it to work with VIVO.
</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/>
<h2 id="tableofcontents">Table of Contents</h2>
<toc>
<ol class="roman1">
<li> <a href="#installation">Installing and Configuring</a>
<ol class="roman2">
<li><a href="#database">Create database tables and procedures</a></li>
<li><a href="#config_files">Create configuration directory and key file</a></li>
<li><a href="#tomcat_settings">Modify Tomcat settings</a></li>
<li><a href="#vivo_settings">Configure VIVO</a></li>
<li><a href="#deploy">Run the deployment script</a></li>
<li><a href="#confirm">Does it work?</a></li>
</ol>
</li>
<li> <a href="#gadgets">Changing the gadget configurations</a>
<ol class="roman2">
<li><a href="#orng_apps">The <em>orng_apps</em> database table</a></li>
<li><a href="#orng_app_views">The <em>orng_app_views</em> database table</a></li>
</ol>
</li>
<li> <a href="#additional">Additional Considerations</a>
<ol class="roman2">
<li><a href="#redeploying">Re-running the deployment script</a></li>
<li><a href="#cache">Resetting the gadget cache</a></li>
<li><a href="#LOD_issues">Issues with Linked Open Data</a></li>
<li><a href="#disabling">Disabling the OpenSocial gadgets</a></li>
</ol>
</li>
</ol>
</toc>
<hr/>
<h2 id="installation">I. Installing and Configuring</h2>
<h3 id="database">I.i. Create database tables and procedures</h3>
<p>
Shindig-ORNG uses several database tables in MySQL to store its data:
which gadgets appear on which pages, how large are the gadgets,
what information applies to each individual, and more.
Shindig-ORNG also creates stored procedures in MySQL. These are small
pieces of code that simplify the use of the database tables.
</p>
<p>
In the VIVO distribution directory, a file called
<em>vitro-core/opensocial/shindig_orng_tables.sql</em>
contains SQL commands that create the tables and
stored procedures for Shindig-ORNG to use.
</p>
<p>
Tell MySQL to process this file with a command like this:
<pre>mysql -u <em>username</em> -p <em>database</em> &lt; <em>sql_file</em></pre>
So, if your current directory is the VIVO distibution directory, and your
VIVO database is <em>vivoDb</em> and your MySQL user account is <em>vivoUser</em>,
then you might use the command this way:
<pre>mysql -u vivoUser -p vivoDb &lt; vitro-core/opensocial/shindig_orng_tables.sql</pre>
MySQL will prompt you for the password for your MySQL user account, and then
process the file.
</p>
<p>
You may want to start your gadget collection with some example gadgets
that have been developed by the ORNG group. The file called
<em>vitro-core/opensocial/shindig_example_gadgets.sql</em>
contains SQL commands that will add these gadgets to your system's configuration.
</p>
<p>
If you want to load these example gadgets, you can use a command similar to the previous one:
<pre>mysql -u vivoUser -p vivoDb &lt; vitro-core/opensocial/shindig_example_gadgets.sql</pre>
As before, MySQL will prompt you for the password for your MySQL user account, and then
process the file.
</p>
<h3 id="config_files">I.ii. Create configuration directory and key file</h3>
<p>
In your VIVO home directory, create a directory called <em>shindig</em>.
Under that, create directories called <em>conf</em> and <em>openssl</em>.
Your VIVO home directory will look something like this:
<pre> [VIVO home directory]
|
|--shindig
| |
| |--conf
| |
| |--openssl
|
|--solr
|
|--uploads</pre>
</p>
<p>
Shindig-ORNG uses an encryption key to insure that the communication
between the gadget and the server is secure.
You should create a file that contains the encryption key,
and store that file in the <em>shindig/openssl</em> directory that you created.
</p>
<p>
On Unix-based systems (like Linux or Mac OS X), this command will create
an encryption key from a random seed:
<pre>dd if=/dev/random bs=32 count=1 | openssl base64 > <em>[key-file]</em></pre>
For example, if your VIVO home directory is <em>/usr/local/vivo/data</em>,
you might use the command this way:
<pre>dd if=/dev/random bs=32 count=1 | openssl base64 > /usr/local/vivo/data/shindig/openssl/securitytokenkey.txt</pre>
</p>
<p>
If your VIVO installation is installed on a machine that runs Microsoft Windows,
you will need to find another way to create an encryption key.
The easiest way might be to find a Unix-based machine,
issue the command above, and copy the resulting file to your Windows machine.
</p>
<h3 id="tomcat_settings">I.iii. Modify Tomcat settings</h3>
<p>
The Shindig-ORNG application must know where to find the configuration file that you created in
Step I.
It must also know its own URL, so that URL can be inserted into the gadgets.
</p>
<p>
This information is provided through startup parameters in Tomcat.
With most installations of Tomcat, the "setenv.sh" or
"setenv.bat" file in Tomcat's bin directory is a convenient place to
set these parameters.
<em>If this file does not exist in Tomcat's bin directory, you can create it.</em>
</p>
<p>
Here is an example of the setenv.sh file, showing only the Shindig-ORNG requirements:
<pre>export CLASSPATH=/usr/local/vivo/data/shindig/conf
export CATALINA_OPTS="-Dshindig.host=localhost -Dshindig.port=8080"</pre>
</p>
<p>
Here is the equivalent file for an installation in Windows.
<pre>set CLASSPATH=C:\vivo\data\shindig\conf
set CATALINA_OPTS=-Dshindig.host=localhost -Dshindig.port=8080</pre>
</p>
<p>
This assumes that your setenv file was empty before starting this process,
and that you used the default location for the Shindig-ORNG configuration file in Step I.
In fact, it's more common for the setenv file to contain other parameters besides
those used for Shindig-ORNG. In that case, it might look more like this:
<pre>export CLASSPATH=/usr/local/vivo/data/shindig/conf
export CATALINA_OPTS="-Dshindig.host=localhost -Dshindig.port=8080 -Djava.awt.headless=true -Xms1024m -Xmx1024m -XX:MaxPermSize=128m"</pre>
</p>
<p>
Or, for Windows:
<pre>set CLASSPATH=C:\vivo\data\shindig\conf
set CATALINA_OPTS=-Dshindig.host=localhost -Dshindig.port=8080 -Djava.awt.headless=true -Xms1024m -Xmx1024m -XX:MaxPermSize=128m</pre>
</p>
<h3 id="vivo_settings">I.iv Configure VIVO</h3>
<p>
In the VIVO distribution directory, the file called <em>build.properties</em>
contains configuration options for the VIVO application.
You must set some additional parameters so VIVO will be able to communicate with Shindig-ORNG.
</p>
<table border='1' bordercolor="#CCCCCC" cellspacing="5">
<tbody>
<tr>
<th>
Property Name
</th>
<th>
Example Value
</th>
</tr>
<tr>
<td colspan="2">
The base URL that VIVO will use when contacting the Shindig-ORNG application.
Usually, this is the same host and port number as VIVO itself,
with a context path of <em>shindigorng</em>
</td>
</tr>
<tr class="odd_row">
<td>OpenSocial.shindigURL</td>
<td>http://localhost:8080/shindigorng</td>
</tr>
<tr>
<td colspan="2">
The host name and port number of the Token Service that Shindig-ORNG creates.
Note that a value of <em>localhost</em> or <em>127.0.0.1</em> will not work.
You must provide the actual host name of your machine, followed by <em>:8777</em>
</td>
</tr>
<tr class="odd_row">
<td>OpenSocial.tokenService</td>
<td>myhost.mydomain.edu:8777</td>
</tr>
<tr>
<td colspan="2">
The path to a key file that will be used to generate security tokens. This is the
file that was created in Step I of this process.
</td>
</tr>
<tr class="odd_row">
<td>OpenSocial.tokenKeyFile</td>
<td>/usr/local/vivo/data/shindig/openssl/securitytokenkey.txt</td>
</tr>
</tbody>
</table>
<h3 id="deploy">I.v. Run the deployment script</h3>
<p>
At the command line, from the top level of the VIVO distribution
directory, type:
<pre> ant orng</pre>
to configure the Shindig-ORNG application and deploy it to Tomcat's webapps directory.
</p>
<p>
You must restart Tomcat so the main VIVO application will load the new settings
in <em>runtime.properties</em>.
</p>
<h3 id="confirm">I.vi Does it work?</h3>
<h4>Startup tests</h4>
<p>
Start VIVO, and verify that you can see VIVO's home page in a browser.
</p>
<p>
On startup, VIVO runs a series of self-diagnostics, or "smoke tests". If these tests find
any problems with the OpenSocial configuration, you will see a warning message instead of
the VIVO home page.
</p>
<p>
Some of VIVO's "smoke tests" are run after the startup is finished, and may take up to a minute
to complete. If one of these tests fails, you will see the warning message as you
navigate from one VIVO page to the next.
</p>
<p>
If one of the OpenSocial tests fails, you may continue to use VIVO, but it is
likely that no gadgets will be shown.
You can review the warning message by selecting the "Startup Status"
link from the "Site Admin" page.
</p>
<h4>Search page</h4>
<p>
If you loaded the example gadgets, you should be able to see the "Google Search" gadget on the
Search Results page in VIVO.
</p>
<p>
Every VIVO installation comes with a geographic data model, so type "Chile" in the search box,
and view the results. Near the bottom of the page, you should see the "OpenSocial" section heading,
and beneath it, a gadget offering "Full Text Search Results". This gadget does a google search
at UCSF, using the search term that you entered. Again, this gadget is just an example, to show
what is possible with OpenSocial gadgets and VIVO.
</p>
<p>
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 much faster.
</p>
<h4>Profile page</h4>
<p>
If your VIVO installation contains profiles of people, you can see several gadgets on their
profile pages. You must be logged in to VIVO, with authority to edit the profile you are
viewing.
</p>
<p>
Go to a personal profile page in VIVO. If you loaded the example gadgets, you will see
the "OpenSocial" section heading above the property lists, with an assortment of
example gadgets available for experimentation.
</p>
<p>
As with the search page, the first appearance of the gadgets may be slow.
</p>
<h4>Troubleshooting</h4>
<p>
If the gadgets do not appear as you expect, look for these symptoms,
and check for the corresponding possible causes.
</p>
<table>
<tr>
<th>Symptoms</th>
<th>Possible causes</th>
</tr>
<tr>
<td>
<ul>
<li>
The "OpenSocial" heading does not appear on Individual page or in search results.
</li>
<li>
Tomcat log files do not contain errors.
</li>
</ul>
</td>
<td>
<ul>
<li>
VIVO was not re-deployed with <tt>ant deploy</tt> after the OpenSocial
values were set in <em>build.properties</em>
</li>
</ul>
</td>
</tr>
<tr class="odd_row"><td colspan="2"></td></tr>
<tr>
<td>
<ul>
<li>
Gadgets do not appear on Individual page or in search results.
</li>
<li>
Tomcat "localhost" log file contains an error message:
<pre>Unable to load properties: shindigorng.properties</pre>
</li>
</ul>
</td>
<td>
<ul>
<li>Configuration file is not correctly named.</li>
<li>Tomcat's setenv file does not specify the correct CLASSPATH</li>
</ul>
</td>
</tr>
<tr class="odd_row"><td colspan="2"></td></tr>
<tr>
<td>
<ul>
<li>
Dialog box appears in the browser with the message:
"Error 500 reading application data: internalError"
</li>
<li>
Tomcat "catalina" log file contains an error message:
<pre>java.sql.SQLException: Access denied for user</pre>
</li>
</ul>
</td>
<td>
<ul>
<li>
Configuration file contains incorrect value for one or more of these:
<ul>
<li>orng.dbURL</li>
<li>orng.dbUser</li>
<li>orng.dbPassword</li>
</ul>
</li>
</ul>
</td>
</tr>
<tr class="odd_row"><td colspan="2"></td></tr>
<tr>
<td>
<ul>
<li>
"Smoke tests" fail at startup.
<pre>Token key file for Shindig does not exist</pre>
</li>
<li>
Pages that display gadgets "hang" in the browser.
</li>
<li>
Tomcat "localhost" log file contains error messages, including:
<pre>com.google.inject.CreationException: Guice creation errors</pre>
</li>
</ul>
</td>
<td>
<ul>
<li>
<em>OpenSocial.tokenKeyFile</em> is not set in <em>build.properties</em>,
or the file does not exist at the specified location.
</li>
</ul>
</td>
</tr>
<tr class="odd_row"><td colspan="2"></td></tr>
<tr>
<td>
<ul>
<li>
Gadgets do not appear on Individual page or in search results
</li>
<li>
vivo.all.log contains an error message:
<pre>MySQLSyntaxErrorException: Table 'vivo.orng_apps' doesn't exist</pre>
</li>
</ul>
</td>
<td>
<ul>
<li>
MySQL does not contain the shindig tables.
<pre>shindig_orng_tables.sql</pre> was not processed.
</li>
</ul>
</td>
</tr>
<tr class="odd_row"><td colspan="2"></td></tr>
<tr>
<td>
<ul>
<li>
Gadgets do not appear on Individual page or in search results
</li>
<li>
vivo.all.log contains an error message:
<pre>java.net.ConnectException: Connection refused</pre>
</li>
</ul>
</td>
<td>
<ul>
<li>
In <em>build.properties</em>, <em>OpenSocial.tokenService</em> is not set correctly.
</li>
</ul>
</td>
</tr>
<tr class="odd_row"><td colspan="2"></td></tr>
</table>
<h2 id="gadgets">II. Changing the gadget configurations</h2>
<p>
VIVO will look at tables in MySQL to determine what gadgets should be made available,
where they should appear, how big they will be, and much more.
At this time, VIVO doesn't provide a user interface to edit the contents of these tables.
Administrators will need to use a MySQL admin client, or SQL commands, to set these
parameters.
</p>
<p>
The tables are named <em>orng_apps</em> and <em>orng_app_views</em>,
and are described in the following sections.
</p>
<h3 id="orng_apps">II.i The <em>orng_apps</em> database table</h3>
<p>
This table acts as a dictionary of the available gadgets.
It includes the name and ID of the gadget and where the source code is stored on the web.
</p>
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Usage</th>
</tr>
<tr>
<td>appid</td>
<td>int(11)</td>
<td>
Identifies the gadget.
In particular, this will be used to determine which rows in the
<em>orng_app_views</em> table should apply to this gadget.
</td>
</tr>
<tr>
<td>name</td>
<td>varchar(255)</td>
<td>
A user-friendly name for the gadget.
This will be displayed in the gadget's "Title Bar".
</td>
</tr>
<tr>
<td>url</td>
<td>varchar(255)</td>
<td>
The location where the gadget's contents and behavior are defined.
</td>
</tr>
<tr>
<td>PersonFilterID</td>
<td>int(11)</td>
<td>deprecated - usually set to <em>NULL</em></td>
</tr>
<tr>
<td>enabled</td>
<td>tinyint(1)</td>
<td>
If set to 0, this gadget will never be displayed.
If set to 1, it is displayed according to the rules in the <em>orng_app_views</em> table.
</td>
</tr>
<tr>
<td>channels</td>
<td>varchar(255)</td>
<td>Keywords that identify the communication channels between the gadget and VIVO.</td>
</tr>
</table>
<h3 id="orng_app_views">II.ii The <em>orng_app_views</em> database table</h3>
<p>
This table tells how, where, and when to display the gadgets that are described in <em>orng_apps</em>.
Each row in this table is a "view", describing a single gadget and the rules that determine whether
the gadget will be displayed on a particular page.
</p>
<p>
Note: If a gadget is described and enabled in the <em>orng_apps</em> table, but has no records in the
<em>orng_app_views</em> table, the gadget will be displayed without restriction on all ORNG-enabled
pages. This can be helpful when developing a new gadget. To avoid this, either
<ul>
<li>remove the gadget from <em>orng_apps</em>, or </li>
<li>set the <em>enabled</em> flag in <em>orng_apps</em> to <em>0</em>, or</li>
<li>create a rule for the gadget in <em>orng_app_views.</em></li>
</ul>
</p>
<table>
<tr>
<th>Field</th>
<th>Type</th>
<th>Usage</th>
</tr>
<tr>
<td>appid</td>
<td>int(11)</td>
<td>
Determines which gadget in <em>orng_apps</em> is affected by this rule.
</td>
</tr>
<tr>
<td>viewer_req</td>
<td>char(1)</td>
<td>
What requirements must the viewer satisfy in order to see this view?
<ul>
<li>
<em>NULL</em> -- There are no requirements on the viewer.
</li>
<li>
<em>'U'</em> -- The viewer must be logged in to VIVO.
</li>
<li>
<em>'R'</em> -- The viewer must be logged in, and must be registered as a user of this gadget.
</li>
</ul>
</td>
</tr>
<tr>
<td>owner_req</td>
<td>char(1)</td>
<td>
What requirements must the owner of this page satisfy in order to see this view?
<ul>
<li>
<em>NULL</em> -- There are no requirements on the owner of the page.
</li>
<li>
<em>'R'</em> -- The owner of the page must choose to display this gadget to the public.
</li>
<li>
<em>'S'</em> -- The viewer must be the owner of the page being viewed.
</li>
</ul>
</td>
</tr>
<tr>
<td>page</td>
<td>varchar(50)</td>
<td>
What page does this rule apply to?
A single gadget might have several views, but no more than one view per page.
Recognized values are
<ul>
<li>
<em>individual</em> -- The profile page of an individual, when it is not in "edit" mode.
This applies when the viewer is not logged in, or does not have the right to edit the profile page.
</li>
<li>
<em>individual-EDIT-MODE</em> -- The profile page of an individual, when it is in "edit" mode.
This applies when the viewer is logged in as an administrator or other privileged user, or
as the owner of the profile page.
</li>
<li>
<em>search</em> -- The search results page.
</li>
<li>
<em>gadgetDetails</em> -- A page that contains only the selected gadget. This usually occurs when
the user clicks on an icon or a link that expands the gadget to full-page mode.
</li>
</ul>
</td>
</tr>
<tr>
<td>view</td>
<td>varchar(50)</td>
<td>
What is the view-mode of the gadget? These are defined as part of the OpenSocial standards.
<ul>
<li>
<em>profile</em> -- The "standard" view, commonly used on the profile page of an individual
</li>
<li>
<em>small</em> -- The "condensed" view.
</li>
<li>
<em>home</em> -- The view which allows the user to change the gadget's settings.
</li>
<li>
<em>canvas</em> -- The "expanded", commonly used when the gadget is the only thing on a page.
</li>
</ul>
</td>
</tr>
<tr>
<td>closed_width</td>
<td>int(11)</td>
<td>
How wide is the gadget when it is closed? (in pixels)
</td>
</tr>
<tr>
<td>open_width</td>
<td>int(11)</td>
<td>
How wide is the gadget when it is open? (in pixels)
</td>
</tr>
<tr>
<td>start_closed</td>
<td>tinyint(1)</td>
<td>
When the page is first loaded, is the gadget open or closed (1 = closed, 0 = open)
</td>
</tr>
<tr>
<td>chromeId</td>
<td>varchar(50)</td>
<td>
The gadget will be displayed on the page inside a &lt;div&gt; with this id.
Note: the page must contain this &lt;div&gt; and its contents
will be replaced with this gadget (or gadgets).
</td>
</tr>
<tr>
<td>display_order</td>
<td>int(11)</td>
<td>
If more than one gadget has the same chromeId, they will be displayed in order by this field.
</td>
</tr>
</table>
<h2 id="additional">III. Additional Considerations</h2>
<p>
Some things to be aware of when working with OpenSocial gadgets.
</p>
<h3 id="redeploying">III.i. Re-running the deployment script</h2>
<p>
The OpenSocial framework relies on several of the settings in the <em>build.properties</em> and <em>runtime.properties</em> files,
in addition to the ones that are explicitly linked to it.
</p>
<p>
Each time you change the settings in <em>build.properties</em> or <em>runtime.properties</em>, you should re-deploy
the framework with
<pre> ant orng</pre>
</p>
<h3 id="cache">III.ii. Resetting the gadget cache</h2>
<p>
For efficiency, VIVO reads the gadget configuration only when it starts up. VIVO keeps
a copy of the database tables in memory, for efficiency.
</p>
<p>
This means that if you change the gadget configuration in the database tables, you must
either tell VIVO to read the tables again. Direct your browser to
the <tt>orng/clearcache</tt> page within VIVO. For example,
<pre> http://localhost:8080/vivo/orng/clearcache</pre>
VIVO will re-read the gadget configuration, and display the VIVO home page.
</p>
<p>
You can achieve the same effect by restarting VIVO.
</p>
<h3 id="LOD_issues">III.iii. Issues with Linked Open Data</h2>
<p>
<b>TBD</b>
</p>
<h3 id="disabling">III.iv. Disabling the OpenSocial gadgets</h2>
<p>
If you decide not to use OpenSocial gadgets in your VIVO installation,
there are several ways to deactivate them, depending on how firm your decision is,
and how thorough you wish to be.
</p>
<h4>Disable the gadgets</h4>
<p>
You can disable any or all of the installed gadgets
by setting the <em>enabled</em> flag in <em>orng_apps</em> to zero
(see <a href="#orng_apps">section II.i. The <em>orng_apps</em> database table</a>).
</p>
<p>
To make this change take effect, restart Tomcat, or clear the OpenSocial cache
(see <a href="#cache">section III.ii. Resetting the gadget cache</a>).
</p>
<h4>Disable the connection</h4>
<p>
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
VIVO and the OpenSocial service. Do this by removing or commenting
the <em>OpenSocial</em> properties in <em>build.properties</em>
(see <a href="#vivo_settings">section I.iv. Configure VIVO</a>).
</p>
<p>
To make this change take effect, re-deploy VIVO and restart Tomcat.
</p>
<h4>Remove the OpenSocial webapp from Tomcat</h4>
<p>
Disabling the connection, as above, will remove all of the OpenSocial processing
from your VIVO requests. However, you may still see that Tomcat takes longer to
start up, and requires more memory.
</p>
<p>
To remove the OpenSocial webapp from Tomcat,
<ul>
<li>stop Tomcat;</li>
<li>in the <tt>[tomcat]/webapps</tt> directory, delete <tt>shindigorng.war</tt> and the
<tt>shindigorng</tt> sub-directory;</li>
<li>start Tomcat.</li>
</ul>
</p>
<h4>Clean up the remnants</h4>
<p>
To remove all traces of OpenSocial from your VIVO installation, you should take the steps
outlined above, and also:
<ul>
<li>
Remove the <em>orng</em> tables from your MySQL database.
</li>
<li>
Remove the changes to Tomcat by restoring your <em>setenv</em> file to its previous state.
</li>
<li>
Remove the <em>shindig</em> directory and subdirectories from your VIVO home directory.
</li>
</ul>
</p>
<p>
These steps will have no appreciable effect on the operation of VIVO, Tomcat, or MySQL.
However, if these artifacts are not removed they could be a source of puzzlement for
future VIVO maintainers.
</p>
</div>
</body>
</html>

198
doc/upgrade-1.0.txt
View file

@ -1,198 +0,0 @@
-------------------------------------------------------------------------------
Upgrading NIH VIVO
Steps to Upgrade from Release 1 Version 0.9 to Release 1 Version 1.0
This file provides a short description of the steps involved in upgrading your
installation of NIH VIVO from Release 1 Version 0.9 to Release 1 Version 1.0.
This and other documentation can be found at:
http://vivoweb.org/support
Installation:
If you need to do a fresh install, please consult the install.txt in this
directory.
-------------------------------------------------------------------------------
I. Before Performing the Upgrade
II. The Upgrade Process
III. Ontology Changes
-------------------------------------------------------------------------------
I. Before Performing the Upgrade
Please read the bullet points below BEFORE beginning the upgrade.
The upgrade process is similar to the original install process with the following
exceptions:
* DO NOT reinstall MySQL or recreate the MySQL database. Please ensure that
you back-up the MySQL database.
* It is not necessary to add RDF data or reconfigure the Apache HTTP Server.
* First-time login of the administrator account will use the password
previously set, NOT the password in deploy.properties.
* Any image files that have been uploaded into the system will not be disturbed
by the upgrade.
* The first time Apache Tomcat starts up after the upgrade, it will
initiate a process that modifies the knowledge base to align the data
with the revised ontology. See the section on "Ontology Changes"
below for more information.
-------------------------------------------------------------------------------
II. The Upgrade Process
1. Ensure that backups are created of the Tomcat webapps directory, the
original source directory, and the MySQL database.
2. Download the new distribution file and unpack it into a new source directory.
3. Create deploy.properties, using the same values as in your original
installation. Be aware that deploy.properties now requires an additional
property:
vitro.core.dir = ./vitro-core
The file example.deploy.properties has been modified to show this.
4. Apply any changes you have made to the new source directory.
Note: 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.
Note: At a minimum it will be necessary to apply the Google Analytics Tracking
code to footer.jsp in the theme:
[new_source_directory]/themes/[theme_dir]/jsp/footer.jsp
For additional information and a copy your institution's tracking code,
see the Google Analytics wiki page.
https://confluence.cornell.edu/display/ennsrd/Google+Analytics+for+UI
Note: Version 1 Release 0.9 contained two directories called "modifications"
and "ontology". These directories have been combined into a directory
called "productMods". If your site has made changes to the ontology
ensure that those changes are moved into the appropriate subdirectory of
"productMods".
Note: This process assumes any changes made to the application were made in
the source directory and deployed, and were not made directly within
Apache Tomcat webapp.
5. If you had modified web.xml to configure the Pellet Reasoner (as described
in the installation instructions), repeat that modification.
6. Stop "Apache Tomcat" and run ant deploy by typing: ant deploy
7. If you have setup the Apache Tomcat Connector using mod_jk and modified your
tomcat/conf/server.xml file, you will need to add 4 lines to your context
section, see examples below.
Context section before:
<Context path=""
docBase="/usr/local/tomcat/webapps/vivo"
reloadable="true"
cookies="true" >
</Context>
Context section after:
<Context path=""
docBase="/usr/local/tomcat/webapps/vivo"
reloadable="true"
cookies="true" >
<Environment type="java.lang.String" override="false"
name="path.configuration"
value="deploy.properties"
/>
</Context>
Also, if you have these 3 lines in your Apache virtual host configuration,
please remove them!
<Location "/edit/forms">
deny from all
<Location>
8. Start "Apache Tomcat" and login to VIVO.
9. Rebuild the Lucene search index as described in step IX of
the install process. This step will ensure that changes in the RDF
data to align with the latest version of the core ontology
will be reflected in the search index.
-------------------------------------------------------------------------------
III. Ontology Changes
Changes to the VIVO core ontology may require corresponding
modifications of the knowledge base instance data and local ontology
extensions.
When Apache Tomcat starts up following the upgrade, it will initiate
a process to examine the knowledge base and apply necessary changes.
Not all of the modifications that may be required can be automated,
so manual review of the knowledge base is recommended after the
automated upgrade process. The automated process will make only
the following types of changes:
Class or Property renaming
All references to the class (in the subject or object position) will
be updated to the new name. References to the property will be
updated to the new name.
Class or Property deletion
All individuals in a deleted class will be changed to
belong to the nearest available superclass (which may be owl:Thing).
All statements using a deleted property will be changed
to use the nearest available superproperty. If there is no available
superproperty then the statement will be deleted from the
knowledge base. Note that all removed and added data
is recorded in the files in the changedData directory.
Class or Property addition
If a newly added class has a superclass and there are
individuals in that superclass, then a note will be
added to the log file suggesting review of those individuals to
see if they should be reasserted in the newly added class.
If a newly added property has a superproperty and there are
statements using the superproperty, then a note will be added to
the log file suggesting review of those statements to see if they
should be reasserted using the newly added property.
Annotation property default values
It 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.
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.
The ontology alignment process will create the following files in the
Tomcat webapps/vivo/WEB-INF directory:
ontologies/update/logs/knowledgeBaseUpdate.log
a log of a summary of updates that were made to the knowledge base and notes
about some recommended manual reviews. This file should end with
"Successfully finished processing ontology changes".
ontologies/update/logs/knowledgeBaseUpdate.error.log
a log of errors that were encountered during the upgrade process. This file
should be empty if the upgrade was successful.
ontologies/update/changedData/removedData.n3
an N3 file containing all the statements that were removed from the knowledge base.
ontologies/update/changedData/addedData.n3
an N3 file containing all the statements that were added to the knowledge base.
After Apache Tomcat is started, these files should be reviewed to verify that
the automated upgrade process was executed successfully.

136
doc/upgrade-1.1.1.txt
View file

@ -1,136 +0,0 @@
-------------------------------------------------------------------------------
Upgrading VIVO
Steps to Upgrade from Release 1 Version 1.1 to Release 1 Version 1.1.1
This file provides a short description of the steps involved in upgrading your
installation of VIVO from Release 1 Version 1.1 to Release 1 Version 1.1.1.
For upgrades from V1.0 to V1.1.1 please see the upgrade-1.1.txt file.
This and other documentation can be found at:
http://vivoweb.org/support
Installation:
If you need to do a fresh install, please consult the install.txt in this
directory.
-------------------------------------------------------------------------------
I. Before Performing the Upgrade
II. The Upgrade Process
III. Ontology
IV. File Storage System
V. Theme Changes
-------------------------------------------------------------------------------
I. Before Performing the Upgrade
Please read the bullet points below BEFORE beginning the upgrade.
The upgrade process is similar to the original install process with the following
exceptions:
* DO NOT reinstall MySQL or recreate the MySQL database. Please ensure that
you back-up the MySQL database.
* It is not necessary to add RDF data.
* First-time login of the administrator 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.
-------------------------------------------------------------------------------
II. The Upgrade Process
1. Ensure that backups are created of the Tomcat webapps directory, the
original source directory, the MySQL database, and the uploaded files
directory (images).
2. Download the new distribution file and unpack it into a new source
directory.
3. Create deploy.properties, using the same values as in your previous
installation.
4. Apply any previous changes you have made to the new source directory.
************* Special notes regarding source files ********************
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.
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.
For NIH-funded institutions:
At a minimum it will be necessary to apply the Google Analytics Tracking
Code (GATC) to googleAnalytics.ftl in the theme:
[new_source_directory]/themes/[theme_dir]/templates/googleAnalytics.ftl
A sample googleAnalytics.ftl 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 your institution's tracking code, see the
VIVO Google Analytics wiki page:
https://confluence.cornell.edu/display/ennsrd/Google+Analytics+for+UI
************************************************************************
5. If you had modified web.xml to configure the Pellet Reasoner (as described
in the installation instructions), repeat that modification.
6. Stop "Apache Tomcat" and run ant by typing: ant all
7. If you have set up the Apache Tomcat Connector using mod_jk and modified
your tomcat/conf/server.xml file, there are no changes in this upgrade.
For upgrades from V1.0 to V1.1.1, please see the upgrade-1.1.txt file.
8. 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 /etc/security/limits.conf:
apache hard nproc 400
tomcat6 hard nproc 1500
9. Start "Apache Tomcat" and log in to VIVO.
-------------------------------------------------------------------------------
III. Ontology Changes
There are some minor changes to the ontology with the V1.1.1 upgrade, but there
is no data migration occurring. For upgrades from V1.0 to V1.1.1, please see the
upgrade-1.1.txt file.
-------------------------------------------------------------------------------
IV. File Storage System
There are no changes to the file storage system with the upgrade from V1.1
to V1.1.1. For changes related to upgrading from V1.0 to V1.1.1,
please see the upgrade-1.1.txt file.
-------------------------------------------------------------------------------
V. Theme Changes
Follow step A or B below, whichever is applicable to your site:
A. If you did not create a customized theme for your site in VIVO 1.0, but used
the 1.0 vivo-basic theme in its original directory, you need not take any
action in order to convert your site to the VIVO 1.1 theme.
B. If you created your own theme directory in VIVO 1.1, you can copy it back
into the theme directory location: /vivo/themes/*
If you are upgrading from V1.0 to V1.1.1, please see the upgrade-1.1.txt file.

371
doc/upgrade-1.1.txt
View file

@ -1,371 +0,0 @@
-------------------------------------------------------------------------------
Upgrading VIVO
Steps to Upgrade from Release 1 Version 1.0 to Release 1 Version 1.1
This file provides a short description of the steps involved in upgrading your
installation of VIVO from Release 1 Version 1.0 to Release 1 Version 1.1.
This and other documentation can be found at:
http://vivoweb.org/support
Installation:
If you need to do a fresh install, please consult the install.txt in this
directory.
-------------------------------------------------------------------------------
I. Before Performing the Upgrade
II. The Upgrade Process
III. Ontology Upgrade
A. Verify Ontology upgrade process
B. Ontology knowledge base manual r
IV. New File Storage System
A. Verifying the File Storage upgrade
B. File Storage changes
V. Theme Changes
-------------------------------------------------------------------------------
I. Before Performing the Upgrade
Please read the bullet points below BEFORE beginning the upgrade.
The upgrade process is similar to the original install process with the following
exceptions:
* DO NOT reinstall MySQL or recreate the MySQL database. Please ensure that
you back-up the MySQL database.
* It is not necessary to add RDF data.
* First-time login of the administrator 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.
* The first time Apache Tomcat starts up after the upgrade, it will
initiate a process that modifies the knowledge base to align the data
with the revised ontology. See the section on "Ontology Upgrade"
below for more information.
* The first time Apache Tomcat starts up after the upgrade, it will
initiate a process that modifies the uploaded files directory (images), to
align the uploaded files with the revised file storage scheme. See the
section on "File Storage Changes" below for more information.
-------------------------------------------------------------------------------
II. The Upgrade Process
1. Ensure that backups are created of the Tomcat webapps directory, the
original source directory, the MySQL database, and the uploaded files
directory (images).
2. Download the new distribution file and unpack it into a new source
directory.
3. Create deploy.properties, using the same values as in your previous
installation.
4. Apply any previous changes you have made to the new source directory.
************* Special notes regarding source files ********************
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.
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.
At a minimum it will be necessary to apply the Google Analytics Tracking
Code (GATC) to googleAnalytics.ftl in the theme:
[new_source_directory]/themes/[theme_dir]/templates/googleAnalytics.ftl
A sample googleAnalytics.ftl 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 your institution's tracking code, see the
VIVO Google Analytics wiki page:
https://confluence.cornell.edu/display/ennsrd/Google+Analytics+for+UI
************************************************************************
5. If you had modified web.xml to configure the Pellet Reasoner (as described
in the installation instructions), repeat that modification.
6. Stop "Apache Tomcat" and run ant by typing: ant all
7. If you have set up the Apache Tomcat Connector using mod_jk and modified
your tomcat/conf/server.xml file, you will need to add a line to your
context section specifying a "Manager" tag; see examples below.
Context section before:
<Context path=""
docBase="/usr/local/tomcat/webapps/vivo"
reloadable="true"
cookies="true" >
<Environment type="java.lang.String" override="false"
name="path.configuration"
value="deploy.properties"
/>
</Context>
Context section after:
<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>
8. Start "Apache Tomcat" and log in to VIVO.
-------------------------------------------------------------------------------
III. Ontology Changes
A. Verify Ontology upgrade process
After Apache Tomcat is started, these files should be reviewed to verify that
the automated upgrade process was executed successfully. The ontology alignment
process will create the following files in the Tomcat webapps/vivo/WEB-INF directory:
ontologies/update/logs/knowledgeBaseUpdate.log
A log of a summary of updates that were made to the knowledge base and notes
about some recommended manual reviews. This file should end with
"Successfully finished processing ontology changes".
ontologies/update/logs/knowledgeBaseUpdate.error.log
A log of errors that were encountered during the upgrade process. This file
should be empty if the upgrade was successful.
ontologies/update/changedData/removedData.n3
An N3 file containing all the statements that were removed from the knowledge base.
ontologies/update/changedData/addedData.n3
An N3 file containing all the statements that were added to the knowledge base.
B. Ontology knowledge base manual review
Changes to the VIVO core ontology may require corresponding
modifications of the knowledge base instance data and local ontology
extensions.
When Apache Tomcat starts up following the upgrade, it will initiate
a process to examine the knowledge base and apply necessary changes.
Not all of the modifications that may be required can be automated,
so manual review of the knowledge base is recommended after the
automated upgrade process. The automated process will make only
the following types of changes:
Class or Property renaming
All references to the class (in the subject or object position) will
be updated to the new name. References to the property will be
updated to the new name.
Class or Property deletion
All individuals in a deleted class will be changed to
belong to the nearest available superclass (which may be owl:Thing).
All statements using a deleted property will be changed
to use the nearest available superproperty. If there is no available
superproperty then the statement will be deleted from the
knowledge base. Note that all removed and added data
is recorded in the files in the changedData directory.
Class or Property addition
If a newly added class has a superclass and there are
individuals in that superclass, then a note will be
added to the log file suggesting review of those individuals to
see if they should be reasserted in the newly added class.
If a newly added property has a superproperty and there are
statements using the superproperty, then a note will be added to
the log file suggesting review of those statements to see if they
should be reasserted using the newly added property.
Annotation property default values
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.
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.
-------------------------------------------------------------------------------
IV. New File Storage System
A. Verifying the File Storage upgrade
If the File Storage upgrade process is not successful, no uploaded images will
be displayed for individuals. Tomcat's "vivo.all.log" log file will contain
an exception listing with more information.
The File Storage upgrade process will create these files in the VIVO upload
directory:
upgrade/upgradeLog.2010-00-00T00-00-00.txt
A log of the upgrade process. The actual filename includes a timestamp
that tells when the upgrade executed. This file should be inspected
for warnings or errors. The file should end with "File Storage update
is complete."
upgrade/translatedImages
Contains the images that were translated to the new file storage system.
upgrade/unreferencedImages
Contains the images which were in the "images" directory, but were no
longer referred to by any Individual.
file_storage_root
A directory where the uploaded images are stored. Within the root, the
path to the image is derived from its unique ID and its filename.
file_storage_namespaces.properties
Contains the URL prefix used when serving the image files.
B. File Storage changes
Changes to the File Storage system in VIVO result in new properties to describe
the relationships involving files, and a new directory structure in which to
store the files.
Uploaded files are stored in the VIVO upload directory, as defined in the
deploy.properties file. Previously, images were stored in the "images" folder
of the upload directory. Now, all uploaded files will be stored in the
"file_storage_root" folder of the upload directory.
Previously, image files were served from the images directory within the web
application, within Tomcat, and copied to the upload directory for backup
purposes. Now, image files are stored only in the upload directory, and served
directly from there. The image directory within the web application is no
longer used.
When Apache Tomcat starts up following the upgrade, it will initiate a process
which makes the required changes:
Initializing the file storage system
Each file will now be assigned a unique ID, in addition to its filename.
Both the ID and filename are used to store the file within the system.
Uploading two images with identical filenames will not cause a conflict.
Pruning dead image references
Previous versions allowed manual editing of file paths, sometimes resulting
in erroneous information. Any image properties that refer to non-existent
files will be removed.
Removing unreferenced images
Any uploaded image which is no longer referred to by an Individual will
be removed.
Generating main images and/or thumbnails
Each image will be represented by both a main image file and a
thumbnail image file. If either of these is missing for a particular
individual, it will be created.
Converting image properties on Individuals
Image properties previously were simple data properties, referring to
the filename and path. These are replaced by object properties, which
refer to the file by its unique ID.
Translating images into the new directory structure
Each image file will be copied to its new location in the upload
directory.
Cleaning the old image directory
All image files are removed from their old locations in the upload
directory.
Once you are satisfied that the File Storage upgrade process is successful,
you may delete the "images" folder and the "upgrade" folder from the upload
directory. You may also delete the WEB-INF/images directory from within
your Tomcat web application.
-------------------------------------------------------------------------------
V. Theme Changes
VIVO 1.1 introduces the first step in a transition from JavaServer Pages (JSPs)
to the FreeMarker template engine for generating web pages. As part of this
process, the JSP files that were used for theme customization in earlier
versions of VIVO have been replaced by a set of FreeMarker templates.
In the 1.1 install package, these files are located in
/vivo/themes/vivo-basic/templates and have an ftl (for FreeMarker Template
Language) extension.
Follow step A or B below, whichever is applicable to your site:
A. If you did not create a customized theme for your site in VIVO 1.0, but used
the 1.0 vivo-basic theme in its original directory, you need not take any
action in order to convert your site to the VIVO 1.1 theme.
B. If you created your own theme directory in VIVO 1.0, follow the steps below
under sections "Templates," "Stylesheets," and "Site Icons" to upgrade your
theme to VIVO 1.1.
1. Templates
a. Copy the directory /vivo/themes/vivo-basic/templates into your theme
directory /vivo/themes/<your-theme-name>.
b. Follow step i or ii below, whichever is applicable to your theme.
i. If you did not apply any customizations to the JSPs in your VIVO
1.0 theme, then you do not need to apply any additional changes
to the VIVO 1.1 theme templates during the upgrade process.
ii. If you did apply customizations to the JSPs in your VIVO 1.0
theme,you will need to hand-replicate those modifications in the
new theme template files.
The theme template content that was previously contained in
three JSP files is now contained in five FTL files. The
correspondence between the 1.0 JSPs and the 1.1 FTLs is as
follows:
identity.jsp => identity.ftl
menu.jsp => menu.ftl and search.ftl
footer.jsp => footer.ftl and googleAnalytics.ftl
googleAnalytics.ftl is a new file to which you will add
your site's Google Analytics Tracking Code (see section II).
Because the FreeMarker Template Language uses many syntactic
conventions that will be familiar to template authors from JSP
or other common templating systems, the translation of your JSP
changes into the new FTLs should be relatively straightforward.
Consult the FreeMarker Template Author's Guide at
http://freemarker.org/docs/dgui.html and the Reference at
http://freemarker.org/docs/ref.html for complete documentation
of the syntax and available built-in constructs. Template
authors need not be concerned with the Programmer's Guide or
Java API documentation.
c. Remove the jsp directory from your themes directory.
2. Stylesheets
VIVO 1.1 includes changes to vivo-basic stylesheets. If you modified
styles in your VIVO 1.0 theme, you will not be able to simply copy the
1.0 stylesheets into your 1.1 theme, because you will then lose 1.1
style upgrades that your theme should pick up. Instead, you should
use the vivo-basic 1.1 stylesheets as a starting point, and manually
merge your 1.0 style modifications in as needed.
3. Site Icons
Copy the site icons from your 1.0 theme into the site_icons folder in
your 1.1 theme.

895
doc/upgrade-1.2.html
View file

@ -1,895 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>VIVO Release 1 V1.2 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.2 Upgrade Guide</h1>
<small>
February 16, 2011 - Upgrading from Release 1 v1.1 to Release 1
v1.2
</small>
<toc>
<ul>
<li>
<a href="#announcement">Release announcement for V1.2</a>
</li>
<li>
<a href="#upgrade">Upgrade process for V1.2</a>
</li>
</ul>
</toc>
<p>
This document provides a short description of the steps involved in
upgrading your installation of VIVO from Release 1, Version 1.1 to
Version 1.2. 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 1 v1.2
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>
<!-- Release Announcement --><h2 id="announcement">Release anouncement for V1.2</h2>
<p>
The VIVO 1.2 release incorporates major changes throughout the application -
notably a new templating system to support more versatile page rendering, plus
improvements to address scalability. The release also features a new personal
visualization option covering grants as well as publications. The VIVO Harvester
library has also been significantly improved and expanded in scope for its 1.0
release through the VIVO SourceForge project at
<a href="http://sourceforge.net/projects/vivo">http://sourceforge.net/projects/vivo</a>.
</p>
<h4>Templating system for page generation, navigation, and theming</h4>
<p>
A fresh installation of VIVO 1.2 looks strikingly different, with the introduction
of a new default theme which takes advantage of the navigation and browse features
delivered by the templating system. Individual pages now offer inline navigation to
streamline viewing of expanded personal and organizational profiles, as well as
improved content layout and organization. New browse controls on the home page and
menu pages help to provide an immediate overview of the size and range of content
and quick access down to the individual person, organization, research feature, or
event.
</p>
<h4>Storage model</h4>
<p>
While server memory capacity has increased significantly in recent years, VIVO's reliance
on in-memory caching of RDF data had put limits on the ultimate scalability of VIVO instances
and potentially increased the cost of servers required to support VIVO.
</p>
<p>
With version 1.2, VIVO has been converted to optionally use Jena's SPARQL database (SDB)
subsystem. SDB significantly reduces the baseline memory footprint, allowing VIVO installations
to scale well beyond what has previously been possible.
</p>
<h4>New visualizations</h4>
<p>
Visualizations of networks of co-authors are now complemented by visualizations of co-investigators
on grants, with similar interactivity and options for export as images or data.
</p>
<h4>Ontology</h4>
<p>
VIVO 1.2 includes a new ontology module representing research
resources including biological specimens, human studies, instruments,
organisms, protocols, reagents, and research opportunities. This module
is aligned with the top-level ontology classes and properties from the
NIH-funded <a href="https://www.eagle-i.org/home/">eagle-i Project</a>.
</p>
<h3>Associated VIVO releases</h3>
<h4>VIVO Harvester</h4>
<p>
The Harvester development team is releasing version 1.0 of the VIVO Harvester library shortly
following the release of VIVO 1.2. The Harvester is an extensible data ingest and updating
framework with sample configurations for loading PubMed publication, grants, and human resources
data. Pre-release versions of the Harvester are available at
<a href="http://sourceforge.net/projects/vivo">http://sourceforge.net/projects/vivo</a>.
</p>
<hr><!-- Page break --><!-- Upgrade process for V1.2 --><h2 id="upgrade">Upgrade process for V1.2</h2>
<toc>
<ol class="roman1">
<li>
<a href="#preparation">Before Performing the Upgrade</a>
</li>
<li>
<a href="#triple_store">Chose Triple Store</a>
</li>
<li>
<a href="#upgrade_process">The Upgrade Process</a>
</li>
<li>
<a href="#ontology">Ontology Changes</a>
<ol class="roman2">
<li>
<a href="#verify_ontology_upgrade">Verify Ontology upgrade
process</a>
</li>
<li>
<a href="#ontology_knowledge_base">Ontology knowledge base
manual review</a>
</li>
</ol>
</li>
<li>
<a href="#fileSystem">File Storage System Upgrade</a>
<ol class="roman2">
<li>
<a href="#changes_to_storage">Changes to the File
Storage System</a>
</li>
<li>
<a href="#verify_file_upgrade">Verify File Storage
System upgrade process</a>
</li>
</ol>
</li>
<li>
<a href="#theme">Theme Changes</a>
</li>
<li>
<a href="#setup_sdb">Set Up SDB Store in the Background (Optional)</a>
</li>
</ol>
</toc>
<h3 id="preparation">I. Before Performing the Upgrade</h3>
<p>
Please ensure that backups are created of the:
</p>
<ul style="list-style-type: square;">
<li>
Tomcat webapps directory
</li>
<li>
Original source directory
</li>
<li>
MySQL database (mysqldump)
</li>
</ul>
<p>
The upgrade process is similar to the original install process with
the following EXCEPTIONS:
</p>
<ul>
<li>
DO NOT reinstall MySQL or recreate the MySQL database. Please
ensure that you back-up the MySQL database. Also note that VIVO 1.2 will
not run on older versions of MySQL that may have worked with 1.1.1.
Be sure to run VIVO 1.2 with MySQL 5.1 or higher. Using unsupported
versions may result in strange error messages related to table formatting or
other unexpected problems.
</li>
<li>
It is not necessary to add RDF data.
</li>
<li>
First-time login of the administrator 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, it
will initiate a process that modifies the knowledge base to align the
data with the revised ontology. See the section on the <a href="#ontology">Ontology Upgrade</a>
below for more information.
</li>
</ul>
<h3 id="triple_store">II. Choose Triple Store</h3>
<p>
VIVO 1.2 offers a choice of two triple store technologies: in-memory models backed by
Jena's legacy relational database store (RDB), and Jena's SPARQL database (SDB). RDB was
used by VIVO 1.1.1 and earlier. This mode offers fast response, but only by caching the
entire RDF model in the server's main memory. The memory available to VIVO limits the
number of RDF statements that may be stored.
</p>
<p>
SDB mode caches only a fraction of the RDF data in memory. Most queries are issued directly
against the underlying database. This allows VIVO installations to display data from large
RDF models while requiring only a small amount of server memory to run the application.
There is a tradeoff in response time: pages make take slightly longer to load in SDB mode,
and performance will depend on the configuration parameters of the database server.
Additionally, advanced OWL reasoning (not enabled by default in either mode) is not possible
in SDB mode. With SDB, only the default set of inferences (inferred rdf:type statements) are
generated, though they are generated as soon as data is edited rather than in a background process.
</p>
<p>
Though a VIVO installation may be switched back and forth between RDB and SDB mode by changing
a configuration property and redeploying the application, it is important to note that data
added in one mode will not typically appear in the other. The exception is when a system is
first switched from RDB mode to SDB mode. In this case, the data from the RDB store will be
automatically migrated to SDB.
</p>
<p>
A VIVO 1.2 system that is upgraded from VIVO 1.1.1 must initially be run in RDB mode in order
to receive required ontology updates. Attempting to run an upgraded system initially in SDB will
result in a logged error message, and the application will not start. After the system starts
up successfully the first time in RDB mode, it may then be switched to SDB, redeployed, and restarted.
Upon restart, the data in the RDB store will be copied to the SDB store.
</p>
<p>
This copying process can take a number of hours to complete if the installation contains a large
amount of RDF data (roughly a million triples or more). See section <a href="#setup_sdb">Set Up SDB Store in the Background (Optional)</a>
for instructions on how
to run this lengthy conversion process in the background while an RDB system is operating.
Doing this will reduce the time necessary to start VIVO the first time it is run in SDB mode.
</p>
<h3 id="upgrade_process">III. The Upgrade Process</h3>
<p>
1. Download the new distribution file and unpack it into a new
source directory.
</p>
<p>
2. Create deploy.properties, using the same values as in your
previous installation and set values for the new variables. The
following table shows the default properties for deploy.properties with
new V1.2 properties in <span class="blue">blue</span>.<!-- deploy.properties table from install.html -->
</p>
<table>
<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/"<h4>* The namespace must end with "individual/" (including the
trailing slash).</h4>
</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 (It is not uncommon for this
setting to point elsewhere in development environments).
</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.
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>
upload.directory
</td>
<td>
/usr/local/vivo/data/uploads
</td>
</tr>
<tr>
<td colspan="2">
Directory where the Lucene search index will be
built. 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>
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 the URL 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 blue">
<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 blue">
<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 blue">
<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 blue">
<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 <code>webapp/lib</code>
directory within the vitro.core.dir specified above.
</td>
</tr>
<tr class="odd_row blue">
<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 blue">
<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 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.&nbsp; For example, to use the netID
at Cornell University as the property:
<br>
<span style="font-style: italic;">seflEditing.idMatchingProperty
=
http://vivo.cornell.edu/ns/hr/0.9/hr.owl#netId</span>
</td>
</tr>
<tr class="odd_row blue">
<td>
selfEditing.idMatchingProperty
</td>
<td>
http://vivo.mydomain.edu/ns#networkId
</td>
</tr>
<tr>
<td colspan="2">
The temporal graph visualization can require extensive machine resources.
This can have a particularly noticable impact on memory usage if
<ul>
<li>
VIVO is configured to use Jena SDB,
</li>
<li>
The organization tree is deep,
</li>
<li>
The number of grants and publications is large.
</li>
</ul>
The VIVO developers are working to make this visualization more efficient.
In the meantime, VIVO release 1.2 guards against this impact by disabling
the temporal graph visualization unless the "visualization.temporal" flag
is set to "enabled". To enable it, uncomment the line for this setting.
</td>
</tr>
<tr class="odd_row blue">
<td>
visualization.temporal
</td>
<td>
enabled
</td>
</tr>
<tr>
<td colspan="2">
The temporal graph visualization is used to
compare different
organizations/people within an organization on parameters like number
of publications or grants. By default, the app will attempt to make its
best guess at the top level organization in your instance. If you're
unhappy with this selection, uncomment out the property below and set
it to the URI of the organization individual you want to identify as
the top level organization. It will be used as the default whenever the
temporal graph visualization is rendered without being passed an
explicit org. For example, to use "Ponce School of Medicine" as the top
organization:
<br>
<span style="font-style: italic;">visualization.topLevelOrg =
http://vivo.psm.edu/individual/n2862</span>
</td>
</tr>
<tr class="odd_row blue">
<td>
visualization.topLevelOrg
</td>
<td>
http://vivo-trunk.indiana.edu/individual/topLevelOrgURI
</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>
<li>
If you had used the <code>vivo/contrib/FLShibboleth</code>
code in your previous release, you should stop using it. Consult <code>install.html</code>
or <a href="VIVO_Release-1-v1.2_Installation_Guide.pdf">VIVO Release 1
v1.2 Installation Guide</a>
on "Using an External Authentication System
with VIVO".
</li>
</ul>
</blockquote>
<p>
4. If you had modified <code>web.xml</code>
to configure the Pellet Reasoner (as described
in the installation instructions), repeat that modification.
</p>
<p>
5. Stop Apache Tomcat and run ant by typing: <code>ant all</code>
</p>
<p>
6. Start Apache Tomcat and log in to VIVO.
</p>
<h3 id="ontology">IV. Ontology Changes</h3>
<h4 id="verify_ontology_upgrade">i. Verify Ontology upgrade process</h4>
<p>
After Apache Tomcat is started, these files should be reviewed to
verify that the automated upgrade process was executed
successfully.&nbsp; The ontology alignment process will create the
following files in the Tomcat <code>webapps/vivo/WEB-INF directory</code>:
</p>
<dl>
<dt>
<code>ontologies/update/logs/knowledgeBaseUpdate.log</code>
</dt>
<dd>
A log of a summary of updates that were made to the knowledge base and
notes about some recommended manual reviews. 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.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.
</dd>
</dl>
<dl>
<dt>
<code>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>ontologies/update/changedData/addedData.n3</code>
</dt>
<dd>
An N3 file containing all the statements that were added to the
knowledge base.
</dd>
</dl>
<h4 id="ontology_knowledge_base">ii. Ontology knowledge base manual review</h4>
<p>
Changes to the VIVO core ontology may require corresponding
modifications of the knowledge base instance data and local ontology
extensions.
</p>
<p>
When Apache Tomcat starts up following the upgrade, it will initiate a
process to examine the knowledge base and apply necessary changes. Not
all of the modifications that may be required can be automated, so
manual review of the knowledge base is recommended after the automated
upgrade process. The automated process will make only the following
types of changes:
</p>
<dl>
<dt>
Class or Property renaming
</dt>
<dd>
All references to the class (in the subject or object position) will be
updated to the new name. References to the property will be updated to
the new name.
</dd>
</dl>
<dl>
<dt>
Class or Property deletion
</dt>
<dd>
All individuals in a deleted class will be removed.
<br>
All statements using a deleted property will be changed to use the
nearest available superproperty. If there is no available superproperty
then the statement will be deleted from the knowledge base. Note that
all removed and added data is recorded in the files in the changedData
directory.
</dd>
</dl>
<dl>
<dt>
Property addition
</dt>
<dd>
If a newly added property is the inverse of a previously existing
property, the inverse of any statements using the pre-existing property
will be asserted.
</dd>
</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>
<h3 id="fileSystem">V. File Storage System Upgrade</h3>
<h4 id="changes_to_storage">i. Changes to the File Storage System</h4>
<p>
Each uploaded file exists as an individual in VIVO. When the browser
requests an uploaded file from VIVO, the data model is queried to find
out where the file is actually stored, so it can be downloaded to the
browser.
</p>
<p>
In VIVO 1.2 this storage location, known as the "Alias URL" for
the uploaded file, is stored in the file individual. That way, pages that
contain many files can be displayed much more quickly.
</p>
<p>
When Apache Tomcat starts up after the upgrade,
it will initiate a process to calculate the "Alias URL"
for each existing file and store it in the data model for fast access.
</p>
<h4 id="verify_file_upgrade">ii. Verify File Storage System upgrade process</h4>
<p>
The File Storage upgrade process will create a log file in the
VIVO upload directory. You should review this file to ensure that
this upgrade worked properly.
</p>
<dl>
<dt>
<code>upgrade/FileStorageAliasAdder-log.2011-00-00T00-00-00.txt</code>
</dt>
<dd>
A log of the upgrade process. The actual filename includes a timestamp
that tells when the upgrade executed.
This file should end with<code>Finished adding alias URLs to FileByteStreams.</code>
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>
<h3 id="theme">VI. Theme Changes</h3>
<h4 id="#newTheme">Introducing a New Default Theme</h4>
<p>
VIVO 1.2 includes a new default theme called <strong>wilma</strong>
(located in
/vivo/themes/wilma) which fully supports all 1.2 features. For details on how to
create your own theme using wilma as a starting point, please review the <a href="http://www.vivoweb.org/support/user-guide/administration" title="Download VIVO documentation" target="_blank">Site Administrator's Guide</a>.
</p>
<blockquote id="vivoBasicDeprecated">
<h4>The vivo-basic theme has been deprecated with the 1.2 release and is not
recommended for production instances.</h4>
<p>
Since vivo-basic was the default theme for all previous releases, it is
included as part of VIVO 1.2 to help with the transition of upgrading
existing installations to the latest code, but all vivo-basic development
has ceased and it will not be distributed in future releases.
</p>
<p>
Please note that vivo-basic does not support all of the new 1.2 features.
Most notably, in choosing to use vivo-basic you will be missing out on the
following:
</p>
<ul>
<li>
new primary menu for site navigation (replaces tabs)
</li>
<li>
home page with class group browse and visual graph
</li>
<li>
menu pages with class group and individual browse
</li>
</ul>
</blockquote>
<h4 id="templateTransition">Templates</h4>
<p>
The 1.2 release continues the transition from JavaServer Pages (.jsp) to
Freemarker templates (.ftl) for generating web pages. While there are still
JSP files in action behind the scenes, as of 1.2 all theme templates
are of the Freemarker variety and are located in the "templates" directory
within a theme.
</p>
<p>
If you did not create a custom theme for your site previously, but used
the vivo-basic theme in its original directory, you need not take any
action in order to remain using the vivo-basic theme in 1.2.
</p>
<p>
If you did make changes to the vivo-basic theme, you will need to reapply those changes.
We recommend you apply these changes to the wilma theme.
</p>
<blockquote>
<strong>Please note:</strong>
The vivo-basic theme has been deprecated and is <a href="#vivoBasicDeprecated">not recommended for production instances</a>.
</blockquote>
<p>
For details on the new structure of themes in 1.2 and further information
regarding the development of your own custom theme, please review the <a href="http://www.vivoweb.org/support/user-guide/administration" title="Download VIVO documentation" target="_blank">Site Administrator's Guide</a>. This document will focus on updating an existing
pre 1.2 theme.
</p>
<h3 id="setup_sdb">VII. Set Up SDB Store in the Background (Optional)</h3>
<p>
If your VIVO installation is running in RDB mode, and you'd like to convert
to SDB, you can start the conversion process in the background while the RDB
system is running. This will reduce the delay in initial startup after the
application is redeployed with deploy.properties set for SDB. Note that it
is important not to edit any data anywhere in the application while this
background conversion is running.
</p>
<p>
To start the SDB conversion, log in as a system
administrator and request /sdbsetup (For example, if your VIVO is installed
at http://vivo.myuniversity.edu/ you would type
http://vivo.myuniversity.edu/sdbsetup into your browser).
</p>
<p>
Click the button that appears on this page.
</p>
<p>
During the course of the SDB setup, which may take several hours on a
large database, subsequent requests to /sdbsetup will display a
message that the operation is still in progress. When a request for this
page shows a message that the SDB setup has completed successfully, shut down
Tomcat, set deploy.properties to SDB mode, redeploy, and restart Tomcat.
VIVO will now be running from the SDB store.
</p>
</div>
<!-- end of content -->
<div id="footer" role="contentinfo">
<p class="copyright">
<small>
&copy;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>
<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>
</body>
</html>

1324
doc/upgrade-1.3.html
View file

File diff suppressed because it is too large Load diff

815
doc/upgrade-1.4.html
View file

@ -1,815 +0,0 @@
<!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.4 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.4 Upgrade Guide</h1>
<small>
December 9, 2011 - Upgrading from Release 1 V1.3 to Release 1 V1.4
</small>
<p>
This document contains instructions on how to upgrade your
installation of VIVO from Version 1.3 to Version 1.4.
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.4 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 (there are no new hardware
or software requirements for V1.4).
</p>
<p>
For a description of the release contents see the <a href="./release.html">Release announcement for V1.4</a>.
</p>
<hr/>
<!-- Upgrade process for V1.4 --><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>
<br>
<ol class="roman2">
<li>
<a href="#newproperty">New Property in deploy.properties</a>
</li>
<li>
<a href="#changetoconfig">Change to tomcat configuration</a>
</li>
</ol>
</li>
<li>
<a href="#upgrade_process">Upgrade Instructions</a>
</li>
<li>
<a href="#kbm">Knowledge Base Migration</a>
<ol class="roman3">
<li>
<a href="#verifymigration">Knowledge Base Migration Process</a>
</li>
<li>
<a href="#reviewkbm">Knowledge Base Manual Review for Local Extensions</a>
</li>
</ol>
</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.3)
</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="newproperty">New property in deploy.properties</h4>
<p>
<code>proxy.eligibleTypeList</code> describes which classes of Individuals are
eligible for "self-editing" by proxy.
See the table in <a href="#upgrade_process">Section III</a> for more details.
</p>
</li>
<li>
<h4 id="changetoconfig">Change to Tomcat configuration</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 conf/server.xml and add the following attribute to each of the
Connector elements: URIEncoding="UTF-8".
</p>
<pre>
&lt;Server ...&gt;
&lt;Service ...&gt;
&lt;Connector ... URIEncoding="UTF-8"/&gt;
...
&lt;/Connector&gt;
&lt;/Service&gt;
&lt;/Server&gt;
</pre>
</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. Create a new deploy.properties using the same settings as in
your previous installation and set values for the new variables as described
below (vitro.local.solr.url, vitro.local.solr.ipaddress.mask,
vitro.home.directory, email.smptHost, email.replyTo,
rootUser.emailAddress)
<br>
</p>
<p>
<!-- deploy.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">
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
deployments, this is set to ./vitro-core (It is not uncommon for this
setting to point elsewhere in development environments).
</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">
URL of Solr context used in local VIVO search.
Should consist of:<pre> scheme + servername + port + vivo_webapp_name + "solr"</pre>
In the standard installation, the Solr context will be on the same
server as VIVO, and in the same Tomcat instance. The path will be the
VIVO webapp.name (specified above) + "solr"
</td>
</tr>
<tr class="odd_row">
<td>
vitro.local.solr.url
</td>
<td>
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:0:0:0:0:0: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
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>
vivoAdmin@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 "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 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 VIVO 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 VIVO. 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>
vivoAdmin@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://vivo.mydomain.edu/ns#networkId
</td>
</tr>
<tr>
<td colspan="2">
If an external authentication system like Shibboleth or CUWebAuth is to be
used, these properties say how the login button should be labeled, and which
HTTP header will contain the user ID from the authentication system. If such
a system is not to be used, leave these commented out. Consult the installation
instructions for more details.
</td>
</tr>
<tr class="odd_row">
<td>
externalAuth.buttonText
<br/>
externalAuth.netIdHeaderName
</td>
<td>
Log in using BearCat Shibboleth
<br/>
remote_userID
</td>
</tr>
<tr>
<td colspan="2">
The temporal graph visualization can require
extensive machine resources. This can have a particularly noticable
impact on memory usage if
<ul>
<li>
The organization tree is deep,
</li>
<li>
The number of grants and publications is large.
</li>
</ul>
VIVO V1.4 mitigates this problem by the way of a caching
mechanism and hence we can safely set this to be enabled by default.
</td>
</tr>
<tr class="odd_row">
<td>
visualization.temporal
</td>
<td>
enabled
</td>
</tr>
<tr>
<td colspan="2">
The temporal graph visualization is used to
compare different organizations/people within an organization on
parameters like number of publications or grants. By default, the app
will attempt to make its best guess at the top level organization in
your instance. If you're unhappy with this selection, uncomment out the
property below and set it to the URI of the organization individual you
want to identify as the top level organization. It will be used as the
default whenever the temporal graph visualization is rendered without
being passed an explicit org. For example, to use "Ponce School of
Medicine" as the top organization:
<br>
<code>visualization.topLevelOrg =
http://vivo.psm.edu/individual/n2862</code>
<br>
</td>
</tr>
<tr class="odd_row">
<td>
visualization.topLevelOrg
</td>
<td>
http://vivo-trunk.indiana.edu/individual/topLevelOrgURI
</td>
</tr>
<tr>
<td colspan="2">
An absolute file path, pointing to the root directory of the Harvester utility.
You must include the final slash.
</td>
</tr>
<tr class="odd_row">
<td>
harvester.location
</td>
<td>
/usr/local/vivo/harvester/
</td>
</tr>
<tr>
<td colspan="2">
Types of individual for which we can create proxy editors.
If this is omitted, defaults to http://www.w3.org/2002/07/owl#Thing
</td>
</tr>
<tr class="odd_row blue">
<td>
proxy.eligibleTypeList
</td>
<td>
http://xmlns.com/foaf/0.1/Person, http://xmlns.com/foaf/0.1/Organization
</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.4 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>
<h4 id="kbmprocess">i.Knowledge Base Migration Process</h4>
<p>
For an description of changes to the VIVO ontology in version 1.4 see the <a href="https://sourceforge.net/apps/mediawiki/vivo/index.php?title=Ontology_changes_from_version_1.3_to_1.4">sourceforge wiki page on ontology changes</a>
</p>
<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 will make the following types of changes:
</p>
<dl>
<dt>
Class or Property renaming
</dt>
<dd>
All references to the class (in the subject or object
position) will be updated to the new name. References to the property will be
updated to the new name.
</dd>
</dl>
<dl>
<dt>
Class or Property deletion
</dt>
<dd>
All type assertions of a deleted class will be removed.
<br>
All statements using a deleted property will be changed to use the
nearest available superproperty. If there is no available superproperty
then the statement will be deleted from the knowledge base. Note that
all removed and added data is recorded in the files in the changedData
directory.
</dd>
</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>
<dl>
<dt>
Structural changes
</dt>
<dd>
Changes in the way individuals (intances of classes) are related to other individuals.
</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>
<h4 id="reviewkbm">ii. Knowledge Base Manual Review for Local Extensions</h4>
Not all of the modifications that may be required are
automated. If you have local extensions to areas of the ontology that have changed, a manual review of the knowledge base is recommended after
the automated upgrade process.
<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="http://sourceforge.net/apps/mediawiki/vivo/index.php?title=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>
©2011 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>

403
doc/upgrade-1.5.html
View file

@ -1,403 +0,0 @@
<!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.5 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.5 Upgrade Guide</h1>
<small>
February 15, 2012 - Upgrading from Release 1 V1.4 to Release 1 V1.5
</small>
<p>
This document contains instructions on how to upgrade your
installation of VIVO from Version 1.4 (or 1.4.1) to Version 1.5.
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.5 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.5</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="#upgradeAnt">Ant version 1.8 is required</a></li>
<li><a href="#customShortView">Custom short views</a></li>
<li><a href="#openSocial">Support for OpenSocial gadgets</a></li>
<li><a href="#browsers">Supported Browsers</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.4 or VIVO 1.4.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="upgradeAnt">Ant version 1.8 is required</h4>
<p>
The VIVO build script has been revised, and now requires features from
version 1.8 of Apache Ant. Version 1.8 has been available since February, 2010.
The current version of Apache Ant is 1.8.4.
</p>
<p>
You can find recent versions of Apache Ant at
<a href="http://ant.apache.org">http://ant.apache.org</a>
</p>
</li>
<li>
<h4 id="customSearchView">Custom short views</h4>
<p>
"Custom search views" have been re-implemented as part of the more flexible "Custom short views" mechanism.
If you have implemented custom search views, you will need to re-configure them to fit the new framework.
For an explanation of how to use custom search views, consult the
<a href="http://sourceforge.net/apps/mediawiki/vivo/index.php?title=Using_Short_Views_in_Release_1.5">
SourceForge Wiki page on custom search views
</a>
</p>
</li>
<li>
<h4 id="openSocial">Support for OpenSocial gadgets</h4>
<p>
VIVO can now be configured to support Open Research Networking Gadgets,
an extension of OpenSocial gadgets. For a description of this, and instructions
for configuring VIVO, look at <a href="./setting_up_orng.html">setting_up_orng.html</a>, in this directory.
</p>
</li>
<li>
<h4 id="browsers">Supported Browsers</h4>
<p>
For this release, the following browsers are supported.
</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. Create a new deploy.properties using the same settings as in
your previous installation and set values for the new variables as described
below:
<br>
</p>
<p>
<!-- deploy.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">
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 blue">
<td>
RDFService.languageFilter
</td>
<td>
false
</td>
</tr>
<tr>
<td colspan="2">
These values are used when deploying VIVO as an OpenSocial container
and integrating with OpenSocial gadgets.
For instructions, look at <a href="./setting_up_orng.html">setting_up_orng.html</a>, in this directory.
If you are creating
a VIVO installation that does not use OpenSocial gadgets, these values are omitted.
</td>
</tr>
<tr class="odd_row blue">
<td>
OpenSocial.shindigURL<br>
OpenSocial.tokenService<br>
OpenSocial.tokenKeyFile<br>
OpenSocial.sandbox
</td>
<td>
&nbsp;
</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.5 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.5 will make
the following types of changes:
</p>
<dl>
<dt>
The vivo:ResearchLaboratory class has been removed. All instances of vivo:ResearchLaboratory will be
retyped to its superclass vivo:Laboratory.
</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="http://sourceforge.net/apps/mediawiki/vivo/index.php?title=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>
©2011 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>

919
doc/upgrade-1.6.html
View file

@ -1,919 +0,0 @@
<!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>
October 9, 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="#log4j_properties">Log4J properties file renamed</a></li>
<li><a href="#tabMenu">Property groups now displayed in a tab format</a></li>
<li><a href="#sparqlDataGetters">Class-specific SPARQL Query Data Getters</a></li>
<li><a href="#foafPersonTemplate">The foaf:Person template has been re-located.</a></li>
<li><a href="#multiple">Multiple foaf:Person Profile Pages</a></li>
<li><a href="#homePage">Home Page Re-design</a></li>
<li><a href="#rdffiles">Auto-loaded RDF files move to the Home directory</a></li>
<li><a href="#language">Support for additional languages</a></li>
<li><a href="#extended_lod">More compact responses to Linked data requests</a></li>
<li><a href="#google_refine">Changes to default types for Google Refine</a></li>
<li><a href="#developers">Special runtime settings for developers</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>
If you have used temporary models in the database to stage ingested data,
you will want to clear out any unneeded models that remain listed on the Manage
Jena Models page (under "Ingest tools"). This step is especially important if
these temporary models contain blank nodes, as this may cause unwanted or
duplicate data to appear following the upgrade.
</p>
<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>
When 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>
</li>
<li>
<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>
</li>
<li>
<h4 id="log4j_properties">Log4J properties file renamed</h4>
<p>
In previous releases, the properties file for the VIVO logging system
was called <code>default.log4j.properties</code>. In release 1.6, this
file has been renamed to <code>log4j.properties</code>. This is so the
developers and implementers will know where to look for the file.
</p>
<p>
Note that <code>debug.log4j.properties</code>, if present, will still
override the default.
</p>
</li>
<li>
<h4 id="tabMenu">Property groups now displayed in a tab format, including a "View All" tab</h4>
<p>
With release 1.6, the property group menu bar that was used on profile pages has been replaced
by java script enabled tabs. When clicked, each property group tab will display the properties
within that group while the contents of the previously displayed group will be hidden. The array of
tabs also includes a "View All" tab that, when clicked, displays the contents of all the property groups.
</p>
</li>
<li>
<h4 id="sparqlDataGetters">Class-specific SPARQL Query Data Getters</h4>
<p>
The VIVO software now supports the development of SPARQL query data getters that can be associated
with specific ontological classes. These data getters, in turn, can be accessed within Freemarker
templates to provide richer content on VIVO profile pages. For example, the profile page for an academic
department lists only the names of the faculty within that department and their titles, but with a SPARQL
query data getter it is now possible to extend the faculty information to display all of the faculty
members' research areas. Refer to this wiki page for details on how to use class-specific SPARQL query
data getters:
<code>https://wiki.duraspace.org/display/VIVO/Enriching+VIVO+Content+Using+SPARQL+Query+Data+Getters</code>.
</p>
</li>
<li>
<h4 id="foafPersonTemplate">The foaf:Person template has been re-located.</h4>
<p>
The template individual--foaf-person.ftl has been moved to the "templates" subdirectory in the wilma
theme directory (vivo/themes/wilma/templates). If your installation has a customized version of
individual--foaf-person.ftl, ensure that it is located in the templates subdirectory in your installation's
theme directory or, if your installation does not have it's own theme directory, in the
<code>themes/wilma/templates subdirectory</code>.
</p>
</li>
<li>
<h4 id="multiple">Multiple foaf:Person Profile Pages</h4>
<p>
VIVO now supports multiple profile pages for foaf:Persons. This feature, which is optional so installations
can continue to use just the individual--foaf-person.ftl template, currently consists of two profile page
types: a standard view, which is a redesigned version of the foaf:Person template in previous releases; and
a quick view, which emphasizes the individual's own web page presence while providing summary VIVO information,
such as current positions and research areas. The profile quick view requires the use of a web service that
captures images of web pages. <strong>This web service is not included with the VIVO software.</strong> An
installation will either have to develop their own service or use a third-party service, usually for a small
fee depending on the number of images served. (Examples of these services include WebShotsPro, Thumbalizr and
Websnapr.) For more information on how to implement multiple profile page views, refer to this wiki page:
<code>https://wiki.duraspace.org/display/VIVO/Multiple+foaf%3APerson+Profile+Pages</code>.
</p>
</li>
<li>
<h4 id="homePage">Home Page Re-design</h4>
<p>
For Release 1.6 the VIVO Home Page has been redesigned. The Search field beneath the "welcome" text now
allows the user to limit the results of a search to a specific class group, such as people, organizations,
etc. In addition, the browse-by-class-group display has been removed from the Home Page and replaced by
multiple features, which include: a list of four randomly selected faculty members, including their titles
and thumbnail images; a display of statistical data about the VIVO installation, such as the number of people,
activities and organizations; and, <a href="#optionalMap">optionally</a> a global map showing researchers'
areas of geographic focus.
</p>
</li>
<li>
<h4 id="rdffiles">Auto-loaded RDF files move to the Home directory</h4>
<p>
The RDF files that initialize the data model have moved, in both the distribution and
the runtime locations.
In the distribution, they have been collected in one place, and reorganized to use
a more consistent naming scheme. During the build process, they are copied to a
location within the VIVO home directory, instead of residing in the webapp itself.
</p>
<p>
If you have modified these RDF files, or added files of your own, you must adjust to
the new locations accordingly.
</p>
<table>
<tr>
<th>Old locations of RDF files<br/>under [Vitro]/webapp/web or [VIVO]/productMods</th>
<th>New locations of RDF files<br/>under [Vitro]/webapp/rdf or [VIVO]/rdf</th>
<th>Comments</th>
</tr>
<tr>
<td>WEB-INF/ontologies/app/</td>
<td>rdf/display/firsttime/</td>
<td></td>
</tr>
<tr>
<td>WEB-INF/ontologies/app/loadedAtStartup/</td>
<td>rdf/display/everytime/</td>
<td></td>
</tr>
<tr>
<td>WEB-INF/ontologies/app/menuload/displayTBOX.n3</td>
<td>rdf/displayTbox/everytime/</td>
<td>Was one file, now a directory</td>
</tr>
<tr>
<td>/WEB-INF/ontologies/app/menuload/displayDisplay.n3</td>
<td>rdf/displayDisplay/everytime/</td>
<td>Was one file, now a directory</td>
</tr>
<tr>
<td>WEB-INF/ontologies/user/applicationMetadata/<br/>WEB-INF/init-data/</td>
<td>rdf/applicationMetadata/firsttime/</td>
<td>Merged directories</td>
</tr>
<tr>
<td>WEB-INF/ontologies/user/abox/</td>
<td>rdf/abox/firsttime/</td>
<td></td>
</tr>
<tr>
<td>WEB-INF/filegraph/abox/</td>
<td>rdf/abox/filegraph/</td>
<td></td>
</tr>
<tr>
<td>WEB-INF/ontologies/user/tbox/</td>
<td>rdf/tbox/firsttime/</td>
<td></td>
</tr>
<tr>
<td>WEB-INF/filegraph/tbox/</td>
<td>rdf/tbox/filegraph/</td>
<td></td>
</tr>
</table>
<p>
If you are using a three-tier build process, you will need to add two lines
to the build script to accomodate the RDF files, and the language support (see below)
So this:
<pre>&lt;patternset id="appbase.patterns"&gt;
&lt;include name="src/**/*" /&gt;
&lt;include name="lib/**/*" /&gt;
&lt;include name="test/**/*" /&gt;
&lt;include name="themes/**/*" /&gt;
&lt;include name="config/*.properties" /&gt;
&lt;include name="config/*.txt" /&gt;
&lt;include name="config/jarlist/*.txt" /&gt;
&lt;include name="config/solr/*" /&gt;
&lt;include name="context.xml" /&gt;
&lt;/patternset&gt;</pre>
becomes this:
<pre>&lt;patternset id="appbase.patterns"&gt;
&lt;include name="src/**/*" /&gt;
&lt;include name="lib/**/*" /&gt;
<b>&lt;include name="rdf/**/*" /&gt;
&lt;include name="languages/**/*" /&gt;</b>
&lt;include name="test/**/*" /&gt;
&lt;include name="themes/**/*" /&gt;
&lt;include name="config/*.properties" /&gt;
&lt;include name="config/*.txt" /&gt;
&lt;include name="config/jarlist/*.txt" /&gt;
&lt;include name="config/solr/*" /&gt;
&lt;include name="context.xml" /&gt;
&lt;/patternset&gt;</pre>
</p>
</li>
<li>
<h4 id="language">Support for additional languages</h4>
<p>
VIVO 1.6 includes limited support for other languages, in addition to American English.
This limited support is described as <em>read-only</em> support on <em>public-facing</em>
pages.
</p>
<p>
<em>Read-only</em> means that there is no provision for editing multi-language
data or displays. Property values, ontology labels, etc. must all be provided in RDF files
and ingested or otherwise inserted into the data model. The Page Management user interface
does not support maintaining pages in multiple languages.
</p>
<p>
<em>Public-facing</em> means that most of the pages used for site adminstration
are only presented in American English.
</p>
<p>
These two pages in the VIVO Wiki describe how to
<a href="https://wiki.duraspace.org/display/VIVO/Building+a+multi-language+VIVO+instance">
Build VIVO with multiple languages</a> and how to
<a href="https://wiki.duraspace.org/display/VIVO/Adding+a+language+to+VIVO">
Add a new language to VIVO</a>.
</p>
</li>
<li>
<h4 id="extended_lod">More compact responses to Linked data requests</h4>
<p>
In VIVO 1.6, the response to requests for linked data is changed, to be smaller and faster.
</p>
<p>
When responding to a request for linked data about an individual, VIVO 1.6 returns:
<ul>
<li>Data properties of the individual</li>
<li>Object relationships to and from the individual</li>
<li>The RDF types and RDFS labels for any object that directly relates to the individual</li>
</ul>
This data is filtered by the usual VIVO privacy policies,
so properties such as salary or employee ID number may not be revealed
unless the requester has been properly authenticated.
</p>
<p>
VIVO releases prior to VIVO 1.6 returned a more complex set of statements,
referred to as "extended linked data":
<ul>
<li>Data properties of the individual</li>
<li>Object relationships from the individual</li>
<li>All properties of the context nodes (positions, roles, etc.) that are associated with the individual.</li>
<li>Labels of objects that are joined to the individual through context nodes.</li>
<li>Full details of time intervals that are attached to context nodes: start, end, precision.</li>
</ul>
As above, this data was filtered by the VIVO privacy policies.
Although these additional items were included,
extended linked data was based only on relationships from the individual.
Relationships to the individual were not included.
</p>
<p>
Extended linked data was costly to produce, in terms of resources,
because it required a recursive search of the data model.
Extended linked data typically contained 50% more information than its non-extended equivalent,
and took more than 10 times as long to produce.
</p>
<p>
VIVO release 1.6 can be configured to produce extended linked data like previous releases.
However, extended linked data will not be supported in future releases.
</p>
</li>
<li>
<h4 id="google_refine">Changes to default types for Google Refine</h4>
<p>
The list of default types for Google Refine has changed, to accomodate changes in the
ontology. If you are using Google Refine, you may need to change your runtime properties
accordingly. The new defaults appear in <code>example.runtime.properties</code>.
</p>
</li>
<li>
<h4 id="developers">Special runtime settings for developers</h4>
<p>
This release includes several settings to help developers by instumenting the
freemarker templates and the SPARQL queries on the RDFService. Check the wiki for
details, or look in the home directory in <code>example.developer.properties</code>.
</p>
</li>
<li>
<h4 id="browsers">Supported Browsers</h4>
<p>
For this release, the following browsers are supported.
</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>
</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. Store the new <code>build.properties</code> file in
the top level of the VIVO distribution directory. Store the new <code>runtime.properties</code>
file in your VIVO 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>
<p>
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. Remember, the <code>runtime.properties</code> file
goes into your VIVO home directory.
</p>
<p>
The properties below are new to <code>build.properties</code>. They are optional,
so you need not add them unless you want a value other than the default.
</p>
<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">
Languages (in addition to American English) that will be built into your
VIVO site. The languages must be found in the
<code>languages</code> directory of the VIVO 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 blue">
<td>
languages.addToBuild
</td>
<td>
es_MX
</td>
</tr>
</tbody>
</table>
<p>
The properties below are new to <code>runtime.properties</code>. They are optional,
so you need not add them, unless you want a value other than the default.
</p>
<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">
Tell VIVO 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 blue">
<td>
http.createCacheHeaders
</td>
<td>
true
</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 blue">
<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 blue">
<td>
languages.selectableLocales
</td>
<td>
en, es, fr_FR
</td>
</tr>
<tr>
<td colspan="2" id="optionalMap">
On the VIVO home page, display a global map highlighting the geographical focus
of foaf:person individuals. The default is <code>enabled</code>.
</td>
</tr>
<tr class="odd_row blue">
<td>
homePage.geoFocusMaps
</td>
<td>
enabled
</td>
</tr>
<tr>
<td colspan="2">
<b>MultiViews for foaf:person profile pages.</b>
VIVO supports the simultaneous use of a full foaf:Person profile page view
and a "quick" page view that emphasizes the individual's own webpage presence.
<b>Implementing this feature requires an installation to develop a web service
that captures images of web pages or to use an existing service outside of VIVO,
usually for a small fee.</b>
The default is <code>disabled</code>.
</td>
</tr>
<tr class="odd_row blue">
<td>
MultiViews.profilePageTypes
</td>
<td>
disabled
</td>
</tr>
<tr>
<td colspan="2">
Setting this property causes VIVO 1.6 to produce extended responses to requests
for linked data. This provides compatibility with earlier releases.
The default is <code>false</code>.
<br/>
Extended linked data is costly, in terms of server resource. Typically, extended
linke data contains 50% more information than its non-extended equivalent, and
takes 10 times as long to produce.
<br/>
<b>Extended linked data will not be supported in future releases of VIVO.</b>
</td>
</tr>
<tr class="odd_row blue">
<td>
serveExtendedLinkedData
</td>
<td>
true
</td>
</tr>
</tbody>
</table>
<p>
Note that the property named <code>externalAuth.buttonText</code> is no longer used.
You can specify the text of the external login button by adding a property to
<code>all.properties</code> like this:
<pre>external_login_text = Log in using BearCat Shibboleth</pre>
</p>
<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>
4. Apply any previous changes you have made to the RDF initialization files.
See the section on the <a href="#rdffiles">Auto-loaded RDF files</a>
above for more details.
</p>
<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 the knowledge base migration logs.
The knowledge base migration process described in the next section will create logs
in a subdirectory of the VIVO home directory:
</p>
<dl>
<dt>
<code>(home directory)/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>
<p>
9. Load the About Page .N3 file (optional). Release 1.6 provides an "about VIVO" page that is editable
through the GUI, using the Page Management functionality. If your installation has a customized version
of the About Page and you do not need to have it accessible via Page Management, then skip this step.
Otherwise, here are the instructions for loading the About Page .N3 file:
<ol>
<li>
Once the VIVO application is running, go to the Site Admin page and click the "Ingest Tools"
link under Advanced Data Tools.
</li>
<li>
From the Ingest Menu click the "Manage Jena Tools" link, and then click the "RDB Models" button.
</li>
<li>
Locate the "vitro-kb-displayMetadata" model and click the "load RDF data" button.
</li>
<li>
Click the "Browse" button to upload the file from your computer and select the aboutPage.n3 file
located here in the VIVO source: <code>productMods/WEB-INF/ontologies/app/aboutPage.n3</code>.
</li>
<li>
Select N3 as the file type from the drop-down list and then click the "Load Data" button.
</li>
<li>
Restart tomcat.
</li>
</ol>
</p>
<p>
If your installation has a customized version of the About Page, but you would like to make its content
editable through the GUI, follow the above steps and then use Page Management to update the fixed HTML
content.
</p>
<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.
The first time VIVO 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>
Instance data changes to align with VIVO-ISF
</dt>
<dd>
Obsolete predicates and types in the instance data will be updated where necesary to correspond to the current properties and classes in version 1.6 of the VIVO-ISF ontology. Note that VIVO 1.6 continues to make use of certain deprecated classes and properties that are not incompatible with VIVO-ISF. Most notable among these are the various subclasses of foaf:Person: these types will be unchanged by the VIVO 1.6 data migration, but may be removed in a future release.
</dd>
</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. Note that the
annotation settings for certain obsolete VIVO 1.5 properties will be
preserved in a configuration file that applies settings to particular
object properties based on the types of their subject and object
individuals. This file is found in the VIVO home directory:
<code>(home directory)/rdf/display/everytime/PropertyConfig.n3</code>
<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 in the VIVO home directory:
</p>
<dl>
<dt>
<code>(home directory)/upgrade/knowledgeBase/changedData/removedData.(timestamp).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.(timestamp).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>

56
doc/upgrades.html
View file

@ -1,56 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>Upgrading VIVO</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>
<!-- Start of content -->
<div id="wrapper-content" role="main">
<h1>Upgrading VIVO</h1>
<div>
February 15, 2012
</div>
<p>
The following documents describe how to upgrade VIVO.
</p>
<ul>
<li><a href="upgrade-1.0.txt">upgrade-1.0.txt</a></li>
<li><a href="upgrade-1.1.1.txt">upgrade-1.1.1.txt</a></li>
<li><a href="upgrade-1.1.txt">upgrade-1.1.txt</a></li>
<li><a href="upgrade-1.2.html">upgrade-1.2.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.5.html">upgrade-1.5.html</a></li>
<li><a href="upgrade-1.6.html">upgrade-1.6.html</a></li>
</ul>
</div>
<!-- #wrapper-content -->
<div id="footer" role="contentinfo">
<p class="copyright">
<small>
All Rights Reserved <a href="license.txt">see license</a>
</small>
</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>
</body>
</html>

62
example.build.properties
View file

@ -9,38 +9,48 @@
# #
# ----------------------------------------------------------------------------- # -----------------------------------------------------------------------------
#
# Where is the Vitro core directory? # -----------------------------------------------------------------------------
# In most deployments, this is set to ./vitro-core (It is not uncommon for this # BASIC PROPERTIES
# setting to point elsewhere in development environments). # -----------------------------------------------------------------------------
# Examples:
# vitro.core.dir = ./vitro-core #
# vitro.core.dir = ../vitro # Where is the Vitro core directory?
# vitro.core.dir = /usr/local/vitro/trunk # 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 vitro.core.dir = ./vitro-core
# #
# The base install directory for your Tomcat server. The VIVO application # The base install directory for your Tomcat server. The VIVO application
# will be deployed in the /webapps directory below this base. # will be deployed in the /webapps directory below this base.
# #
tomcat.home = /usr/local/tomcat tomcat.home = /usr/local/tomcat
# #
# The name of the VIVO application. This will be used as the name of the # 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 # subdirectory within your Tomcat server's /webapps directory. It also appears
# in the URL for the application. For example, http://my.vivo.server/vivo # in the URL for the application. For example, http://my.vivo.server/vivo
# #
webapp.name = vivo webapp.name = vivo
# #
# The location where the VIVO application will store the data that it creates. # The location where the VIVO application will store the data that it creates.
# This includes uploaded files (usually images) and the search index. # This includes uploaded files (usually images) and the search index.
# #
vitro.home = /usr/local/vivo/home vitro.home = /usr/local/vivo/home
#
# Additional languages to be built into your VIVO site. The locales specified # -----------------------------------------------------------------------------
# here must appear as sub-directories of [vivo]/languages in the distribution. # ADDING LANGUAGES TO VIVO
# Find more information on the VIVO Wiki (https://wiki.duraspace.org/display/VIVO). # -----------------------------------------------------------------------------
#
#
# Additional languages to be built into your VIVO site. The locales specified
# here must appear as sub-directories of [vivo]/languages in the distribution.
# Find more information on the VIVO Wiki (https://wiki.duraspace.org/display/VIVO).
#
#languages.addToBuild = #languages.addToBuild =