litvinovg/vivo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merging Elly and my changes to upgrade-1.1.txt from rel-1.1-maint branch to trunk. Revisions: 1008 1082:1089 1146:1159 1162:1164

Browse source
This commit is contained in:
rjy7 2010-07-26 14:10:49 +00:00
parent be9082a691
commit ce720e7bb3
1 changed files with 370 additions and 358 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

728
doc/upgrade-1.1.txt
View file

@ -1,358 +1,370 @@
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
Upgrading NIH VIVO Upgrading NIH VIVO
Steps to Upgrade from Release 1 Version 1.0 to Release 1 Version 1.1 Steps to Upgrade from Release 1 Version 1.0 to Release 1 Version 1.1
This file provides a short description of the steps involved in upgrading your This file provides a short description of the steps involved in upgrading your
installation of NIH VIVO from Release 1 Version 1.0 to Release 1 Version 1.1. installation of NIH VIVO from Release 1 Version 1.0 to Release 1 Version 1.1.
This and other documentation can be found at: This and other documentation can be found at:
http://vivoweb.org/support http://vivoweb.org/support
Installation: Installation:
If you need to do a fresh install, please consult the install.txt in this If you need to do a fresh install, please consult the install.txt in this
directory. directory.
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
I. Before Performing the Upgrade I. Before Performing the Upgrade
II. The Upgrade Process II. The Upgrade Process
III. Ontology Upgrade III. Ontology Upgrade
A. Verify Ontology upgrade process A. Verify Ontology upgrade process
B. Ontology knowledge base manual r B. Ontology knowledge base manual r
IV. New File Storage System IV. New File Storage System
A. Verifying the File Storage upgrade A. Verifying the File Storage upgrade
B. File Storage changes B. File Storage changes
V. Theme Changes V. Theme Changes
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
I. Before Performing the Upgrade I. Before Performing the Upgrade
Please read the bullet points below BEFORE beginning the upgrade. Please read the bullet points below BEFORE beginning the upgrade.
The upgrade process is similar to the original install process with the following The upgrade process is similar to the original install process with the following
exceptions: exceptions:
* DO NOT reinstall MySQL or recreate the MySQL database. Please ensure that * DO NOT reinstall MySQL or recreate the MySQL database. Please ensure that
you back-up the MySQL database. you back-up the MySQL database.
* It is not necessary to add RDF data or reconfigure the Apache HTTP Server. * It is not necessary to add RDF data or reconfigure the Apache HTTP Server.
* First-time login of the administrator account will use the password * First-time login of the administrator account will use the password
previously set, NOT the password in deploy.properties. previously set, NOT the password in deploy.properties.
* The first time Apache Tomcat starts up after the upgrade, it will * The first time Apache Tomcat starts up after the upgrade, it will
initiate a process that modifies the knowledge base to align the data initiate a process that modifies the knowledge base to align the data
with the revised ontology. See the section on "Ontology Changes" with the revised ontology. See the section on "Ontology Changes"
below for more information. below for more information.
* The first time Apache Tomcat starts up after the upgrade, it will * The first time Apache Tomcat starts up after the upgrade, it will
initiate a process that modifies the uploaded files directory (images), to initiate a process that modifies the uploaded files directory (images), to
align the uploaded files with the revised file storage scheme. See the align the uploaded files with the revised file storage scheme. See the
section on "File Storage Changes" below for more information. section on "File Storage Changes" below for more information.
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
II. The Upgrade Process II. The Upgrade Process
1. Ensure that backups are created of the Tomcat webapps directory, the 1. Ensure that backups are created of the Tomcat webapps directory, the
original source directory, the MySQL database, and the uploaded files original source directory, the MySQL database, and the uploaded files
directory (images). directory (images).
2. Download the new distribution file and unpack it into a new source 2. Download the new distribution file and unpack it into a new source
directory. directory.
3. Create deploy.properties, using the same values as in your previous 3. Create deploy.properties, using the same values as in your previous
installation. installation.
4. Apply any changes you have made to the new source directory. 4. Apply any changes you have made to the new source directory.
************* Special notes regarding source files ******************** ************* Special notes regarding source files ********************
This process assumes any changes made to the application were made in This process assumes any changes made to the application were made in
the source directory and deployed, and were not made directly within the source directory and deployed, and were not made directly within
Apache Tomcat webapp. Apache Tomcat webapp.
In many cases, simply copying the modified files from your original In many cases, simply copying the modified files from your original
source directory will not work since the files on which they are based 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 have changed. It will be necessary to inspect the new source files and
add any changes to them at that time. add any changes to them at that time.
At a minimum it will be necessary to apply the Google Analytics Tracking At a minimum it will be necessary to apply the Google Analytics Tracking
Code (GATC) to googleAnalytics.ftl in the theme: Code (GATC) to googleAnalytics.ftl in the theme:
[new_source_directory]/themes/[theme_dir]/templates/googleAnalytics.ftl [new_source_directory]/themes/[theme_dir]/templates/googleAnalytics.ftl
A sample googleAnalytics.ftl is included in the built-in theme. This file 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 serves only as an example, and you must replace the tracking code shown
with your institution's own tracking code. with your institution's own tracking code.
For additional information about the GATC for the NIH-funded VIVO For additional information about the GATC for the NIH-funded VIVO
implementation sites and a copy your institution's tracking code, see the implementation sites and a copy your institution's tracking code, see the
VIVO Google Analytics wiki page: VIVO Google Analytics wiki page:
https://confluence.cornell.edu/display/ennsrd/Google+Analytics+for+UI https://confluence.cornell.edu/display/ennsrd/Google+Analytics+for+UI
************************************************************************ ************************************************************************
5. If you had modified web.xml to configure the Pellet Reasoner (as described 5. If you had modified web.xml to configure the Pellet Reasoner (as described
in the installation instructions), repeat that modification. in the installation instructions), repeat that modification.
6. Stop "Apache Tomcat" and run ant by typing: ant all 6. Stop "Apache Tomcat" and run ant by typing: ant all
7. If you have set up the Apache Tomcat Connector using mod_jk and modified 7. If you have set up the Apache Tomcat Connector using mod_jk and modified
your tomcat/conf/server.xml file, you will need to add a line to your your tomcat/conf/server.xml file, you will need to add a line to your
context section specifying a "Manager" tag; see examples below. context section specifying a "Manager" tag; see examples below.
Context section before: Context section before:
<Context path="" <Context path=""
docBase="/usr/local/tomcat/webapps/vivo" docBase="/usr/local/tomcat/webapps/vivo"
reloadable="true" reloadable="true"
cookies="true" > cookies="true" >
<Environment type="java.lang.String" override="false" <Environment type="java.lang.String" override="false"
name="path.configuration" name="path.configuration"
value="deploy.properties" value="deploy.properties"
/> />
</Context> </Context>
Context section after: Context section after:
<Context path="" <Context path=""
docBase="/usr/local/tomcat/webapps/vivo" docBase="/usr/local/tomcat/webapps/vivo"
reloadable="true" reloadable="true"
cookies="true" > cookies="true" >
<Manager pathname="" /> <Manager pathname="" />
<Environment type="java.lang.String" override="false" <Environment type="java.lang.String" override="false"
name="path.configuration" name="path.configuration"
value="deploy.properties" value="deploy.properties"
/> />
</Context> </Context>
8. Start "Apache Tomcat" and log in to VIVO. 8. Start "Apache Tomcat" and log in to VIVO.
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
III. Ontology Changes III. Ontology Changes
A. Verify Ontology upgrade process A. Verify Ontology upgrade process
After Apache Tomcat is started, these files should be reviewed to verify that After Apache Tomcat is started, these files should be reviewed to verify that
the automated upgrade process was executed successfully. The ontology alignment the automated upgrade process was executed successfully. The ontology alignment
process will create the following files in the Tomcat webapps/vivo/WEB-INF directory: process will create the following files in the Tomcat webapps/vivo/WEB-INF directory:
ontologies/update/logs/knowledgeBaseUpdate.log ontologies/update/logs/knowledgeBaseUpdate.log
A log of a summary of updates that were made to the knowledge base and notes 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 about some recommended manual reviews. This file should end with
"Successfully finished processing ontology changes". "Successfully finished processing ontology changes".
ontologies/update/logs/knowledgeBaseUpdate.error.log ontologies/update/logs/knowledgeBaseUpdate.error.log
A log of errors that were encountered during the upgrade process. This file A log of errors that were encountered during the upgrade process. This file
should be empty if the upgrade was successful. should be empty if the upgrade was successful.
ontologies/update/changedData/removedData.n3 ontologies/update/changedData/removedData.n3
An N3 file containing all the statements that were removed from the knowledge base. An N3 file containing all the statements that were removed from the knowledge base.
ontologies/update/changedData/addedData.n3 ontologies/update/changedData/addedData.n3
An N3 file containing all the statements that were added to the knowledge base. An N3 file containing all the statements that were added to the knowledge base.
B. Ontology knowledge base manual review B. Ontology knowledge base manual review
Changes to the VIVO core ontology may require corresponding Changes to the VIVO core ontology may require corresponding
modifications of the knowledge base instance data and local ontology modifications of the knowledge base instance data and local ontology
extensions. extensions.
When Apache Tomcat starts up following the upgrade, it will initiate When Apache Tomcat starts up following the upgrade, it will initiate
a process to examine the knowledge base and apply necessary changes. a process to examine the knowledge base and apply necessary changes.
Not all of the modifications that may be required can be automated, Not all of the modifications that may be required can be automated,
so manual review of the knowledge base is recommended after the so manual review of the knowledge base is recommended after the
automated upgrade process. The automated process will make only automated upgrade process. The automated process will make only
the following types of changes: the following types of changes:
Class or Property renaming Class or Property renaming
All references to the class (in the subject or object position) will All references to the class (in the subject or object position) will
be updated to the new name. References to the property will be be updated to the new name. References to the property will be
updated to the new name. updated to the new name.
Class or Property deletion Class or Property deletion
All individuals in a deleted class will be changed to All individuals in a deleted class will be changed to
belong to the nearest available superclass (which may be owl:Thing). belong to the nearest available superclass (which may be owl:Thing).
All statements using a deleted property will be changed All statements using a deleted property will be changed
to use the nearest available superproperty. If there is no available to use the nearest available superproperty. If there is no available
superproperty then the statement will be deleted from the superproperty then the statement will be deleted from the
knowledge base. Note that all removed and added data knowledge base. Note that all removed and added data
is recorded in the files in the changedData directory. is recorded in the files in the changedData directory.
Class or Property addition Class or Property addition
If a newly added class has a superclass and there are If a newly added class has a superclass and there are
individuals in that superclass, then a note will be individuals in that superclass, then a note will be
added to the log file suggesting review of those individuals to added to the log file suggesting review of those individuals to
see if they should be reasserted in the newly added class. see if they should be reasserted in the newly added class.
If a newly added property has a superproperty and there are If a newly added property has a superproperty and there are
statements using the superproperty, then a note will be added to statements using the superproperty, then a note will be added to
the log file suggesting review of those statements to see if they the log file suggesting review of those statements to see if they
should be reasserted using the newly added property. should be reasserted using the newly added property.
Annotation property default values Annotation property default values
If a site has modified the value of a vitro annotation (such as If a site has modified the value of a vitro annotation (such as
displayRankAnnot or displayLimitAnnot) so that it is displayRankAnnot or displayLimitAnnot) so that it is
no longer using the default, then that setting will be left unchanged. 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 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 default has been changed in the new version of the ontology, then
the new default value will be propagated to the knowledge base. the new default value will be propagated to the knowledge base.
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
IV. New File Storage System IV. New File Storage System
A. Verifying the File Storage upgrade A. Verifying the File Storage upgrade
If the File Storage upgrade process is not successful, Tomcat's "vivo.all.log" If the File Storage upgrade process is not successful, Tomcat's "vivo.all.log"
log file will contain an exception listing with more information. log file will contain an exception listing with more information.
The File Storage upgrade process will create these files in the VIVO upload The File Storage upgrade process will create these files in the VIVO upload
directory: directory:
upgrade/upgradeLog.2010-00-00T00-00-00.txt upgrade/upgradeLog.2010-00-00T00-00-00.txt
A log of the upgrade process. The actual filename includes a timestamp A log of the upgrade process. The actual filename includes a timestamp
that tells when the upgrade executed. This file should be inspected that tells when the upgrade executed. This file should be inspected
for warnings or errors. The file should end with "File Storage update for warnings or errors. The file should end with "File Storage update
is complete." is complete."
upgrade/translatedImages upgrade/translatedImages
Contains the images that were translated to the new file storage system. Contains the images that were translated to the new file storage system.
upgrade/unreferencedImages upgrade/unreferencedImages
Contains the images which were in the "images" directory, but were no Contains the images which were in the "images" directory, but were no
longer referred to by any Individual. longer referred to by any Individual.
file_storage_root file_storage_root
A directory where the uploaded images are stored. Within the root, the A directory where the uploaded images are stored. Within the root, the
path to the image is derived from its unique ID and its filename. path to the image is derived from its unique ID and its filename.
file_storage_namespaces.properties file_storage_namespaces.properties
Contains the URL prefix used when serving the image files. Contains the URL prefix used when serving the image files.
B. File Storage changes B. File Storage changes
Changes to the File Storage system in VIVO result in new properties to describe Changes to the File Storage system in VIVO result in new properties to describe
the relationships involving files, and a new directory structure in which to the relationships involving files, and a new directory structure in which to
store the files. store the files.
Uploaded files are stored in the VIVO upload directory, as defined in the Uploaded files are stored in the VIVO upload directory, as defined in the
deploy.properties file. Previously, images were stored in the "images" folder deploy.properties file. Previously, images were stored in the "images" folder
of the upload directory. Now, all uploaded files will be stored in the of the upload directory. Now, all uploaded files will be stored in the
"file_storage_root" folder of the upload directory. "file_storage_root" folder of the upload directory.
Previously, image files were served from the images directory within the web Previously, image files were served from the images directory within the web
application, within Tomcat, and copied to the upload directory for backup application, within Tomcat, and copied to the upload directory for backup
purposes. Now, image files are stored only in the upload directory, and served purposes. Now, image files are stored only in the upload directory, and served
directly from there. The image directory within the web application is no directly from there. The image directory within the web application is no
longer used. longer used.
When Apache Tomcat starts up following the upgrade, it will initiate a process When Apache Tomcat starts up following the upgrade, it will initiate a process
which makes the required changes: which makes the required changes:
Initializing the file storage system Initializing the file storage system
Each file will now be assigned a unique ID, in addition to its filename. Each file will now be assigned a unique ID, in addition to its filename.
Both the ID and filename are used to store the file within the system. Both the ID and filename are used to store the file within the system.
Uploading two images with identical filenames will not cause a conflict. Uploading two images with identical filenames will not cause a conflict.
Pruning dead image references Pruning dead image references
Previous versions allowed manual editing of file paths, sometimes resulting Previous versions allowed manual editing of file paths, sometimes resulting
in erroneous information. Any image properties that refer to non-existent in erroneous information. Any image properties that refer to non-existent
files will be removed. files will be removed.
Removing unreferenced images Removing unreferenced images
Any uploaded image which is no longer referred to by an Individual will Any uploaded image which is no longer referred to by an Individual will
be removed. be removed.
Generating main images and/or thumbnails Generating main images and/or thumbnails
Each image will be represented by both a main image file and a Each image will be represented by both a main image file and a
thumbnail image file. If either of these is missing for a particular thumbnail image file. If either of these is missing for a particular
individual, it will be created. individual, it will be created.
Converting image properties on Individuals Converting image properties on Individuals
Image properties previously were simple data properties, referring to Image properties previously were simple data properties, referring to
the filename and path. These are replaced by object properties, which the filename and path. These are replaced by object properties, which
refer to the file by its unique ID. refer to the file by its unique ID.
Translating images into the new directory structure Translating images into the new directory structure
Each image file will be copied to its new location in the upload Each image file will be copied to its new location in the upload
directory. directory.
Cleaning the old image directory Cleaning the old image directory
All image files are removed from their old locations in the upload All image files are removed from their old locations in the upload
directory. directory.
Once you are satisfied that the File Storage upgrade process is successful, Once you are satisfied that the File Storage upgrade process is successful,
you may delete the "images" folder and the "upgrade" folder from the upload you may delete the "images" folder and the "upgrade" folder from the upload
directory. You may also delete the WEB-INF/images directory from within directory. You may also delete the WEB-INF/images directory from within
your Tomcat web application. your Tomcat web application.
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
V. Theme Changes V. Theme Changes
VIVO 1.1 introduces the first step in a transition from JavaServer Pages (JSPs) VIVO 1.1 introduces the first step in a transition from JavaServer Pages (JSPs)
to the FreeMarker template engine for generating web pages. As part of this to the FreeMarker template engine for generating web pages. As part of this
process, the JSP files that were used for theme customization in earlier process, the JSP files that were used for theme customization in earlier
versions of VIVO have been replaced by a set of FreeMarker templates. versions of VIVO have been replaced by a set of FreeMarker templates.
In the 1.1 install package, these files are located in In the 1.1 install package, these files are located in
/vivo/themes/vivo-basic/templates and have an ftl (for FreeMarker Template /vivo/themes/vivo-basic/templates and have an ftl (for FreeMarker Template
Language) extension. Language) extension.
Follow step A or B below, whichever is applicable to your site: Follow step A or B below, whichever is applicable to your site:
A. If you did not create a customized theme for your site in VIVO 1.0, but used A. If you did not create a customized theme for your site in VIVO 1.0, but used
the 1.0 vivo-basic theme in its original directory, you need not take any action the 1.0 vivo-basic theme in its original directory, you need not take any
in order to convert your site to the VIVO 1.1 theme. action in order to convert your site to the VIVO 1.1 theme.
B. If you created your own theme directory in VIVO 1.0, follow the steps below B. If you created your own theme directory in VIVO 1.0, follow the steps below
to upgrade your theme to VIVO 1.1. under sections "Templates," "Stylesheets," and "Site Icons" to upgrade your
theme to VIVO 1.1.
1. Copy the directory /vivo/themes/vivo-basic/templates into your theme
directory /vivo/themes/<your-theme-name>. 1. Templates
2. Follow step a or b below, whichever is applicable to your theme. Then proceed to Steps 3 and 4: a. Copy the directory /vivo/themes/vivo-basic/templates into your theme
directory /vivo/themes/<your-theme-name>.
a. If you did not apply any customizations to the JSPs in your VIVO 1.0
theme, then you do not need to apply any additional changes to the b. Follow step i or ii below, whichever is applicable to your theme.
VIVO 1.1 theme templates during the upgrade process.
i. If you did not apply any customizations to the JSPs in your VIVO
b. If you did apply customizations to the JSPs in your VIVO 1.0 theme, 1.0 theme, then you do not need to apply any additional changes
you will need to hand-replicate those modifications in the new theme to the VIVO 1.1 theme templates during the upgrade process.
template files.
ii. If you did apply customizations to the JSPs in your VIVO 1.0
The theme template content that was previously contained in three theme,you will need to hand-replicate those modifications in the
JSP files is now contained in five FTL files. The correspondence new theme template files.
between the 1.0 JSPs and the 1.1 FTLs is as follows:
The theme template content that was previously contained in
identity.jsp => identity.ftl three JSP files is now contained in five FTL files. The
menu.jsp => menu.ftl and search.ftl correspondence between the 1.0 JSPs and the 1.1 FTLs is as
footer.jsp => footer.ftl follows:
googleAnalytics.ftl is a new file included from footer.ftl to identity.jsp => identity.ftl
which you will add your site's Google Analytics Tracking Code menu.jsp => menu.ftl and search.ftl
(see section II). footer.jsp => footer.ftl
Because the FreeMarker Template Language uses many syntactic googleAnalytics.ftl is a new file included from footer.ftl to
conventions that will be familiar to template authors from JSP or which you will add your site's Google Analytics Tracking Code
other common templating systems, the translation of your JSP changes (see section II).
into the new FTLs should be relatively straightforward.
Because the FreeMarker Template Language uses many syntactic
Consult the FreeMarker Template Author's Guide at conventions that will be familiar to template authors from JSP
http://freemarker.org/docs/dgui.html and the Reference at or other common templating systems, the translation of your JSP
http://freemarker.org/docs/ref.html for complete documentation of changes into the new FTLs should be relatively straightforward.
the syntax and available built-in constructs. Template authors need
not be concerned with the Programmer's Guide or Java API documentation. Consult the FreeMarker Template Author's Guide at
http://freemarker.org/docs/dgui.html and the Reference at
3. Remove the jsp directory from your themes directory. http://freemarker.org/docs/ref.html for complete documentation
of the syntax and available built-in constructs. Template
4. VIVO 1.1 includes changes to vivo-basic stylesheets. If you modified authors need not be concerned with the Programmer's Guide or
styles in your VIVO 1.0 theme, you will not be able to simply copy the Java API documentation.
1.0 stylesheets into your 1.1 theme, because you will then lose 1.1
style upgrades that your theme should pick up. Instead, you should c. Remove the jsp directory from your themes directory.
use the vivo-basic 1.1 stylesheets as a starting point, and manually
merge your 1.0 style modifications in as needed. 2. Stylesheets
VIVO 1.1 includes changes to vivo-basic stylesheets. If you modified
styles in your VIVO 1.0 theme, you will not be able to simply copy the
1.0 stylesheets into your 1.1 theme, because you will then lose 1.1
style upgrades that your theme should pick up. Instead, you should
use the vivo-basic 1.1 stylesheets as a starting point, and manually
merge your 1.0 style modifications in as needed.
3. Site Icons
Copy the site icons from your 1.0 theme into the site_icons folder in
your 1.1 theme.