Upgrading from Release 1.7 to Release 1.8.1

This document contains instructions on how to upgrade your installation of VIVO from Version 1.7 to Version 1.8.1. 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 Installation Instructions, found on vivoweb.org, or the VIVO Installation Instructions.pdf 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.8.

Before Performing the Upgrade

Create backups of:

The VIVO distribution directory (which contains the source for VIVO 1.7
The VIVO home directory (pointed to by your build.properties file)
The webapps directory in Tomcat
MySQL database (most people use mysqldump to create the backup)

If you have used temporary models in the database to stage ingested data, you will want to clear out any unneeded models that remain listed on the Manage Jena Models page (under Ingest tools). This step is especially important if these temporary models contain blank nodes, as this may cause unwanted or duplicate data to appear following the upgrade.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.
The root account will keep the password that was previously set on it. It will not return to the default password. Any user accounts that you have created will also be preserved.

Noteworthy Changes

Editing faux properties

There is now a GUI for editing faux properties. In previous releases, PropertyConfig.n3 contained the faux property configuration, now it will contain the initial configuration.

In v1.8, PropertyConfig.n3 has moved from rdf/display/evertime to rdf/display/firsttime. It will be read in once, in order to pick up the version changes.

If you have local modifications for PropertyConfig.n3, you can ingest those changes or use the GUI to enter them into v1.8.

Configuration changes

Before starting VIVO 1.8, you must create config/applicationSetup.n3 in your VIVO home directory. For most installations this is simply a copy of config/example.applicationSetup.n3.

If you have created a developer.properties file in your VIVO home directory, you should move it to the config sub-directory of the VIVO home directory.

Alternative triple stores

If you are using an external triple store on a SPARQL endpoint, you must change how it is configured. This configuration is no longer made in runtime.properties; instead, it is done in config/applicationSetup.n3.

For more details, consult the Installation Instructions, in the section titled "Using a Different Datastore".

Supported versions of Java

VIVO 1.8 supports Oracle Java 1.8 as well as Oracle Java 1.7.

Supported Browsers

For this release, the following browsers are supported.

Mac:
- Chrome 30.0.1599.69 and above
- Firefox 3.6.28, 10.0.12, 24, 30
- Opera 12.15
- Safari 5.0.3 and above
PC:
- Chrome 25.1364.2 and above
- Firefox 10.0.12, 24, 30
- Internet Explorer 8 (see compatibility note), 9, 10
- Opera 12.02

1.8.1 introduces new D3-based visualizations for the Co-Author and Co-Investigator networks. These do not work on IE 8, however, they do increase compatibility to mobile browsers that do not have Flash.

If you require the traditional Flash visualizations for IE 8 compatibility (providing Adobe Flash has been installed), then you can use them by setting the following in your runtime.properties:

visualization.d3 = disabled

It is expected that the Flash visualizations will be removed from version 1.9.0 onwards.

Upgrade Instructions

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

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.

Apply any previous changes you have made to the RDF initialization files.

Run the build script

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

Create configuration files

In the config sub-directory of your VIVO home directory (specified by vitro.home in the build.properties file), rename or copy example.applicationSetup.n3 to applicationSetup.n3. For most installations, changes to this file are not needed.

If you have been using a SPARQL endpoint as your triple store, you will need to edit this file. See Using a different data store for more information.

If you have been using a developer.properties file, you must move it to the config sub-directory of your VIVO home directory.

Start VIVO

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

Review the knowledge base migration logs.

This is usually an important step in VIVO upgrades. However, the upgrade from VIVO 1.7 to VIVO 1.8 does not require a knowledge base migration.

Knowledge Base Migration

This is usually an important step in VIVO upgrades. However, the upgrade from VIVO 1.7 to VIVO 1.8 does not require a knowledge base migration.

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.