VIVO Release 1 V1.6 Upgrade Guide
BOGUS DATE, 2013 - Upgrading from Release 1 V1.5 to Release 1 V1.6This 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
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 calleddistribution.tar.gz
. This compressed archive contains these files:vivo.war
-- a WAR file for the main VIVO application.vivosolr.war
-- a WAR file for the Solr application.solrhome.tar
-- a Solr home directory that is configured for use with VIVO.
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), thenbuild.properties
must contain these properties:vitro.core.dir
webapp.name
tomcat.home
vitro.home
-- note that this wasvitro.home.directory
in previous releases
If you are building to
distribute
, thebuild.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 thevitro.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.
The properties below are new to runtime.properties
. They are optional,
so you need not add them, unless you want a value other than the default.
Property Name | Example Value |
---|---|
Force VIVO to use a specific language or Locale instead of those specified by the browser. This affects RDF data retrieved from the model, if RDFService.languageFilter is true. This also affects the text of pages that have been modified to support multiple languages. | |
languages.forceLocale | en_US |
A list of supported languages or Locales that the user may choose to use instead of the one specified by the browser. Selection images must be available in the i18n/images directory of the theme. This affects RDF data retrieved from the model, if RDFService.languageFilter is true. This also affects the text of pages that have been modified to support multiple languages. | |
languages.selectableLocales | en, es, fr_FR |
For developers only.
Defeat the Freemarker template cache, so each template
is read from disk on each request. This permits developers to immediately
see the effect of changes to the template. The default is false , which
means that a cached copy of each template will be used for 60 seconds
before the disk is checked for a new version.
Setting this option to "true" slows down VIVO performance. |
|
developer.defeatFreemarkerCache | false |
For developers only.
Defeat the cache of language-specific text strings,
so the language file is read from disk on each request.
This permits developers to immediately
see the effect of changes to the text strings.
The default is false , which means that the language file is
read when VIVO starts up, or when a new theme is selected.
Setting this option to "true" slows down VIVO performance. |
|
developer.defeatI18nCache = true | false |
For developers only.
Add starting and ending delimiters to each Freemarker template, so you can see
which template were invoked by viewing the generated HTML.
The default is false .
Setting this option to "true" slows down VIVO performance. |
|
developer.insertFreemarkerDelimiters = true | false |
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.ftlA samplegoogleAnalytics.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.ftlBe 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.