VIVO Release 1 v1.2 Upgrade Guide
- - January 28, 2011 - Upgrading from Release 1 v1.1 to Release 1 v1.2 - -- Missing pieces and fixes --+
VIVO Release 1 v1.2 Upgrade Guide
+ + January 28, 2011 - Upgrading from Release 1 v1.1 to Release 1 + v1.2 + ++ Missing pieces and fixes +++
+- + Link to install pdf online at SF +
+- +
+
++ ++
+- + Release announcement for V1.2 +
+- + Upgrade process for V1.2 +
++ This document provides a short description of the steps involved in + upgrading your installation of VIVO from Release 1, Version 1.1 to + Version 1.2. This and other documentation can be found on the support page + at VIVOweb.org +
++ If you need to do a fresh install, please consult VIVO Release 1 v1.2 + Installation Guide + or the install.html file located in the
+doc+ directoy of the VIVO source code distribution. The installation + document also has a list of the required software and versions. +Release anouncement for V1.2
++ The VIVO 1.2 release incorporates major changes to the entire + application - theming and navigation changes that will be immediately + evident to any user, and underlying changes to the system architecture + that are less visible but address important questions of scalability + and extensibility. +
+Theming and Navigation
++ A new installation of VIVO 1.2 will look strikingly different - the + User Interface team has designed a new visual theme that incorporates a + new navigation and browse structure as well as a much more modular + approach to page design. This theme is not only cosmetically different + but leverages entirely new page templates developed with the Freemarker + system, an open-source library for Java development that enables much + cleaner separation of application logic from the actual page design. + These changes extend the available configuration options controlling + VIVO's appearance and navigation options while also simplifying the + process of local customization and branding. +
++ For existing installations of VIVO, the upgrade will not immediately + transition to the new theme, navigation, or page templates. The current + default theme and "tabs" (top-level and secondary navigation controls) + will be left intact on upgrade and will still function as they do in + version 1.1.1, with the caveat that local modifications to the default + theme may conflict with internal application changes. We highly + recommend that current VIVO installations use the time between release + 1.2 and the upcoming release of version 1.3 (targeted for June or July + 2011) to migrate local theme branding and navigation to the new VIVO + template. Many legacy features such as the "tab" infrastructure have + been deprecated with version 1.2 and will no longer be supported as of + version 1.3. +
+Browsing
++ In addition to changes in the top-level navigation, VIVO 1.2 + introduces a number of new browsing controls that will be made more + configurable and extensible in version 1.3 but which already offer + extensive functionality. +
++ A fresh installation of VIVO 1.2 will feature the new theme and + additional browsing options on other top-level navigation pages (Home, + People, Research, Organizations, and Events). Primary among the new + browsing options will be browsing by type, organized + hierarchically with the same upper-level class groups + currently + visible in search results - people, courses, activities, topics, + events, organizations, and publications. Class groups combine the + similar types such as people or organizations into groups for browsing + and searching, and are locally configurable using the VIVO ontology + editor. +
++ Once a group has been selected, browsing can continue to the very + specific, at the level of individual people, organizations, events, or + publications via A ... Z listing featuring thumbnail pictures where + available. Sites will be able to configure which groups and which types + within a group are exposed in search results and for browsing. +
+Data Storage
++ Before this release, VIVO has used the Jena + (http://jena.sourceforge.net) + relational database (RDB) + subsystem for the storage of RDF data. The performance of this persistence layer + has never been fast enough for an interactivity at any significant scale, so + VIVO has also maintained a complete copy of data in memory. While server memory capacity + has increased significantly in recent years, this requirement has put + limits on the ultimate scalability of VIVO instances and also increased + the cost of servers required to support VIVO. +
++ With version 1.2 VIVO uses the SPARQL database (SDB) subsystem of + Jena, specifically designed to support scalable storage and query of + RDF datasets while still using standard relational database technology. + This transition will significantly reduce the initial memory footprint + of a VIVO application, and while the application will still require + adequate processor and memory resources to generate pages from so many + individual RDF statements, the scalability of VIVO installations is + greatly improved. +
++ The transition to retrieving all data via SPARQL queries also + enables additional features important for tracking data provenance and + access to data outside the immediate local VIVO instance. These + features will be more fully explored and developed for version 1.3. +
+Upgrade process for V1.2
++ ++
+- + Before Performing the Upgrade +
+- + The Upgrade Process +
+- + Ontology Upgrade + +
+- + File Storage System Upgrade + +
+- + Theme Modifications +
+I. Before Performing the Upgrade
++ Please ensure that backups are created of the: +
+-
- - Link to install pdf online at SF + Tomcat webapps directory
- - Add config table from install d/t so many new vars. + Original source directory
- + MySQL database (mysqldump)
+ The upgrade process is similar to the original install process with + the following EXCEPTIONS: +
- - Release announcement for V1.2 + DO NOT reinstall MySQL or recreate the MySQL database. Please + ensure that you back-up the MySQL database.
- - Upgrade process for V1.2 + It is not necessary to add RDF data. + +
- + First-time login of the administrator 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.
- This document provides a short description of the steps involved in upgrading your - installation of VIVO from Release 1, Version 1.1 to Version 1.2. This and other - documentation can be found on the support page - at VIVOweb.org -
-
- If you need to do a fresh install, please consult VIVO Release 1 v1.2 Installation Guide
- or the install.html file located in the doc
- directoy of the VIVO source code distribution.
-
Release anouncement for V1.2
-- Text from the wiki page -
-Upgrade process for V1.2
- --
-
- - Before Performing the Upgrade - -
- - The Upgrade Process - -
- - Ontology Upgrade - - -
- - File Storage System Upgrade - - -
- - Theme Modifications - -
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: -
--
-
- - 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 administrator 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. - -
The Upgrade Process
-- 1. Download the new distribution file and unpack it into a new source - directory. -
-- 2. Create deploy.properties, using the same values as in your previous - installation and set values for the new variables. The following table - shows the default properties for deploy.properties with new V1.2 properties in - blue. - +
The Upgrade Process
++ 1. Download the new distribution file and unpack it into a new + source directory. +
++ 2. Create deploy.properties, using the same values as in your + previous installation and set values for the new variables. The + following table shows the default properties for deploy.properties with + new V1.2 properties in blue. +
| - 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 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, but it commonly points elsewhere during development. - | -|
| - vitro.core.dir - | -- ./vitro-core - | -
| - Directory where tomcat is installed. - | -|
| - tomcat.home - | -- /usr/local/tomcat - | -
| - Name of your VIVO application. - | -|
| - webapp.name - | -- vivo - | -
| - Directory where uploaded files will be stored. You must create this directory ahead of time. - | -|
| - upload.directory - | -- /usr/local/vivo/data/uploads - | -
| - Directory where the Lucene search index will be built. Depending on your - permissions and who Tomcat is running as, you may need to create this directory - ahead of time. - | -|
| - LuceneSetup.indexDir - | -- /usr/local/vivo/data/luceneIndex - | -
| - Specify an SMTP host that the form will use for sending e-mail (Optional). If - this is left blank, the contact form will be hidden and disabled. - | -|
| - Vitro.smtpHost - | -- smtp.servername.edu - | -
| - Specify the JDBC URL of your database. Change the end of theURL 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 Jena triple store technology to use. SDB is Jena's - SPARQL database; this setting allows RDF data to scale beyond the - limits of the JVM heap. Set to RDB to use the older Jena RDB - store with in-memory caching. - | -|
| - VitroConnection.DataSource.tripleStoreType - | -- SDB - | -
| - 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 name of your first admin user for the VIVO application. - This user will have an initial temporary password of 'defaultAdmin'. - You will be prompted to create a new password on first login. - | -|
| - initialAdminUser - | -- defaultAdmin - | -
| - The name 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 editthat Individual. - | -|
| - selfEditing.idMatchingProperty - | -- http://vivo.mydomain.edu/ns#networkId - | -
| - Temporal Graph Visualization is used to compare different - organizations/people within an organization on different parameters like - number of publications, grants. This parameter will be used as a default - in case a URI is not provided. It will be also used whenever this - visualization is to be rendered for top level organization. - In absence of this parameter a SPARQL query will be fired which will - attempt to provide a top level organization. The name 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. - | -|
| - visualization.topLevelOrg - | -- http://vivo-trunk.indiana.edu/individual/topLevelOrgURI - | -
| + 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
+ 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 + | +
| + Directory where uploaded files will be stored. + Be sure this directory exists and is writable by the user that + the Tomcat service is running as. + | +|
| + upload.directory + | ++ /usr/local/vivo/data/uploads + | +
| + Directory where the Lucene search index will be + built. Be sure this directory exists and is writable by the user that + the Tomcat service is running as. + | +|
| + LuceneSetup.indexDir + | ++ /usr/local/vivo/data/luceneIndex + | +
| + Specify an SMTP host that the form will use for + sending e-mail (Optional). If this is left blank, the contact form will + be hidden and disabled. + | +|
| + Vitro.smtpHost + | ++ smtp.servername.edu + | +
| + Specify the JDBC URL of your database. Change + the end of theURL 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 Jena triple store technology to use. + SDB is Jena's SPARQL database; this setting allows RDF data to scale + beyond the limits of the JVM heap. Set to RDB to use the older Jena RDB + store with in-memory caching. + | +|
| + VitroConnection.DataSource.tripleStoreType + | ++ SDB + | +
| + 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 name of your first admin user for + the VIVO application. This user will have an initial temporary password + of 'defaultAdmin'. You will be prompted to create a new password on + first login. + | +|
| + initialAdminUser + | ++ defaultAdmin + | +
|
+ 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. For example, to use the netID
+ at Cornell University as the property:
+ + seflEditing.idMatchingProperty + = + http://vivo.cornell.edu/ns/hr/0.9/hr.owl#netId + |
+ |
| + selfEditing.idMatchingProperty + | ++ http://vivo.mydomain.edu/ns#networkId + | +
|
+ 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 + | +
- 3. Apply any previous changes you have made to the new source directory. +
+ 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. + 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. + 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 Implmentations 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+ NIH-funded VIVO Implmentations will need to apply the Google + Analytics Tracking Code (GATC) togoogleAnalytics.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 your institution's tracking code, see the VIVO Google Analytics wiki page. + 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 your institution's tracking code, see + the VIVO + Google + Analytics + wiki + page.- If you had used the
vivo/contrib/FLShibboleth- code in your previous release, - you should stop using it. Consultinstall.html- or VIVO Release 1 v1.2 Installation Guide - on "Using an External Authentication System with VIVO". + code in your previous release, you should stop using it. Consultinstall.html+ or VIVO Release 1 + v1.2 Installation Guide + on "Using an External Authentication System + with VIVO".