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