VIVO Release 1 V1.4 Upgrade Guide
- Upgrading from Release 1 V1.3 to Release 1 V1.4 + December 9, 2011 - Upgrading from Release 1 V1.3 to Release 1 V1.4 +-
+
- + Release announcement for V1.4 + +
- + Upgrade process for V1.4 + +
+ This document provides a short description of the steps involved in + upgrading your installation of VIVO from Version 1.3 to Version 1.4. + 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.4 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 (there are no new hardware
+ or software requirements for V1.4).
+
Release Announcement for V1.4
+ +TBD
++
Upgrade process for V1.4
+-
+
- + Before Performing the Upgrade + +
-
+ Noteworthy Changes
+
+-
+
- + Template changes + +
- + Profile editing by Proxies + +
- + Change to Tomcat configuration + +
+ - + The Upgrade Process + +
- + Ontology Changes + + +
- + Review the VIVO Terms of Use + +
Template changes
--
-
${stylesheets.list},${scripts.list}, and${headscripts.list}have changed to -${stylesheets.list()},${scripts.list()}, and${headscripts.list()}, respectively. +I. Before Performing the Upgrade
++ Please ensure that backups are created of the: +
+-
+
- + Tomcat webapps directory +
- + Original source directory + +
- + MySQL database (mysqldump) + +
+ The upgrade process is similar to the original install process + with + the following EXCEPTIONS: +
+-
+
-
+ If you are still in RDB mode, it is required that you move
+ your
+ triple store to SDB while still at V1.2 (see Triple
+ Store
+ info below).
+
+
+ - + 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. + +
- + 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, it + will initiate a process that modifies the knowledge base to align the + data with the revised ontology. See the section on the Ontology Upgrade + below for more information. + +
II. Noteworthy Changes
+ +i. Template changes +
+-
+
${stylesheets.list},${scripts.list}, and${headscripts.list}have changed to +${stylesheets.list()},${scripts.list()}, and${headscripts.list()}, respectively. +
(ryounes)
-
addition to deploy.properties
--
-
- What types of individuals may have proxy editors?
-
proxy.eligibleTypeList = http://xmlns.com/foaf/0.1/Person, http://xmlns.com/foaf/0.1/Organization
-
+
ii. Profile editing by Proxies +
+-
+
- addition to deploy.properties +
- What types of individuals may have proxy editors?
+
proxy.eligibleTypeList = http://xmlns.com/foaf/0.1/Person, http://xmlns.com/foaf/0.1/Organization
+
(jblake)
-
changes to the build script
--
-
- Incremental builds go much faster, but at some cost:
+
iii. Change to Tomcat configuration +
+-
+
- Tomcat configuration +
- Specify URI encoding + +
III. The Upgrade Process
++ 1. Download the new distribution file and unpack it into a new + source directory. +
++ 2. Create a new deploy.properties using the same values as in + your + previous installation and set values for the new variables as described + below (vitro.local.solr.url, vitro.local.solr.ipaddress.mask, + vitro.home.directory, email.smptHost, email.replyTo, + rootUser.emailAddress) +
+
++ +
++ +
+ + ++ ++ Property Name + ++ Example Value + ++ ++ Default namespace: VIVO installations make their + RDF resources available for harvest using linked data. Requests for RDF + resource URIs redirect to HTML or RDF representations as specified by + the client. To make this possible, VIVO's default namespace must have a + certain structure and begin with the public web address of the VIVO + installation. For example, if the web address of a VIVO installation is + "http://vivo.example.edu/" the default namespace must be set to + "http://vivo.example.edu/individual/" in order to support linked data. + Similarly, if VIVO is installed at "http://www.example.edu/vivo" the + default namespace must be set to + "http://www.example.edu/vivo/individual/" +* The namespace must end with "individual/" (including the + trailing slash).
++ ++ Vitro.defaultNamespace + ++ http://vivo.mydomain.edu/individual/ + ++ ++ Directory where Vitro code is located. In most + deployments, this is set to ./vitro-core (It is not uncommon for this + setting to point elsewhere in development environments). + ++ ++ vitro.core.dir + ++ ./vitro-core + ++ ++ Directory where tomcat is installed. + ++ ++ tomcat.home + ++ /usr/local/tomcat + ++ ++ Name of your VIVO application. + ++ ++ webapp.name + ++ vivo + ++ ++ URL of Solr context used in local VIVO search. + Should consist of: +scheme + servername + port + vivo_webapp_name + "solr"
+ In the standard installation, the Solr context will be on the same + server as VIVO, and in the same Tomcat instance. The path will be the + VIVO webapp.name (specified above) + "solr" ++ ++ vitro.local.solr.url + ++ http://localhost:8080/vivosolr + ++ ++ Restricts access to the Solr search platform. + One or more regular expressions, separated by commas. When a request is + made to Solr, the IP address of the requestor must match one of the + patterns, or the request will be rejected. + +
+ Examples:++-
+
- + vitro.local.solr.ipaddress.mask = 127\.0\.0\.1 + +
- + vitro.local.solr.ipaddress.mask = + 127\.0\.0\.1,0:0:0:0:0:0:0:1 + +
- + vitro.local.solr.ipaddress.mask = 169.254.* + +
+ ++ vitro.local.solr.ipaddress.mask + ++ 127\.0\.0\.1,0:0:0:0:0:0:0:1 + ++ ++ Directory where the VIVO application will store + the data that it creates. This includes uploaded files (usually images) + and the Solr search index. Be sure this directory exists and is + writable by the user who the Tomcat service is running as. + ++ ++ vitro.home.directory + ++ /usr/local/vivo/data + ++ ++ Specify an SMTP host that the application will + use for sending e-mail (Optional). If this is left blank, the contact + form will be hidden and disabled, and users will not be notified of + changes to their accounts. + ++ ++ email.smtpHost + ++ smtp.servername.edu + ++ ++ Specify an email address which will appear as + the sender in e-mail notifications to users (Optional). If a user + replies to the notification, this address will receive the reply. If a + user's e-mail address is invalid, this address will receive the error + notice. If this is left blank, users will not be notified of changes to + their accounts. + ++ ++ email.replyTo + ++ vivoAdmin@my.domain.edu + ++ ++ Specify the JDBC URL of your database. Change + the end of the URL to reflect your database name (if it is not "vivo"). + ++ ++ VitroConnection.DataSource.url + ++ jdbc:mysql://localhost/vivo + ++ ++ Change the username to match the authorized user + you created in MySQL. + ++ ++ VitroConnection.DataSource.username + ++ username + ++ ++ Change the password to match the password you + created in MySQL. + ++ ++ VitroConnection.DataSource.password + ++ password + ++ ++ Specify the maximum number of active connections + in the database connection pool to support the anticipated number of + concurrent page requests. It is not necessary to adjust this value when + using the RDB configuration. + ++ ++ VitroConnection.DataSource.pool.maxActive + ++ 40 + ++ ++ Specify the maximum number of database + connections that will be allowed to remain idle in the connection pool. + Default is 25% of the maximum number of active connections. + ++ ++ VitroConnection.DataSource.pool.maxIdle + ++ 10 + ++ ++ Change the dbtype setting to use a database + other than MySQL. Otherwise, leave this value unchanged. Possible + values are DB2, derby, HSQLDB, H2, MySQL, Oracle, PostgreSQL, and + SQLServer. Refer to http://openjena.org/wiki/SDB/Databases_Supported + for additional information. + ++ ++ VitroConnection.DataSource.dbtype + ++ MySQL + ++ ++ Specify a driver class name to use a database + other than MySQL. Otherwise, leave this value unchanged. This JAR file + for this driver must be added to the the webapp/lib directory within + the vitro.core.dir specified above. + ++ ++ VitroConnection.DataSource.driver + ++ com.mysql.jdbc.Driver + ++ ++ Change the validation query used to test + database connections only if necessary to use a database other than + MySQL. Otherwise, leave this value unchanged. + ++ ++ VitroConnection.DataSource.validationQuery + ++ SELECT 1 + ++ ++ Specify the email address of the root user + account for the VIVO application. This user will have an initial + temporary password of 'rootPassword'. You will be prompted to create a + new password on first login. + ++ NOTE: The root user account has access to all data and all + operations in VIVO. Data views may be surprising when logged in as the + root user. It is best to create a Site Admin account to use for every + day administrative tasks. +
++ ++ rootUser.emailAddress + ++ vivoAdmin@my.domain.edu + ++ ++ The URI of a property that can be used to + associate an Individual with a user account. When a user logs in with a + name that matches the value of this property, the user will be + authorized to edit that Individual + (the value of the property must be either a String literal or an untyped literal). + ++ ++ selfEditing.idMatchingProperty + ++ http://vivo.mydomain.edu/ns#networkId + ++ ++ If an external authentication system like Shibboleth or CUWebAuth is to be + used, these properties say how the login button should be labeled, and which + HTTP header will contain the user ID from the authentication system. If such + a system is not to be used, leave these commented out. Consult the installation + instructions for more details. + ++ ++ externalAuth.buttonText + +
+ externalAuth.netIdHeaderName ++ Log in using BearCat Shibboleth + +
+ remote_userID ++ ++ The temporal graph visualization can require + extensive machine resources. This can have a particularly noticable + impact on memory usage if + +-
+
- + The organization tree is deep, + +
- + The number of grants and publications is large. + +
+ ++ visualization.temporal + ++ enabled + ++ ++ The temporal graph visualization is used to + compare different organizations/people within an organization on + parameters like number of publications or grants. By default, the app + will attempt to make its best guess at the top level organization in + your instance. If you're unhappy with this selection, uncomment out the + property below and set it to the URI of the organization individual you + want to identify as the top level organization. It will be used as the + default whenever the temporal graph visualization is rendered without + being passed an explicit org. For example, to use "Ponce School of + Medicine" as the top organization: + +
+visualization.topLevelOrg = + http://vivo.psm.edu/individual/n2862+
++ ++ visualization.topLevelOrg + ++ http://vivo-trunk.indiana.edu/individual/topLevelOrgURI + ++ ++ An absolute file path, pointing to the root directory of the Harvester utility. + You must include the final slash. + ++ + ++ harvester.location + ++ /usr/local/vivo/harvester/ + ++ 3. Apply any previous changes you have made to the new source + directory. +
++ Special notes regarding source files
-
-
- full builds go a little slower -
- if you delete a source file, you must do a full build to really get rid of it. +
- + 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 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. +
- - Changes to solr deploy. - (jblake) -
Tomcat configuration
--
-
- Specify URI encoding - - (jblake) -
+ 4. If you had modified web.xml
+ to configure the
+ Pellet Reasoner (as described in the installation instructions), repeat
+ that modification.
+
+ 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". +
+IV. Ontology Changes
+i. 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.(timestamp).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 "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. + +
-
+
-
+
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. + +
ii. 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 a process 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 type assertions of a deleted class will be removed.
+
+ 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. +
+
-
+
- + Property addition + +
- + If a newly added property is the inverse of a previously + existing property, the inverse of any statements using the pre-existing + property will be asserted. + +
-
+
- + 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. +
+
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 Step ...
++ Now that you have VIVO up and running, please go read the Site Administrator's Guide. +
+