+

VIVO Release 1 V1.6 Upgrade Guide

+ + BOGUS DATE, 2013 - Upgrading from Release 1 V1.5 to Release 1 V1.6 + +

+ 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 support page + at VIVOweb.org +

+

+ If you need to do a fresh install, please consult the VIVO Release V1.6 Installation + Guide found on vivoweb.org + or the install.html file located in the doc + directory of the VIVO source code distribution. The installation document also has a + list of the required software and versions. +

+

+ For a description of the release contents see the Release announcement for V1.6. +

+
+

Table of Contents

+ +
    +
  1. Before Performing the Upgrade
    2. +
  2. + Noteworthy Changes +
      +
    1. VIVO becomes more portable
      2. +
    2. Solr is no longer secured
      3. +
    3. ANYTHING ELSE?
      4. +
    +
    3. +
  3. Upgrade Instructions
    4. +
  4. Knowledge Base Migration
    5. +
  5. Review the VIVO Terms of Use
    6. +
  6. Next Steps
    7. +
+ +
+

I. Before Performing the Upgrade

+
+ Create backups of: +
    +
  • + The VIVO distribution directory (which contains the source for VIVO 1.5 or VIVO 1.5.1) +
    • +
  • + The VIVO home directory (pointed to by your deploy.properties file) +
    • +
  • + The webapps directory in Tomcat +
    • +
  • + MySQL database (most people use mysqldump to create the backup) +
    • +
+

+ The upgrade process is similar to the initial install process + with + the following exceptions: +

+
    +
  • + You do not need to reinstall MySQL or recreate the MySQL database. Please + backup your MySQL database as noted above. +
    • +
  • + 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.) +
    • +
  • + 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 Knowledge Base Migration + below for more information. +
    • +
+ +

II. Noteworthy Changes

+
    +
  • +

    VIVO becomes more portable

    +

    + The VIVO build script now includes a distribute target that will produce + a file called distribution.tar.gz. This compressed archive contains + these files: +

      +
    1. vivo.war -- a WAR file for the main VIVO application.
      2. +
    2. vivosolr.war -- a WAR file for the Solr application.
      3. +
    3. solrhome.tar -- a Solr home directory that is configured for use with VIVO.
      4. +
    + These files can be used with Tomcat, or with any container that supports + the Java Servlet 2.4 Specification. +

    +

    + To permit this portability, the deploy.properties file + has been split in two. build.properties contains only the properties + that are required for building VIVO. runtime.properties, + which must be created in the Vitro home directory, contains the properties + that VIVO uses while running. +

    +

    + If you are building to deploy to Tomcat (as with previous releases), + then build.properties must contain these properties: +

      +
    • vitro.core.dir
      • +
    • webapp.name
      • +
    • tomcat.home
      • +
    • vitro.home -- note that this was vitro.home.directory + in previous releases
      • +
    +

    +

    + If you are building to distribute, the build.properties + file requires only these properties: +

      +
    • vitro.core.dir
      • +
    • webapp.name
      • +
    +

    + +

    Solr is no longer secured

    +

    + In previous releases, Solr was deployed to Tomcat with a RemoteAddrValve + that would only permit access from certain IP addresses. + Acceptable IP addresses were those which matched the regular expression pattern in + the vitro.local.solr.ipaddress.mask property. +

    +

    + This has been removed because: +

      +
    • It caused repeated problems for sites who were experimenting with VIVO.
      • +
    • It was not standards-based, but specific to Tomcat.
      • +
    • It was redundant. Production instances of VIVO are + usually hidden behind a firewall and accessed through an Apache Http server.
      • +
    +

    +

    + Sites that need to secure Solr are now left to their own devices. +

    + +

    ANYTHING ELSE?

    +

    +

    +
    • +
  • +

    Supported Browsers

    +

    + For this release, the following browsers are supported. + BOGUS IS THIS LIST CURRENT? +

    +

    + Mac: +

    +
      +
    • Chrome 8.0.552.237
      • +
    • FireFox 3.6.13
      • +
    • Opera 10.6.2
      • +
    • Safari 5.0.3
      • +
    +

    + PC: +

    +
      +
    • Chrome 8.0.552.273
      • +
    • FireFox 10.0.2
      • +
    • Internet Explorer 7, 8, 9
      • +
    • Opera 10.6.2
      • +
    +
    • +
+ + +

III. Upgrade Instructions

+ +

+ 1. Download the new distribution file and unpack it into a new + source directory. +

+

+ 2. Separate your existing deploy.properties file into two files, + as described below. The new build.properties file is stored in + the top level of the VIVO distribution directory. The new runtime.properties + file is stored in your Vitro home directory. +
+

+ + + + + + + + + + + + + + +
+ Properties in build.properties + + Properties in runtime.properties +
+ vitro.core.dir
+ vitro.home
+ tomcat.home
+ webapp.name
+ 		+ All other properties from deploy.properties +
+ Note that vitro.home replaces vitro.home.directory +
+ Note that vitro.local.solr.ipaddress.mask is no longer used. +
+
+ If you prefer, you may start with example.build.properties + and example.runtime.properties, make copies, + and edit them to suit your installation. + +

+ +

+ + + + + + + + + + + + + + +
+ Property Name + + Example Value +
+ BOGUS: ANY NEW PROPERTIES TO ADD? +
+ BOGUS.PROPERTYNAME + + BOGUS EXAMPLE VALUE +
+ +

+ 3. 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. +
    • +
  • + NIH-funded VIVO implementations will need 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 of your institution's tracking code, + see the VIVO + Google + Analytics + wiki + page. +
    • +
+
+

+ 5. Stop Apache Tomcat and from your VIVO source directory, run + ant + by typing: ant all +

+

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

INFO: Server startup in XXXXX ms
+

+

+ 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". +

+

+ 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.6 VIVO data after deployment, + you should save them aside. + The logs are created in the Tomcat webapps/vivo/WEB-INF directory: +

+
+
+ ontologies/update/logs/knowledgeBaseUpdate.(timestamp).log +
+
+ 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. +
+
+
+
+ ontologies/update/logs/knowledgeBaseUpdate.(timestamp).error.log +
+
+ 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. +
+
+ +

IV. Knowledge Base Migration

+ +

+ 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.6 will make + the following types of changes: +

+
+
+ BOGUS CHANGES +
+
+
+
+ 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. +
+
+

+ In addition to the logs described in step 8 of the previous section, the knowledge base migration + process will log copies of all additions and deletions that were made to the knowledge base in the following files: +

+
+
+ webapps/vivo/WEB-INF/ontologies/update/changedData/removedData.n3 +
+
+ An N3 file containing all the statements that were removed from the knowledge base. +
+
+
+
+ webapps/vivo/WEB-INF/ontologies/update/changedData/addedData.n3 +
+
+ An N3 file containing all the statements that were added to the knowledge base. +
+
+ +

V. Review the VIVO Terms of Use

+

+ VIVO comes with a "Terms of Use" statement linked from the footer. The "Site Name" + you assign in the "Site Information" form under the Site Admin + 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:

[vivo_source_dir]/vitro-core/webapp/web/templates/freemarker/body/termsOfUse.ftl
+ 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. +

+

Next Steps

+

+ Now that you have VIVO up and running, please refer to the + Site Administrator's Guide + for information about its operation. +

+