diff --git a/doc/upgrade-1.1.txt b/doc/upgrade-1.1.txt index 305dbabb..4021296a 100644 --- a/doc/upgrade-1.1.txt +++ b/doc/upgrade-1.1.txt @@ -1,358 +1,370 @@ - -------------------------------------------------------------------------------- - -Upgrading NIH VIVO - -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 -installation of NIH VIVO from Release 1 Version 1.0 to Release 1 Version 1.1. -This and other documentation can be found at: - -http://vivoweb.org/support - -Installation: -If you need to do a fresh install, please consult the install.txt in this -directory. - -------------------------------------------------------------------------------- - -I. Before Performing the Upgrade -II. The Upgrade Process -III. Ontology Upgrade - A. Verify Ontology upgrade process - B. Ontology knowledge base manual r -IV. New File Storage System - A. Verifying the File Storage upgrade - B. File Storage changes -V. Theme Changes - -------------------------------------------------------------------------------- - -I. Before Performing 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 -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 or reconfigure the Apache HTTP Server. -* First-time login of the administrator account will use the password - previously set, NOT the password in deploy.properties. -* 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 "Ontology Changes" - below for more information. -* The first time Apache Tomcat starts up after the upgrade, it will - initiate a process that modifies the uploaded files directory (images), to - align the uploaded files with the revised file storage scheme. See the - section on "File Storage Changes" below for more information. - -------------------------------------------------------------------------------- - -II. The Upgrade Process - - -1. Ensure that backups are created of the Tomcat webapps directory, the - original source directory, the MySQL database, and the uploaded files - directory (images). - -2. Download the new distribution file and unpack it into a new source - directory. - -3. Create deploy.properties, using the same values as in your previous - installation. - -4. Apply any 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 - Apache Tomcat webapp. - - 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. - - At a minimum it will be necessary 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 your institution's tracking code, see the - VIVO Google Analytics wiki page: - https://confluence.cornell.edu/display/ennsrd/Google+Analytics+for+UI - - ************************************************************************ - -5. If you had modified web.xml to configure the Pellet Reasoner (as described - in the installation instructions), repeat that modification. - -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 - 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 before: - - - - - - Context section after: - - - - - - -8. Start "Apache Tomcat" and log in to VIVO. - -------------------------------------------------------------------------------- - -III. Ontology Changes - -A. 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.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 - "Successfully finished processing ontology changes". - -ontologies/update/logs/knowledgeBaseUpdate.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. - -B. 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 individuals in a deleted class will be changed to - belong to the nearest available superclass (which may be owl:Thing). - - 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. - - Class or Property addition - If a newly added class has a superclass and there are - individuals in that superclass, then a note will be - added to the log file suggesting review of those individuals to - see if they should be reasserted in the newly added class. - - If a newly added property has a superproperty and there are - statements using the superproperty, then a note will be added to - the log file suggesting review of those statements to see if they - should be reasserted using the newly added property. - - 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. - -------------------------------------------------------------------------------- - -IV. New File Storage System - -A. Verifying the File Storage upgrade - -If the File Storage upgrade process is not successful, Tomcat's "vivo.all.log" -log file will contain an exception listing with more information. - -The File Storage upgrade process will create these files in the VIVO upload -directory: - -upgrade/upgradeLog.2010-00-00T00-00-00.txt - A log of the upgrade process. The actual filename includes a timestamp - that tells when the upgrade executed. This file should be inspected - for warnings or errors. The file should end with "File Storage update - is complete." - -upgrade/translatedImages - Contains the images that were translated to the new file storage system. - -upgrade/unreferencedImages - Contains the images which were in the "images" directory, but were no - longer referred to by any Individual. - -file_storage_root - 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. - -file_storage_namespaces.properties - Contains the URL prefix used when serving the image files. - -B. File Storage changes - -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 -store the files. - -Uploaded files are stored in the VIVO upload directory, as defined in the -deploy.properties file. Previously, images were stored in the "images" folder -of the upload directory. Now, all uploaded files will be stored in the -"file_storage_root" folder of the upload directory. - -Previously, image files were served from the images directory within the web -application, within Tomcat, and copied to the upload directory for backup -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 -longer used. - -When Apache Tomcat starts up following the upgrade, it will initiate a process -which makes the required changes: - - Initializing the file storage system - 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. - Uploading two images with identical filenames will not cause a conflict. - - Pruning dead image references - Previous versions allowed manual editing of file paths, sometimes resulting - in erroneous information. Any image properties that refer to non-existent - files will be removed. - - Removing unreferenced images - Any uploaded image which is no longer referred to by an Individual will - be removed. - - Generating main images and/or thumbnails - 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 - individual, it will be created. - - Converting image properties on Individuals - Image properties previously were simple data properties, referring to - the filename and path. These are replaced by object properties, which - refer to the file by its unique ID. - - Translating images into the new directory structure - Each image file will be copied to its new location in the upload - directory. - - Cleaning the old image directory - All image files are removed from their old locations in the upload - directory. - -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 -directory. You may also delete the WEB-INF/images directory from within -your Tomcat web application. - -------------------------------------------------------------------------------- - -V. Theme Changes - -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 -process, the JSP files that were used for theme customization in earlier -versions of VIVO have been replaced by a set of FreeMarker templates. -In the 1.1 install package, these files are located in -/vivo/themes/vivo-basic/templates and have an ftl (for FreeMarker Template -Language) extension. - -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 -the 1.0 vivo-basic theme in its original directory, you need not take any 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 -to upgrade your theme to VIVO 1.1. - - 1. Copy the directory /vivo/themes/vivo-basic/templates into your theme - directory /vivo/themes/. - - 2. Follow step a or b below, whichever is applicable to your theme. Then proceed to Steps 3 and 4: - - 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 - VIVO 1.1 theme templates during the upgrade process. - - b. If you did apply customizations to the JSPs in your VIVO 1.0 theme, - you will need to hand-replicate those modifications in the new theme - template files. - - The theme template content that was previously contained in three - JSP files is now contained in five FTL files. The correspondence - between the 1.0 JSPs and the 1.1 FTLs is as follows: - - identity.jsp => identity.ftl - menu.jsp => menu.ftl and search.ftl - footer.jsp => footer.ftl - - googleAnalytics.ftl is a new file included from footer.ftl to - which you will add your site's Google Analytics Tracking Code - (see section II). - - Because the FreeMarker Template Language uses many syntactic - conventions that will be familiar to template authors from JSP or - other common templating systems, the translation of your JSP changes - into the new FTLs should be relatively straightforward. - - Consult the FreeMarker Template Author's Guide at - http://freemarker.org/docs/dgui.html and the Reference at - http://freemarker.org/docs/ref.html for complete documentation of - the syntax and available built-in constructs. Template authors need - not be concerned with the Programmer's Guide or Java API documentation. - - 3. Remove the jsp directory from your themes directory. - - 4. 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. \ No newline at end of file + +------------------------------------------------------------------------------- + +Upgrading NIH VIVO + +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 +installation of NIH VIVO from Release 1 Version 1.0 to Release 1 Version 1.1. +This and other documentation can be found at: + +http://vivoweb.org/support + +Installation: +If you need to do a fresh install, please consult the install.txt in this +directory. + +------------------------------------------------------------------------------- + +I. Before Performing the Upgrade +II. The Upgrade Process +III. Ontology Upgrade + A. Verify Ontology upgrade process + B. Ontology knowledge base manual r +IV. New File Storage System + A. Verifying the File Storage upgrade + B. File Storage changes +V. Theme Changes + +------------------------------------------------------------------------------- + +I. Before Performing 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 +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 or reconfigure the Apache HTTP Server. +* First-time login of the administrator account will use the password + previously set, NOT the password in deploy.properties. +* 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 "Ontology Changes" + below for more information. +* The first time Apache Tomcat starts up after the upgrade, it will + initiate a process that modifies the uploaded files directory (images), to + align the uploaded files with the revised file storage scheme. See the + section on "File Storage Changes" below for more information. + +------------------------------------------------------------------------------- + +II. The Upgrade Process + + +1. Ensure that backups are created of the Tomcat webapps directory, the + original source directory, the MySQL database, and the uploaded files + directory (images). + +2. Download the new distribution file and unpack it into a new source + directory. + +3. Create deploy.properties, using the same values as in your previous + installation. + +4. Apply any 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 + Apache Tomcat webapp. + + 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. + + At a minimum it will be necessary 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 your institution's tracking code, see the + VIVO Google Analytics wiki page: + https://confluence.cornell.edu/display/ennsrd/Google+Analytics+for+UI + + ************************************************************************ + +5. If you had modified web.xml to configure the Pellet Reasoner (as described + in the installation instructions), repeat that modification. + +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 + 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 before: + + + + + + Context section after: + + + + + + +8. Start "Apache Tomcat" and log in to VIVO. + +------------------------------------------------------------------------------- + +III. Ontology Changes + +A. 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.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 + "Successfully finished processing ontology changes". + +ontologies/update/logs/knowledgeBaseUpdate.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. + +B. 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 individuals in a deleted class will be changed to + belong to the nearest available superclass (which may be owl:Thing). + + 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. + + Class or Property addition + If a newly added class has a superclass and there are + individuals in that superclass, then a note will be + added to the log file suggesting review of those individuals to + see if they should be reasserted in the newly added class. + + If a newly added property has a superproperty and there are + statements using the superproperty, then a note will be added to + the log file suggesting review of those statements to see if they + should be reasserted using the newly added property. + + 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. + +------------------------------------------------------------------------------- + +IV. New File Storage System + +A. Verifying the File Storage upgrade + +If the File Storage upgrade process is not successful, Tomcat's "vivo.all.log" +log file will contain an exception listing with more information. + +The File Storage upgrade process will create these files in the VIVO upload +directory: + +upgrade/upgradeLog.2010-00-00T00-00-00.txt + A log of the upgrade process. The actual filename includes a timestamp + that tells when the upgrade executed. This file should be inspected + for warnings or errors. The file should end with "File Storage update + is complete." + +upgrade/translatedImages + Contains the images that were translated to the new file storage system. + +upgrade/unreferencedImages + Contains the images which were in the "images" directory, but were no + longer referred to by any Individual. + +file_storage_root + 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. + +file_storage_namespaces.properties + Contains the URL prefix used when serving the image files. + +B. File Storage changes + +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 +store the files. + +Uploaded files are stored in the VIVO upload directory, as defined in the +deploy.properties file. Previously, images were stored in the "images" folder +of the upload directory. Now, all uploaded files will be stored in the +"file_storage_root" folder of the upload directory. + +Previously, image files were served from the images directory within the web +application, within Tomcat, and copied to the upload directory for backup +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 +longer used. + +When Apache Tomcat starts up following the upgrade, it will initiate a process +which makes the required changes: + + Initializing the file storage system + 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. + Uploading two images with identical filenames will not cause a conflict. + + Pruning dead image references + Previous versions allowed manual editing of file paths, sometimes resulting + in erroneous information. Any image properties that refer to non-existent + files will be removed. + + Removing unreferenced images + Any uploaded image which is no longer referred to by an Individual will + be removed. + + Generating main images and/or thumbnails + 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 + individual, it will be created. + + Converting image properties on Individuals + Image properties previously were simple data properties, referring to + the filename and path. These are replaced by object properties, which + refer to the file by its unique ID. + + Translating images into the new directory structure + Each image file will be copied to its new location in the upload + directory. + + Cleaning the old image directory + All image files are removed from their old locations in the upload + directory. + +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 +directory. You may also delete the WEB-INF/images directory from within +your Tomcat web application. + +------------------------------------------------------------------------------- + +V. Theme Changes + +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 +process, the JSP files that were used for theme customization in earlier +versions of VIVO have been replaced by a set of FreeMarker templates. +In the 1.1 install package, these files are located in +/vivo/themes/vivo-basic/templates and have an ftl (for FreeMarker Template +Language) extension. + +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 +the 1.0 vivo-basic theme in its original directory, you need not take any +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 +under sections "Templates," "Stylesheets," and "Site Icons" to upgrade your +theme to VIVO 1.1. + + 1. Templates + + a. Copy the directory /vivo/themes/vivo-basic/templates into your theme + directory /vivo/themes/. + + b. Follow step i or ii below, whichever is applicable to your theme. + + i. 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 VIVO 1.1 theme templates during the upgrade process. + + ii. If you did apply customizations to the JSPs in your VIVO 1.0 + theme,you will need to hand-replicate those modifications in the + new theme template files. + + The theme template content that was previously contained in + three JSP files is now contained in five FTL files. The + correspondence between the 1.0 JSPs and the 1.1 FTLs is as + follows: + + identity.jsp => identity.ftl + menu.jsp => menu.ftl and search.ftl + footer.jsp => footer.ftl + + googleAnalytics.ftl is a new file included from footer.ftl to + which you will add your site's Google Analytics Tracking Code + (see section II). + + Because the FreeMarker Template Language uses many syntactic + conventions that will be familiar to template authors from JSP + or other common templating systems, the translation of your JSP + changes into the new FTLs should be relatively straightforward. + + Consult the FreeMarker Template Author's Guide at + http://freemarker.org/docs/dgui.html and the Reference at + http://freemarker.org/docs/ref.html for complete documentation + of the syntax and available built-in constructs. Template + authors need not be concerned with the Programmer's Guide or + Java API documentation. + + c. Remove the jsp directory from your themes directory. + + 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. \ No newline at end of file