diff --git a/doc/install.txt b/doc/install.txt index ca9422ec..029bc291 100644 --- a/doc/install.txt +++ b/doc/install.txt @@ -1,300 +1,354 @@ - -------------------------------------------------------------------------------- - -This is a summary of the VIVO installation process. This and other documentation -can be found at: - - http://vivoweb.org/support - -PLEASE NOTE! -These instructions assume that you are performing a clean install, -including emptying an existing database and removing a previous installation -from the tomcat webapps directory. Product functionality may not be as expected -if you install over an existing installation of an earlier version. - -Upgrade: -If you are going to upgrade an existing service, please consult the upgrade.txt -in this directory. - -VIVO Developers: -If you are working on the VIVO source code from Subversion, the instructions -are slightly different. Please consult "developers.txt" in this directory. - -------------------------------------------------------------------------------- - - * I. Install required software - * II. Create an empty MySQL database - * III. Download the VIVO code distribution - * IV. Specify deployment properties - * V. Compile and deploy - * VI. Set Tomcat JVM Parameters - * VII. Start Tomcat - * VIII. Log in and add RDF data - * IX. Create an initial Lucene search index - * X. Setup Apache Tomcat Connector - * XI. Configure Pellet Reasoner - * XII. Was the Installation Successful? - -------------------------------------------------------------------------------- - -I. Install required software - -Before installing VIVO, make sure that the following software is installed on -the desired machine: - - * Java (SE) 1.5 or higher [http://java.sun.com/javase/downloads/] - * Apache Tomcat 5.x or higher* [http://tomcat.apache.org] - * Apache Ant [http://ant.apache.org/] - * MySQL 4.1 or higher [http://www.mysql.com/downloads/mysql/#downloads] - * Subversion client (developers only) - -------------------------------------------------------------------------------- - -II. Create an empty MySQL database - -Decide on a database name, username, and password. Log into your mysql server -and create a new database in MySQL that uses UTF-8 encoding. You will need -these values for step IV when you configure the deployment properties. At the -mysql command line you can create the database and user with these commands -substituting your values for "dbname", "username", and "password". Most of the -time, the "hostname" will equal "localhost". - -CREATE DATABASE dbname CHARACTER SET utf8; - -Grant access to a database user. For example: - -GRANT ALL ON dbname.* TO 'username'@'hostname' IDENTIFIED BY 'password'; - -Keep track of the database name, username, and password for the next step. - -------------------------------------------------------------------------------- - -III. Download the VIVO code distribution - -Download either a zip or gz file and unpack it on your web server: -ftp://download.mannlib.cornell.edu/pub/Vivo/rel-1.0.zip -ftp://download.mannlib.cornell.edu/pub/Vivo/rel-1.0.tar.gz - -------------------------------------------------------------------------------- - -IV. Specify deployment properties - -At the top level of the unpacked distribution, copy the file -example.deploy.properties to a file named simply deploy.properties. This file -sets several properties used in compilation and deployment. - - Directory where Vitro code is located - (this is used by developers, and should not be changed) -property name: vitro.core.dir -example value: ./vitro-core - - Directory where tomcat is installed -property name: tomcat.home -example value: /usr/local/tomcat - - Name of your VIVO application -property name: webapp.name -example value: vivo - - Directory where uploaded files will be stored -property name: upload.directory -example value: /usr/local/vivo/data/uploads - - Directory where the Lucene search index will be built. -property name: LuceneSetup.indexDir -example value: /usr/local/vivo/data/luceneIndex - - Specify the namespace in which the Vitro editor should create new ABox and portal resources - Note that the trailing slash is essential. -property name: Vitro.defaultNamespace -example value: http://vivo.mydomain.edu/individual/ - - Specify an SMTP host that the form will use for sending e-mail (Optional) -property name: Vitro.smtpHost -example value: smtp.servername.edu - - Specify the JDBC URL of your database. Change the end of the - URL to reflect your database name (if it is not "vivo"). -property name: VitroConnection.DataSource.url -example value: jdbc:mysql://localhost/vivo - - Change the username to match the authorized user you created in MySQL -property name: VitroConnection.DataSource.username -example value: username - - Change the password to match the password you created in MySQL -property name: VitroConnection.DataSource.password -example value: password - - Specify the name of your first admin user for the VIVO application. This user - will have an initial password of 'defaultAdmin'. This will be changed on first - login. -property name: initialAdminUser -example value: defaultAdmin - -------------------------------------------------------------------------------- - -V. Compile and deploy - -At the command line, from the top level of the unpacked distribution directory, -type: - -ant clean deploy - -to build VIVO and deploy to Tomcat's webapps directory. - -------------------------------------------------------------------------------- - -VI. Set Tomcat JVM Parameters - -Currently, VIVO copies the contents of your RDF database into memory in order -to serve Web requests quickly. (The in-memory copy and the underlying database - are kept in synch as edits are performed.) - -VIVO will require more memory than that allocated to Tomcat by default. With -most installations of Tomcat, the setenv.sh or setenv.bat file in Tomcat's bin -directory is a convenient place to set the memory parameters. For example: -export CATALINA_OPTS="-Xms1024m -Xmx1024m -XX:MaxPermSize=64m" sets Tomcat to -allocate an initial heap of 1024 megabytes, a maximum heap of 1024 megabytes, -and a PermGen space of 64 megs. 1024 megabytes is a minimum practical heap size -for production installations storing data for large academic institutions, and -additional heap space is preferable. For testing with small sets of data, 256m -to 512m should be sufficient. - -If an OutOfMemoryError is encountered during VIVO execution, increasing the -heap parameters is the typical remedy. - -------------------------------------------------------------------------------- - -VII. Start Tomcat - -Most Tomcat installations can be started by running startup.sh or startup.bat -in Tomcat's bin directory. Point your browser to http://localhost:8080/vivo/ -to test the application. - -If Tomcat does not start up, or the VIVO application is not visible, check the -catalina.out file in Tomcat's logs directory. (More information about detailed -error logging to be added here.) - -------------------------------------------------------------------------------- - -VIII. Log in and add RDF data - -If the startup was successful, you will see a relatively empty screen with the -VIVO logo in the header. Click the "Log in" link near the upper right corner. -Log in with the initialAdminUser username you set up in step IV. The initial -password the initialAdminUser is defaultAdmin. On first login, you will be -prompted to select a new password and verify it a second time. - -After verifying your new password, you will be presented with a menu of -editing options. Here you can create OWL classes, object properties, datatype -properties, and configure the display of data. Currently, any classes you wish -to make visible on your website must be part of a Class Group, and there a -number of visibility and display options available for each ontology entity. -More documentation is forthcoming. - -VIVO comes with an ontology, but you may also upload another ontology from an -RDF file. Under the "Advanced Data Tools", click "Add/Remove RDF Data." Note -that Vitro currently works best with OWL-DL ontologies and has only limited -support for pure RDF data. You can enter a URL pointing to the RDF data you -wish to load or upload a file on your local machine. Ensure that the "add RDF" -radio button is selected. You will also likely want to check "create -classgroups automatically." Clicking the "Index" tab in the navigation bar at -the top left of the page will show a simple index of the knowledge base. -See more documentation for configuring VIVO at vivoweb.org. - -------------------------------------------------------------------------------- - -IX. Create an initial Lucene search index - -Invoke the indexing servlet by requesting http://localhost:8080/vivo/SearchIndex - -You will not see any output to the browser (though this will change in future -versions). When your browser switches to a blank screen, the indexing has -completed and the search box on the Vitro portal will be usable. Individuals -that are created, edited, or deleted from the Vitro editing interface will -trigger incremental updates of the search index. - -------------------------------------------------------------------------------- - -X. Setup Apache Tomcat Connector - -It is recommend that a Tomcat Connector, such as mod_jk be used to ensure that -the site address does not include the port number and any extraneous Tomcat -context. - -For example - http://example.com instead of http://example.com:8080/vivo - -Using the mod_jk connector allows for communication between Tomcat and the -primary web server. The "Quick Start HowTo" on the Apache site -http://tomcat.apache.org/connectors-doc/generic_howto/quick.html describes -the minimum server configurations for several popular web servers. - -------------------------------------------------------------------------------- - -XI. Configure Pellet Reasoner - -VIVO uses the ÒPelletÓ engine to perform reasoning, which runs in the -background at startup and also when the knowledge base is edited. VIVO -continues serving pages while the reasoner continues working; when it finishes, -the new inferences appear. Inferred statements are cached in a database graph -so that they are available immediately when VIVO is restarted. - -By default, ÒPelletÓ is fed only an incomplete view of your ontology and only -certain inferences are materialized. These include rdf:type, -rdfs:subClassOf,owl:equivalentClass, and owl:disjointWith. This mode is -typically suitable for ontologies with a lot of instance data. If you would -like to keep the default mode, skip to the next step. - -To enable "complete" OWL inference (materialize all significant entailed -statements), openvitro-core/webapp/config/web.xml and search for -PelletReasonerSetup. - -Then change the name of the listener class to PelletReasonerSetupComplete. -Because "complete" reasoning can be very resource intensive, there is also an -option to materialize nearly all inferences except owl:sameAs and -owl:differentFrom. - -This is enabled by specifying PelletReasonerSetupPseudocomplete. For ontologies -with large numbers of individuals, this mode can offer enormous performance -improvements over the "complete" mode. - -Finally, a class called PelletReasonerSetupPseudocompleteIgnoreDataproperties -is provided to improve performance on ontologies with large literals where -datatype property entailments are not needed. - -------------------------------------------------------------------------------- - -XII. Was the installation successful? - -If you have completed the previous steps, you have good indications that the -installation was successful. - -* Step VII showed that Tomcat recognized the webapp, and that the webapp was - able to present the initial page. -* Step VIII verified that you can log in to the administrator account. -* Step IX initialized the Lucene Search system. Though there is very little - feedback for a successful installation, there are dramatic indications - for failures. - -Here is a simple test to see whether the ontology files were loaded: -* Point your browser to http://localhost:8080/vivo, and click the "Log in" link - near the upper right corner. Log in with the initialAdminUser username you - set up in step IV. If this is your first time logging in, you will be - prompted to change the password. -* Click on the "Index" link on the upper left, below the logo. You should see - a "locations" section, with links for "Country" and "Geographic Location". - The index is built in a background thread, so on your first login, you may - see an empty index instead. Refresh the page periodically to see whether - the index will be populated. This may take some time: with VIVO installed - on a modest laptop computer, loading the ontology files and building the - index took more than 5 minutes from the time that Tomcat was started. -* Click on the "Country" link. You should see an alphabetical list of the - countries of the world. - -Finally, test the search index. -* The search box is on the right side, directly opposite the "Index" link. - Type the word "Afghanistan" into the box, and click on the "Search" - button.You should see a page of results, with links to countries that - border Afghanistan, entities that include Afghanistan, and to - Afghanistan itself. \ No newline at end of file + +------------------------------------------------------------------------------- + +This document is a summary of the VIVO installation process. This and other documentation +can be found at: + + http://vivoweb.org/support + +PLEASE NOTE! +These instructions assume that you are performing a clean install, +including emptying an existing database and removing a previous installation +from the Tomcat webapps directory. Product functionality may not be as expected +if you install over an existing installation of an earlier version. + +Upgrade: +If you are going to upgrade an existing service, please consult the upgrade.txt +in this directory. + +VIVO Developers: +If you are working on the VIVO source code from Subversion, the instructions +are slightly different. Please consult developers.txt in this directory. + +------------------------------------------------------------------------------- + + * I. Install required software + * II. Create an empty MySQL database + * III. Download the VIVO code distribution + * IV. Specify deployment properties + * V. Compile and deploy + * VI. Set Tomcat JVM Parameters + * VII. Start Tomcat + * VIII. Log in and add RDF data + * IX. Create an initial Lucene search index + * X. Setup Apache Tomcat Connector + * XI. Configure Pellet Reasoner + * XII. Was the Installation Successful? + +------------------------------------------------------------------------------- + +I. Install required software + +Before installing VIVO, make sure that the following software is installed on +the desired machine: + + * Java (SE) 1.5 or higher [http://java.sun.com] + * Apache Tomcat 5.x or higher [http://tomcat.apache.org] + * Apache Ant [http://ant.apache.org] + * MySQL 4.1 or higher [http://www.mysql.com] + +------------------------------------------------------------------------------- + +II. Create an empty MySQL database + +Decide on a database name, username, and password. Log into your MySQL server +and create a new database in MySQL that uses UTF-8 encoding. You will need +these values for step IV when you configure the deployment properties. At the +mysql command line you can create the database and user with these commands +substituting your values for "dbname", "username", and "password". Most of the +time, the "hostname" will equal "localhost". + +CREATE DATABASE dbname CHARACTER SET utf8; + +Grant access to a database user. For example: + +GRANT ALL ON dbname.* TO 'username'@'hostname' IDENTIFIED BY 'password'; + +Keep track of the database name, username, and password for Step IV. + +------------------------------------------------------------------------------- + +III. Download the VIVO code distribution + +Download either a zip or gz file and unpack it on your web server: +ftp://download.mannlib.cornell.edu/pub/Vivo/rel-1.0.zip +ftp://download.mannlib.cornell.edu/pub/Vivo/rel-1.0.tar.gz + +------------------------------------------------------------------------------- + +IV. Specify deployment properties + +At the top level of the unpacked distribution, copy the file +example.deploy.properties to a file named simply deploy.properties. This file +sets several properties used in compilation and deployment. + + 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/ + Note: The namespace must end with "individual/" (including the + trailing slash). +property name: Vitro.defaultNamespace +example value: 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. +property name: vitro.core.dir +example value: ./vitro-core + + Directory where tomcat is installed +property name: tomcat.home +example value: /usr/local/tomcat + + Name of your VIVO application +property name: webapp.name +example value: vivo + + Directory where uploaded files will be stored. Depending on + your permissions and who Tomcat is running as, you may need + to create these directories ahead of time. +property name: upload.directory +example value: /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 these directories ahead of time. +property name: LuceneSetup.indexDir +example value: /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. +property name: Vitro.smtpHost +example value: smtp.servername.edu + + Specify the JDBC URL of your database. Change the end of the + URL to reflect your database name (if it is not "vivo"). +property name: VitroConnection.DataSource.url +example value: jdbc:mysql://localhost/vivo + + Change the username to match the authorized user you created in MySQL +property name: VitroConnection.DataSource.username +example value: username + + Change the password to match the password you created in MySQL +property name: VitroConnection.DataSource.password +example value: password + + 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. +property name: initialAdminUser +example value: defaultAdmin + +------------------------------------------------------------------------------- + +V. Compile and deploy + +At the command line, from the top level of the unpacked distribution directory, +type: + +ant all + +to build VIVO and deploy to Tomcat's webapps directory. + +------------------------------------------------------------------------------- + +VI. Set Tomcat JVM Parameters + +Currently, VIVO copies the contents of your RDF database into memory in order +to serve Web requests quickly. (The in-memory copy and the underlying database + are kept in synch as edits are performed.) + +VIVO will require more memory than that allocated to Tomcat by default. With +most installations of Tomcat, the setenv.sh or setenv.bat file in Tomcat's bin +directory is a convenient place to set the memory parameters. + +For example: + +export CATALINA_OPTS="-Xms1024m -Xmx1024m -XX:MaxPermSize=64m" + +This sets Tomcat to allocate an initial heap of 1024 megabytes, a maximum heap +of 1024 megabytes, and a PermGen space of 64 megs. 1024 megabytes is a minimum +practical heap size for production installations storing data for large academic +institutions, and additional heap space is preferable. For testing with small +sets of data, 256m to 512m should be sufficient. + +If an OutOfMemoryError is encountered during VIVO execution, increasing the +heap parameters and restarting Tomcat is the typical remedy. + +------------------------------------------------------------------------------- + +VII. Start Tomcat + +Most Tomcat installations can be started by running startup.sh or startup.bat +in Tomcat's bin directory. Point your browser to http://localhost:8080/vivo/ +to test the application. + +If Tomcat does not start up, or the VIVO application is not visible, check the +catalina.out file in Tomcat's logs directory. + +------------------------------------------------------------------------------- + +VIII. Log in and add RDF data + +If the startup was successful, you will see a welcome message informing you +that you have successfully installed VIVO. Click the "Log in" link near the +upper right corner. Log in with the initialAdminUser username you set up in +step IV. The initial password the initialAdminUser is defaultAdmin. On first +login, you will be prompted to select a new password and verify it a second +time. + +After verifying your new password, you will be presented with a menu of +editing options. Here you can create OWL classes, object properties, data +properties, and configure the display of data. Currently, any classes you wish +to make visible on your website must be part of a class group, and there a +number of visibility and display options available for each ontology entity. + +VIVO comes with a core VIVO ontology, but you may also upload other ontologies +from an RDF file. Under the "Advanced Data Tools", click "Add/Remove RDF Data." +Note that Vitro currently works best with OWL-DL ontologies and has only limited +support for pure RDF data. You can enter a URL pointing to the RDF data you +wish to load or upload a file on your local machine. Ensure that the "add RDF" +radio button is selected. You will also likely want to check "create +classgroups automatically." Clicking the "Index" tab in the navigation bar at +the top left of the page will show a simple index of the knowledge base. +See more documentation for configuring VIVO at http://vivoweb.org/support. + +------------------------------------------------------------------------------- + +IX. Set the Contact Email Address (if using "Contact Us" form) + +If you have configured your application to use the "Contact Us" feature in Step +IV (Vitro.smtpHost), you will also need to add an email address to the VIVO +application. This is the email that the contact form submits to. It can be a +list server or an individual's email address. + +Log in as a system administrator. Navigate to the "Site Admin" table of contents +(link in the right side of the header). Go to "Site Information" (under "Site +Configuration"). In the "Site Information Editing Form", enter a functional +email address in the field "Contact Email Address." and submit the change. + +If you set the Vitro.smtpHost in Step IV and do NOT provide an email address +in this step, your users will receive a java error in the interface. + +------------------------------------------------------------------------------- + +X. Create an initial Lucene search index + +Invoke the indexing servlet by requesting http://localhost:8080/vivo/SearchIndex + +You will not see any output to the browser (though this will change in future +versions). When your browser switches to a blank screen, the indexing has +completed and the search box on the Vitro portal will be usable. Individuals +that are created, edited, or deleted from the Vitro editing interface will +trigger incremental updates of the search index. + +------------------------------------------------------------------------------- + +XI. Set up Apache Tomcat Connector + +It is recommended that a Tomcat Connector such as mod_jk be used to ensure that +the site address does not include the port number (e.g. 8080) and an additional +reference to the Tomcat context name (e.g. /vivo). + +For example - http://example.com instead of http://example.com:8080/vivo + +Using the mod_jk connector allows for communication between Tomcat and the +primary web server. The "Quick Start HowTo" on the Apache site +http://tomcat.apache.org/connectors-doc/generic_howto/quick.html describes +the minimum server configurations for several popular web servers. + +------------------------------------------------------------------------------- + +XII. Configure Pellet Reasoner + +VIVO uses the Pellet engine to perform reasoning, which runs in the +background at startup and also when the knowledge base is edited. VIVO +continues serving pages while the reasoner continues working; when the +reasoner finishes, the new inferences appear. Inferred statements are cached +in a database graph so that they are available immediately when VIVO is restarted. + +By default, Pellet is fed only an incomplete view of your ontology and only +certain inferences are materialized. These include rdf:type, +rdfs:subClassOf,owl:equivalentClass, and owl:disjointWith. This mode is +typically suitable for ontologies with a lot of instance data. If you would +like to keep the default mode, skip to the next step. + +To enable "complete" OWL inference (materialize all significant entailed +statements), open "vitro-core/webapp/config/web.xml" and search for +PelletReasonerSetup. + +Then change the name of the listener class to PelletReasonerSetupComplete. +Because "complete" reasoning can be very resource intensive, there is also an +option to materialize nearly all inferences except owl:sameAs and +owl:differentFrom. + +This is enabled by specifying PelletReasonerSetupPseudocomplete. For ontologies +with large numbers of individuals, this mode can offer enormous performance +improvements over the "complete" mode. + +Finally, a class called PelletReasonerSetupPseudocompleteIgnoreDataproperties +is provided to improve performance on ontologies with large literals where data +property entailments are not needed. + +------------------------------------------------------------------------------- + +XIII. Was the installation successful? + +If you have completed the previous steps, you have good indications that the +installation was successful. + +* Step VII showed that Tomcat recognized the webapp, and that the webapp was + able to present the initial page. +* Step VIII verified that you can log in to the administrator account. +* Step X initialized the Lucene Search system. Though there is very little + feedback for a successful installation, there are dramatic indications + for failures. + +Here is a simple test to see whether the ontology files were loaded: +* Click on the "Index" link on the upper left, below the logo. You should see + a "locations" section, with links for "Country" and "Geographic Location". + The index is built in a background thread, so on your first login, you may + see an empty index instead. Refresh the page periodically to see whether + the index will be populated. This may take some time: with VIVO installed + on a modest laptop computer, loading the ontology files and building the + index took more than 5 minutes from the time that Tomcat was started. +* Click on the "Country" link. You should see an alphabetical list of the + countries of the world. + +Here is a test to see whether your system is configured to serve linked data: +* Point your browser to the home page of your website, and click the "Log in" link + near the upper right corner. Log in with the initialAdminUser username you + set up in step IV. If this is your first time logging in, you will be + prompted to change the password. +* After you have successfully logged in, click "site admin" in the upper right + corner. In the drop down under "Data Input", select "Faculty Member(core)" + and click the "Add individual of this class" button. +* Enter the name "test individual" under the field "Individual Name", scroll to + the bottom, and click "Create New Record".You will be taken to the "Individual + Control Panel". Make note of the value of the field "URI", it will be used in + the next step. +* Open a new web browser or browser tab to the page "http://marbles.sourceforge.net/". + In the pink box on that page enter the URI of the individual you created in the + previous step and click "open." +* In the resulting page search for the URI of the "test individual". You should + find it towards the bottom of the page next to a red dot followed by "redirect (303)" + This indicates that you are successfully serving linked RDF data. + If the URI of the "test individual" is followed by "failed (400)" you are not + successfully serving linked data. + +Finally, test the search index (assuming you have created the initial Lucene +index in Step X). +* The search box is on the right side, directly opposite the "Index" link. + Type the word "Australia" into the box, and click on the "Search" + button.You should see a page of results, with links to countries that + border Australia, individuals that include Australia, and to + Australia itself. \ No newline at end of file diff --git a/doc/upgrade.txt b/doc/upgrade.txt index c6b4fd9f..fb42ca56 100644 --- a/doc/upgrade.txt +++ b/doc/upgrade.txt @@ -1,37 +1,51 @@ + +------------------------------------------------------------------------------- + Upgrading NIH VIVO -Steps to Upgrade from Version 1 Release 0.9 to Release 1.0 +Steps to Upgrade from Release 1 Version 0.9 to Release 1 Version 1.0 This file provides a short description of the steps involved in upgrading your -installation of �NIH VIVO� from Version 1 Release 0.9 to Version 1 Release 1.0. +installation of NIH VIVO from Release 1 Version 0.9 to Release 1 Version 1.0. +This and other documentation can be found at: ----------- -Before Performing the Upgrade ----------- +http://vivoweb.org/support -The bullet points listed below are important to know before beginning the -upgrade process. +Installation: +If you need to do a fresh install, please consult the install.txt in this +directory. -The upgrade process is like the original install process with the following +------------------------------------------------------------------------------- + +I. Before Performing the Upgrade +II. The Upgrade Process +III. Ontology 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 re-install MySQL or re-create the MySQL database. Please ensure that + +* 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, initialize the Lucene Search Index, or - re-configure 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 previously set, NOT the password in deploy.properties. * Any image files that have been uploaded into the system will not be disturbed by the upgrade. -* The first time that Apache Tomcat starts up after the upgrade, it will - initiate a process which modifies the data in the model, aligning the data - with the revised ontology. For the most part, data in the model will not be - lost. See the section on "Ontology Changes" (below) for more information. -* If you make any changes to the application, they should be made in the source - directory and deployed, and not made directly within Apache Tomcat. +* 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 Process ----------- +------------------------------------------------------------------------------- + +II. The Upgrade Process + 1. Ensure that backups are created of the Tomcat webapps directory, the original source directory, and the MySQL database. @@ -60,42 +74,93 @@ The Process Note: Version 1 Release 0.9 contained two directories called "modifications" and "ontology". These directories have been combined into a directory called "productMods". If your site has made changes to the ontology - ensure that those changes are moved into "productMods". + ensure that those changes are moved into the appropriate subdirectory of + "productMods". -5. If you had modified web.xml to configure the "Pellet Reasoner" (as described + Note: 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. + +5. If you had modified web.xml to configure the Pellet Reasoner (as described in the installation instructions), repeat that modification. -6. Run ant deploy by typing: ant +6. Run ant deploy by typing: ant deploy -7. Lastly, start "Apache Tomcat" and login to VIVO. +7. Start "Apache Tomcat" and login to VIVO. ----------- -Ontology Changes ----------- +8. Rebuild the Lucene search index as described in step IX of +the install process. This step will ensure that changes in the RDF +data to align with the latest version of the core ontology +will be reflected in the search index. -There are changes in the ontology that may require sites to modify the data in -their model. +------------------------------------------------------------------------------- -For example, if there is a split in a combined class -(e.g., SchoolOrCollegeWithinUniversity into School and College) it is -impossible to determine which class of individuals were added to the combined -class and which class those individuals should be assigned. +III. Ontology Changes -Note: When "Apache Tomcat" starts up following the upgrade, it will initiate -a process which may modify the data in the model, to align the data to the -current ontology. Refer to your institutions ontology team representative for -additional information on ontology changes affecting data prior to performing -the upgrade. -The ontology alignment process will create these files in the Tomcat webapps directory: -* WEB-INF/ontologies/update/logs/knowledgeBaseUpdate.log - a log of updates that were made to the knowledge base and notes about some - of the recommended manual reviews. -* WEB-INF/ontologies/update/logs/knowledgeBaseUpdate.error.log - a log of errors that were encoundered during the upgrade process. -* WEB-INF/ontologies/update/removedData/removedData.rdf - a file containing the stataements that were removed from the data model. -* WEB-INF/ontologies/update/addedData/addedData.rdf - a file containing the statements that were added to the data model. -After Apache Tomcat is started, you should review these files to see whether -you need to edit any data in response to the ontology changes. +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 + It 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. + +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.rdf + a file containing all the statements that were removed from the knowledge base. + +ontologies/update/changedData/addedData.rdf + a file containing all the statements that were added to the knowledge base. + + +After Apache Tomcat is started, these files should be reviewed to verify that +the automated upgrade process was executed successfully.