Versions Compared

Old Version 1

changes.mady.by.user Unknown User (conlon)

Saved on

compared with

New Version Current

changes.mady.by.user Unknown User (conlon)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

This file provides a short description of the steps involved in upgrading your installation of VIVO from version 1.0 to 1.1. This and other documentation can be found at: linktovivoweb linktosourceforge. For a new installation, be sure to see the installation document on VIVOWeb or SourceForge.

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 for the upgrade.
  • First-time login of the administrator account after the upgrade process is complete will use the password that you previously set, not the default password used on the first login in the initial installation.
  • The first time Apache Tomcat starts up after the upgrade, it will initiate a process that modified 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 modified 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.

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.
  5. Special notes regarding source files:
    1. This process assumes any changes made to the application were made in the source directory and deployed, and were not made directory within the Tomcat webapps directory.
    2. 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.
    3. At a minimum, it will be necessary to apply the google analytics tracking code (GATC) to googleAnalytics.ftl in the theme:
      1. No Format
        [new source directory]/themes/[theme_dir]/templates/googleAnalytics.ftl
      2. 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
      3. For more information about the GATC for the NIH-funded VIVO and a copy of your institution's tracking code, see the Google Analytics wiki page: https://confluence.cornell.edu/display/ennsrd/Google+Analytics+for+UI
  6. If you had a modified web.xml to configure the Pellet Reasoner (as described in the Installation Instructions), repeat that modification.
  7. Stop Apache Tomcat and use ant to build and deploy the new code using
    No Format
    ant all
    at the command line.
  8. 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:
    1. Context Section Before
      No Format
      <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>
    2. Context Section After
      No Format
      <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>
  9. Start Apache Tomcat and log into VIVO.

Ontology Upgrade

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 of the recommended manual reviews. This file should end with "Successfully finished processing the ontology changes."
  • ontologies/update/logs/knowledgeBaseUpdate.error.log
    • A log of errors that we 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.

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 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 changes 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.

New file storage system

Verifying the file storage upgrade

If, for any reason, the file storage upgrade process is not successful, no uploaded images will be displayed for individuals. Tomcat's "vivo.all.log" file will contain an exception listing with more information.

The file storage upgrade process wil create these files in the VIVO upload director:

  • 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.

File Storage Changes