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

Merge revisions 411 419 422 426 427 428 and 439 to the trunk. For ejc12

Browse source
This commit is contained in:
jeb228 2010-04-13 12:33:30 +00:00
parent 888607cf39
commit 107b12c9a3
2 changed files with 469 additions and 350 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

654
doc/install.txt
View file

@ -1,300 +1,354 @@
-------------------------------------------------------------------------------
This is a summary of the VIVO installation process. This and other documentation
can be found at:
http://vivoweb.org/support
PLEASE NOTE!
These instructions assume that you are performing a clean install,
including emptying an existing database and removing a previous installation
from the tomcat webapps directory. Product functionality may not be as expected
if you install over an existing installation of an earlier version.
Upgrade:
If you are going to upgrade an existing service, please consult the upgrade.txt
in this directory.
VIVO Developers:
If you are working on the VIVO source code from Subversion, the instructions
are slightly different. Please consult "developers.txt" in this directory.
-------------------------------------------------------------------------------
* I. Install required software
* II. Create an empty MySQL database
* III. Download the VIVO code distribution
* IV. Specify deployment properties
* V. Compile and deploy
* VI. Set Tomcat JVM Parameters
* VII. Start Tomcat
* VIII. Log in and add RDF data
* IX. Create an initial Lucene search index
* X. Setup Apache Tomcat Connector
* XI. Configure Pellet Reasoner
* XII. Was the Installation Successful?
-------------------------------------------------------------------------------
I. Install required software
Before installing VIVO, make sure that the following software is installed on
the desired machine:
* Java (SE) 1.5 or higher [http://java.sun.com/javase/downloads/]
* Apache Tomcat 5.x or higher* [http://tomcat.apache.org]
* Apache Ant [http://ant.apache.org/]
* MySQL 4.1 or higher [http://www.mysql.com/downloads/mysql/#downloads]
* Subversion client (developers only)
-------------------------------------------------------------------------------
II. Create an empty MySQL database
Decide on a database name, username, and password. Log into your mysql server
and create a new database in MySQL that uses UTF-8 encoding. You will need
these values for step IV when you configure the deployment properties. At the
mysql command line you can create the database and user with these commands
substituting your values for "dbname", "username", and "password". Most of the
time, the "hostname" will equal "localhost".
CREATE DATABASE dbname CHARACTER SET utf8;
Grant access to a database user. For example:
GRANT ALL ON dbname.* TO 'username'@'hostname' IDENTIFIED BY 'password';
Keep track of the database name, username, and password for the next step.
-------------------------------------------------------------------------------
III. Download the VIVO code distribution
Download either a zip or gz file and unpack it on your web server:
ftp://download.mannlib.cornell.edu/pub/Vivo/rel-1.0.zip
ftp://download.mannlib.cornell.edu/pub/Vivo/rel-1.0.tar.gz
-------------------------------------------------------------------------------
IV. Specify deployment properties
At the top level of the unpacked distribution, copy the file
example.deploy.properties to a file named simply deploy.properties. This file
sets several properties used in compilation and deployment.
Directory where Vitro code is located
(this is used by developers, and should not be changed)
property name: vitro.core.dir
example value: ./vitro-core
Directory where tomcat is installed
property name: tomcat.home
example value: /usr/local/tomcat
Name of your VIVO application
property name: webapp.name
example value: vivo
Directory where uploaded files will be stored
property name: upload.directory
example value: /usr/local/vivo/data/uploads
Directory where the Lucene search index will be built.
property name: LuceneSetup.indexDir
example value: /usr/local/vivo/data/luceneIndex
Specify the namespace in which the Vitro editor should create new ABox and portal resources
Note that the trailing slash is essential.
property name: Vitro.defaultNamespace
example value: http://vivo.mydomain.edu/individual/
Specify an SMTP host that the form will use for sending e-mail (Optional)
property name: Vitro.smtpHost
example value: smtp.servername.edu
Specify the JDBC URL of your database. Change the end of the
URL to reflect your database name (if it is not "vivo").
property name: VitroConnection.DataSource.url
example value: jdbc:mysql://localhost/vivo
Change the username to match the authorized user you created in MySQL
property name: VitroConnection.DataSource.username
example value: username
Change the password to match the password you created in MySQL
property name: VitroConnection.DataSource.password
example value: password
Specify the name of your first admin user for the VIVO application. This user
will have an initial password of 'defaultAdmin'. This will be changed on first
login.
property name: initialAdminUser
example value: defaultAdmin
-------------------------------------------------------------------------------
V. Compile and deploy
At the command line, from the top level of the unpacked distribution directory,
type:
ant clean deploy
to build VIVO and deploy to Tomcat's webapps directory.
-------------------------------------------------------------------------------
VI. Set Tomcat JVM Parameters
Currently, VIVO copies the contents of your RDF database into memory in order
to serve Web requests quickly. (The in-memory copy and the underlying database
are kept in synch as edits are performed.)
VIVO will require more memory than that allocated to Tomcat by default. With
most installations of Tomcat, the setenv.sh or setenv.bat file in Tomcat's bin
directory is a convenient place to set the memory parameters. For example:
export CATALINA_OPTS="-Xms1024m -Xmx1024m -XX:MaxPermSize=64m" sets Tomcat to
allocate an initial heap of 1024 megabytes, a maximum heap of 1024 megabytes,
and a PermGen space of 64 megs. 1024 megabytes is a minimum practical heap size
for production installations storing data for large academic institutions, and
additional heap space is preferable. For testing with small sets of data, 256m
to 512m should be sufficient.
If an OutOfMemoryError is encountered during VIVO execution, increasing the
heap parameters is the typical remedy.
-------------------------------------------------------------------------------
VII. Start Tomcat
Most Tomcat installations can be started by running startup.sh or startup.bat
in Tomcat's bin directory. Point your browser to http://localhost:8080/vivo/
to test the application.
If Tomcat does not start up, or the VIVO application is not visible, check the
catalina.out file in Tomcat's logs directory. (More information about detailed
error logging to be added here.)
-------------------------------------------------------------------------------
VIII. Log in and add RDF data
If the startup was successful, you will see a relatively empty screen with the
VIVO logo in the header. Click the "Log in" link near the upper right corner.
Log in with the initialAdminUser username you set up in step IV. The initial
password the initialAdminUser is defaultAdmin. On first login, you will be
prompted to select a new password and verify it a second time.
After verifying your new password, you will be presented with a menu of
editing options. Here you can create OWL classes, object properties, datatype
properties, and configure the display of data. Currently, any classes you wish
to make visible on your website must be part of a Class Group, and there a
number of visibility and display options available for each ontology entity.
More documentation is forthcoming.
VIVO comes with an ontology, but you may also upload another ontology from an
RDF file. Under the "Advanced Data Tools", click "Add/Remove RDF Data." Note
that Vitro currently works best with OWL-DL ontologies and has only limited
support for pure RDF data. You can enter a URL pointing to the RDF data you
wish to load or upload a file on your local machine. Ensure that the "add RDF"
radio button is selected. You will also likely want to check "create
classgroups automatically." Clicking the "Index" tab in the navigation bar at
the top left of the page will show a simple index of the knowledge base.
See more documentation for configuring VIVO at vivoweb.org.
-------------------------------------------------------------------------------
IX. Create an initial Lucene search index
Invoke the indexing servlet by requesting http://localhost:8080/vivo/SearchIndex
You will not see any output to the browser (though this will change in future
versions). When your browser switches to a blank screen, the indexing has
completed and the search box on the Vitro portal will be usable. Individuals
that are created, edited, or deleted from the Vitro editing interface will
trigger incremental updates of the search index.
-------------------------------------------------------------------------------
X. Setup Apache Tomcat Connector
It is recommend that a Tomcat Connector, such as mod_jk be used to ensure that
the site address does not include the port number and any extraneous Tomcat
context.
For example - http://example.com instead of http://example.com:8080/vivo
Using the mod_jk connector allows for communication between Tomcat and the
primary web server. The "Quick Start HowTo" on the Apache site
http://tomcat.apache.org/connectors-doc/generic_howto/quick.html describes
the minimum server configurations for several popular web servers.
-------------------------------------------------------------------------------
XI. Configure Pellet Reasoner
VIVO uses the ÒPelletÓ engine to perform reasoning, which runs in the
background at startup and also when the knowledge base is edited. VIVO
continues serving pages while the reasoner continues working; when it finishes,
the new inferences appear. Inferred statements are cached in a database graph
so that they are available immediately when VIVO is restarted.
By default, ÒPelletÓ is fed only an incomplete view of your ontology and only
certain inferences are materialized. These include rdf:type,
rdfs:subClassOf,owl:equivalentClass, and owl:disjointWith. This mode is
typically suitable for ontologies with a lot of instance data. If you would
like to keep the default mode, skip to the next step.
To enable "complete" OWL inference (materialize all significant entailed
statements), openvitro-core/webapp/config/web.xml and search for
PelletReasonerSetup.
Then change the name of the listener class to PelletReasonerSetupComplete.
Because "complete" reasoning can be very resource intensive, there is also an
option to materialize nearly all inferences except owl:sameAs and
owl:differentFrom.
This is enabled by specifying PelletReasonerSetupPseudocomplete. For ontologies
with large numbers of individuals, this mode can offer enormous performance
improvements over the "complete" mode.
Finally, a class called PelletReasonerSetupPseudocompleteIgnoreDataproperties
is provided to improve performance on ontologies with large literals where
datatype property entailments are not needed.
-------------------------------------------------------------------------------
XII. Was the installation successful?
If you have completed the previous steps, you have good indications that the
installation was successful.
* Step VII showed that Tomcat recognized the webapp, and that the webapp was
able to present the initial page.
* Step VIII verified that you can log in to the administrator account.
* Step IX initialized the Lucene Search system. Though there is very little
feedback for a successful installation, there are dramatic indications
for failures.
Here is a simple test to see whether the ontology files were loaded:
* Point your browser to http://localhost:8080/vivo, and click the "Log in" link
near the upper right corner. Log in with the initialAdminUser username you
set up in step IV. If this is your first time logging in, you will be
prompted to change the password.
* Click on the "Index" link on the upper left, below the logo. You should see
a "locations" section, with links for "Country" and "Geographic Location".
The index is built in a background thread, so on your first login, you may
see an empty index instead. Refresh the page periodically to see whether
the index will be populated. This may take some time: with VIVO installed
on a modest laptop computer, loading the ontology files and building the
index took more than 5 minutes from the time that Tomcat was started.
* Click on the "Country" link. You should see an alphabetical list of the
countries of the world.
Finally, test the search index.
* The search box is on the right side, directly opposite the "Index" link.
Type the word "Afghanistan" into the box, and click on the "Search"
button.You should see a page of results, with links to countries that
border Afghanistan, entities that include Afghanistan, and to
Afghanistan itself.
-------------------------------------------------------------------------------
This document is a summary of the VIVO installation process. This and other documentation
can be found at:
http://vivoweb.org/support
PLEASE NOTE!
These instructions assume that you are performing a clean install,
including emptying an existing database and removing a previous installation
from the Tomcat webapps directory. Product functionality may not be as expected
if you install over an existing installation of an earlier version.
Upgrade:
If you are going to upgrade an existing service, please consult the upgrade.txt
in this directory.
VIVO Developers:
If you are working on the VIVO source code from Subversion, the instructions
are slightly different. Please consult developers.txt in this directory.
-------------------------------------------------------------------------------
* I. Install required software
* II. Create an empty MySQL database
* III. Download the VIVO code distribution
* IV. Specify deployment properties
* V. Compile and deploy
* VI. Set Tomcat JVM Parameters
* VII. Start Tomcat
* VIII. Log in and add RDF data
* IX. Create an initial Lucene search index
* X. Setup Apache Tomcat Connector
* XI. Configure Pellet Reasoner
* XII. Was the Installation Successful?
-------------------------------------------------------------------------------
I. Install required software
Before installing VIVO, make sure that the following software is installed on
the desired machine:
* Java (SE) 1.5 or higher [http://java.sun.com]
* Apache Tomcat 5.x or higher [http://tomcat.apache.org]
* Apache Ant [http://ant.apache.org]
* MySQL 4.1 or higher [http://www.mysql.com]
-------------------------------------------------------------------------------
II. Create an empty MySQL database
Decide on a database name, username, and password. Log into your MySQL server
and create a new database in MySQL that uses UTF-8 encoding. You will need
these values for step IV when you configure the deployment properties. At the
mysql command line you can create the database and user with these commands
substituting your values for "dbname", "username", and "password". Most of the
time, the "hostname" will equal "localhost".
CREATE DATABASE dbname CHARACTER SET utf8;
Grant access to a database user. For example:
GRANT ALL ON dbname.* TO 'username'@'hostname' IDENTIFIED BY 'password';
Keep track of the database name, username, and password for Step IV.
-------------------------------------------------------------------------------
III. Download the VIVO code distribution
Download either a zip or gz file and unpack it on your web server:
ftp://download.mannlib.cornell.edu/pub/Vivo/rel-1.0.zip
ftp://download.mannlib.cornell.edu/pub/Vivo/rel-1.0.tar.gz
-------------------------------------------------------------------------------
IV. Specify deployment properties
At the top level of the unpacked distribution, copy the file
example.deploy.properties to a file named simply deploy.properties. This file
sets several properties used in compilation and deployment.
Default namespace: VIVO installations make their RDF resources available for harvest
using linked data. Requests for RDF resource URIs redirect to HTML
or RDF representations as specified by the client. To make this
possible, VIVO's default namespace must have certain structure and
begin with the public web address of the VIVO installation.
For example, if the web address of a VIVO installation is
http://vivo.example.edu/ the default namespace must be set to
http://vivo.example.edu/individual/ in order to support linked data.
Similarly, if VIVO is installed at http://www.example.edu/vivo the
default namespace must be set to http://www.example.edu/vivo/individual/
Note: The namespace must end with "individual/" (including the
trailing slash).
property name: Vitro.defaultNamespace
example value: http://vivo.mydomain.edu/individual/
Directory where Vitro code is located. In most deployments,
this is set to ./vitro-core, but it commonly points elsewhere
during development.
property name: vitro.core.dir
example value: ./vitro-core
Directory where tomcat is installed
property name: tomcat.home
example value: /usr/local/tomcat
Name of your VIVO application
property name: webapp.name
example value: vivo
Directory where uploaded files will be stored. Depending on
your permissions and who Tomcat is running as, you may need
to create these directories ahead of time.
property name: upload.directory
example value: /usr/local/vivo/data/uploads
Directory where the Lucene search index will be built.
Depending on your permissions and who Tomcat is running as,
you may need to create these directories ahead of time.
property name: LuceneSetup.indexDir
example value: /usr/local/vivo/data/luceneIndex
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.
property name: Vitro.smtpHost
example value: smtp.servername.edu
Specify the JDBC URL of your database. Change the end of the
URL to reflect your database name (if it is not "vivo").
property name: VitroConnection.DataSource.url
example value: jdbc:mysql://localhost/vivo
Change the username to match the authorized user you created in MySQL
property name: VitroConnection.DataSource.username
example value: username
Change the password to match the password you created in MySQL
property name: VitroConnection.DataSource.password
example value: password
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.
property name: initialAdminUser
example value: defaultAdmin
-------------------------------------------------------------------------------
V. Compile and deploy
At the command line, from the top level of the unpacked distribution directory,
type:
ant all
to build VIVO and deploy to Tomcat's webapps directory.
-------------------------------------------------------------------------------
VI. Set Tomcat JVM Parameters
Currently, VIVO copies the contents of your RDF database into memory in order
to serve Web requests quickly. (The in-memory copy and the underlying database
are kept in synch as edits are performed.)
VIVO will require more memory than that allocated to Tomcat by default. With
most installations of Tomcat, the setenv.sh or setenv.bat file in Tomcat's bin
directory is a convenient place to set the memory parameters.
For example:
export CATALINA_OPTS="-Xms1024m -Xmx1024m -XX:MaxPermSize=64m"
This sets Tomcat to allocate an initial heap of 1024 megabytes, a maximum heap
of 1024 megabytes, and a PermGen space of 64 megs. 1024 megabytes is a minimum
practical heap size for production installations storing data for large academic
institutions, and additional heap space is preferable. For testing with small
sets of data, 256m to 512m should be sufficient.
If an OutOfMemoryError is encountered during VIVO execution, increasing the
heap parameters and restarting Tomcat is the typical remedy.
-------------------------------------------------------------------------------
VII. Start Tomcat
Most Tomcat installations can be started by running startup.sh or startup.bat
in Tomcat's bin directory. Point your browser to http://localhost:8080/vivo/
to test the application.
If Tomcat does not start up, or the VIVO application is not visible, check the
catalina.out file in Tomcat's logs directory.
-------------------------------------------------------------------------------
VIII. Log in and add RDF data
If the startup was successful, you will see a welcome message informing you
that you have successfully installed VIVO. Click the "Log in" link near the
upper right corner. Log in with the initialAdminUser username you set up in
step IV. The initial password the initialAdminUser is defaultAdmin. On first
login, you will be prompted to select a new password and verify it a second
time.
After verifying your new password, you will be presented with a menu of
editing options. Here you can create OWL classes, object properties, data
properties, and configure the display of data. Currently, any classes you wish
to make visible on your website must be part of a class group, and there a
number of visibility and display options available for each ontology entity.
VIVO comes with a core VIVO ontology, but you may also upload other ontologies
from an RDF file. Under the "Advanced Data Tools", click "Add/Remove RDF Data."
Note that Vitro currently works best with OWL-DL ontologies and has only limited
support for pure RDF data. You can enter a URL pointing to the RDF data you
wish to load or upload a file on your local machine. Ensure that the "add RDF"
radio button is selected. You will also likely want to check "create
classgroups automatically." Clicking the "Index" tab in the navigation bar at
the top left of the page will show a simple index of the knowledge base.
See more documentation for configuring VIVO at http://vivoweb.org/support.
-------------------------------------------------------------------------------
IX. Set the Contact Email Address (if using "Contact Us" form)
If you have configured your application to use the "Contact Us" feature in Step
IV (Vitro.smtpHost), you will also need to add an email address to the VIVO
application. This is the email that the contact form submits to. It can be a
list server or an individual's email address.
Log in as a system administrator. Navigate to the "Site Admin" table of contents
(link in the right side of the header). Go to "Site Information" (under "Site
Configuration"). In the "Site Information Editing Form", enter a functional
email address in the field "Contact Email Address." and submit the change.
If you set the Vitro.smtpHost in Step IV and do NOT provide an email address
in this step, your users will receive a java error in the interface.
-------------------------------------------------------------------------------
X. Create an initial Lucene search index
Invoke the indexing servlet by requesting http://localhost:8080/vivo/SearchIndex
You will not see any output to the browser (though this will change in future
versions). When your browser switches to a blank screen, the indexing has
completed and the search box on the Vitro portal will be usable. Individuals
that are created, edited, or deleted from the Vitro editing interface will
trigger incremental updates of the search index.
-------------------------------------------------------------------------------
XI. Set up Apache Tomcat Connector
It is recommended that a Tomcat Connector such as mod_jk be used to ensure that
the site address does not include the port number (e.g. 8080) and an additional
reference to the Tomcat context name (e.g. /vivo).
For example - http://example.com instead of http://example.com:8080/vivo
Using the mod_jk connector allows for communication between Tomcat and the
primary web server. The "Quick Start HowTo" on the Apache site
http://tomcat.apache.org/connectors-doc/generic_howto/quick.html describes
the minimum server configurations for several popular web servers.
-------------------------------------------------------------------------------
XII. Configure Pellet Reasoner
VIVO uses the Pellet engine to perform reasoning, which runs in the
background at startup and also when the knowledge base is edited. VIVO
continues serving pages while the reasoner continues working; when the
reasoner finishes, the new inferences appear. Inferred statements are cached
in a database graph so that they are available immediately when VIVO is restarted.
By default, Pellet is fed only an incomplete view of your ontology and only
certain inferences are materialized. These include rdf:type,
rdfs:subClassOf,owl:equivalentClass, and owl:disjointWith. This mode is
typically suitable for ontologies with a lot of instance data. If you would
like to keep the default mode, skip to the next step.
To enable "complete" OWL inference (materialize all significant entailed
statements), open "vitro-core/webapp/config/web.xml" and search for
PelletReasonerSetup.
Then change the name of the listener class to PelletReasonerSetupComplete.
Because "complete" reasoning can be very resource intensive, there is also an
option to materialize nearly all inferences except owl:sameAs and
owl:differentFrom.
This is enabled by specifying PelletReasonerSetupPseudocomplete. For ontologies
with large numbers of individuals, this mode can offer enormous performance
improvements over the "complete" mode.
Finally, a class called PelletReasonerSetupPseudocompleteIgnoreDataproperties
is provided to improve performance on ontologies with large literals where data
property entailments are not needed.
-------------------------------------------------------------------------------
XIII. Was the installation successful?
If you have completed the previous steps, you have good indications that the
installation was successful.
* Step VII showed that Tomcat recognized the webapp, and that the webapp was
able to present the initial page.
* Step VIII verified that you can log in to the administrator account.
* Step X initialized the Lucene Search system. Though there is very little
feedback for a successful installation, there are dramatic indications
for failures.
Here is a simple test to see whether the ontology files were loaded:
* Click on the "Index" link on the upper left, below the logo. You should see
a "locations" section, with links for "Country" and "Geographic Location".
The index is built in a background thread, so on your first login, you may
see an empty index instead. Refresh the page periodically to see whether
the index will be populated. This may take some time: with VIVO installed
on a modest laptop computer, loading the ontology files and building the
index took more than 5 minutes from the time that Tomcat was started.
* Click on the "Country" link. You should see an alphabetical list of the
countries of the world.
Here is a test to see whether your system is configured to serve linked data:
* Point your browser to the home page of your website, and click the "Log in" link
near the upper right corner. Log in with the initialAdminUser username you
set up in step IV. If this is your first time logging in, you will be
prompted to change the password.
* After you have successfully logged in, click "site admin" in the upper right
corner. In the drop down under "Data Input", select "Faculty Member(core)"
and click the "Add individual of this class" button.
* Enter the name "test individual" under the field "Individual Name", scroll to
the bottom, and click "Create New Record".You will be taken to the "Individual
Control Panel". Make note of the value of the field "URI", it will be used in
the next step.
* Open a new web browser or browser tab to the page "http://marbles.sourceforge.net/".
In the pink box on that page enter the URI of the individual you created in the
previous step and click "open."
* In the resulting page search for the URI of the "test individual". You should
find it towards the bottom of the page next to a red dot followed by "redirect (303)"
This indicates that you are successfully serving linked RDF data.
If the URI of the "test individual" is followed by "failed (400)" you are not
successfully serving linked data.
Finally, test the search index (assuming you have created the initial Lucene
index in Step X).
* The search box is on the right side, directly opposite the "Index" link.
Type the word "Australia" into the box, and click on the "Search"
button.You should see a page of results, with links to countries that
border Australia, individuals that include Australia, and to
Australia itself.

165
doc/upgrade.txt
View file

@ -1,37 +1,51 @@
-------------------------------------------------------------------------------
Upgrading NIH VIVO
Steps to Upgrade from Version 1 Release 0.9 to Release 1.0
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 <20>NIH VIVO<56> from Version 1 Release 0.9 to Version 1 Release 1.0.
installation of NIH VIVO from Release 1 Version 0.9 to Release 1 Version 1.0.
This and other documentation can be found at:
----------
Before Performing the Upgrade
----------
http://vivoweb.org/support
The bullet points listed below are important to know before beginning the
upgrade process.
Installation:
If you need to do a fresh install, please consult the install.txt in this
directory.
The upgrade process is like the original install process with the following
-------------------------------------------------------------------------------
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 re-install MySQL or re-create the MySQL database. Please ensure that
* 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, initialize the Lucene Search Index, or
re-configure the Apache HTTP Server.
* 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 that Apache Tomcat starts up after the upgrade, it will
initiate a process which modifies the data in the model, aligning the data
with the revised ontology. For the most part, data in the model will not be
lost. See the section on "Ontology Changes" (below) for more information.
* If you make any changes to the application, they should be made in the source
directory and deployed, and not made directly within Apache Tomcat.
* 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.
----------
The Process
----------
-------------------------------------------------------------------------------
II. The Upgrade Process
1. Ensure that backups are created of the Tomcat webapps directory, the
original source directory, and the MySQL database.
@ -60,42 +74,93 @@ The Process
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 "productMods".
ensure that those changes are moved into the appropriate subdirectory of
"productMods".
5. If you had modified web.xml to configure the "Pellet Reasoner" (as described
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. Run ant deploy by typing: ant
6. Run ant deploy by typing: ant deploy
7. Lastly, start "Apache Tomcat" and login to VIVO.
7. Start "Apache Tomcat" and login to VIVO.
----------
Ontology Changes
----------
8. 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.
There are changes in the ontology that may require sites to modify the data in
their model.
-------------------------------------------------------------------------------
For example, if there is a split in a combined class
(e.g., SchoolOrCollegeWithinUniversity into School and College) it is
impossible to determine which class of individuals were added to the combined
class and which class those individuals should be assigned.
III. Ontology Changes
Note: When "Apache Tomcat" starts up following the upgrade, it will initiate
a process which may modify the data in the model, to align the data to the
current ontology. Refer to your institutions ontology team representative for
additional information on ontology changes affecting data prior to performing
the upgrade.
The ontology alignment process will create these files in the Tomcat webapps directory:
* WEB-INF/ontologies/update/logs/knowledgeBaseUpdate.log
a log of updates that were made to the knowledge base and notes about some
of the recommended manual reviews.
* WEB-INF/ontologies/update/logs/knowledgeBaseUpdate.error.log
a log of errors that were encoundered during the upgrade process.
* WEB-INF/ontologies/update/removedData/removedData.rdf
a file containing the stataements that were removed from the data model.
* WEB-INF/ontologies/update/addedData/addedData.rdf
a file containing the statements that were added to the data model.
After Apache Tomcat is started, you should review these files to see whether
you need to edit any data in response to the 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.rdf
a file containing all the statements that were removed from the knowledge base.
ontologies/update/changedData/addedData.rdf
a 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.