VIVO Release 1 V1.2 Installation Guide

-

+ January 28, 2011 -

+
Missing pieces and fixes
  • - SDB - any checks? (BL/SM) -
    • -
  • - Theme changes, file locations, branding issues (NC/MB) -
    • -
  • - Fix styles on file, dir, parameters name styles + Add release announcemnet
  • Link to upgrade pdf online at SF @@ -70,7 +64,7 @@

    Steps to Installation

    -
      +
      1. Install required software
        2. @@ -133,19 +127,20 @@

- Be sure to setup the environment variables for "JAVA_HOME" and "ANT_HOME" + Be sure to setup the environment variables for + and ANT_HOME and add the executables to your path per your operating system and installation directions from the software support web sites.

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". + 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;
@@ -164,29 +159,29 @@
                 

             
             

-                Download the VIVO application source as either rel-1.1.1.zip or
-                rel-1.1.1.gz file and unpack it on your web
-                server:
+                Download the VIVO application source as either rel-1.2.zip
+                or rel-1.2.gz
+                file and unpack it on your web server:
                 

                 http://vivoweb.org/download
             

             
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".
+                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.
             

             

                 Windows:
-                For those installing on Windows operating system, include the
-                windows drive and use the forward slash "/" and not the back slash "\"
-                in the directory locations, e.g. "c:/tomcat".
+                For those installing on Windows operating system, include the 
+                windows drive and use the forward slash "/" and not the back slash "\" 
+                in the directory locations, e.g. c:/tomcat.
             

             

                 External authentication:
                 If you want to use an external authentication system like Shibboleth or 
-                CUWebAuth, you will need to set two additional properties in this file. 
-                See the section below entitled "Using an External Authentication System with VIVO".
+                CUWebAuth, you will need to set two additional properties in this file.  
+                See the section below entitled Using an External Authentication System with VIVO.
             

             
@@ -202,14 +197,12 @@
                         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  
+                        VIVO's default namespace must have certain structure and begin with the public  
                         web address of the VIVO installation. For example, if the web address of a VIVO 
                         installation is "http://vivo.example.edu/" the default namespace must be set to  
                         "http://vivo.example.edu/individual/" in order to support linked data. Similarly, 
                         if VIVO is installed at "http://www.example.edu/vivo" the default namespace must be  
-                        set to "http://www.example.edu/vivo/individual/" 
-                        

-                        * The namespace must end with "individual/" (including the trailing slash).
+                        set to "http://www.example.edu/vivo/individual/" 
* The namespace must end with "individual/" (including the trailing slash).

@@ -409,7 +402,7 @@
                 
@@ -504,8 +497,7 @@
                 in order to serve Web requests quickly (the in-memory copy and the  
                 underlying databaseare kept in synch as edits are performed). 
                 

-                    VIVO will 
-                    require more memory than that allocated to Tomcat by default. With most  
+                    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.
                     

@@ -523,16 +515,14 @@
                     data, 256m to 512m should be sufficient.
                 

-                    If an OutOfMemoryError is 
-                    encountered during VIVO execution, it can be remedied by increasing the  
-                    heap parameters and restarting Tomcat. 
+                    If an OutOfMemoryError is encountered during VIVO execution, it can 
+                    be remedied by increasing the heap parameters and restarting Tomcat. 
                 

-                    Security limits: VIVO is a 
-                    multithreaded web application that may require more threads than are  
-                    permitted under your Linux installation's default configuration. Ensure 
-                    that your installation can support the required number of threads 
-                    by making the following edits to "/etc/security/limits.conf":
+                    Security limits: VIVO is a multithreaded web application that may 
+                    require more threads than are permitted under your Linux installation's  
+                    default configuration. Ensure that your installation can support the 
+                    required number of threads by making the following edits to /etc/security/limits.conf:
                 
                     apache	hard	nproc	400
@@ -540,18 +530,19 @@
                 
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. 
+                    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 for the initialAdminUser
+                    near the upper right corner.  Log in with the initialAdminUser
+                    username you set up in Step IV. The initial password for the initialAdminUser
                     account is "defaultAdmin" (without the quotes). On first login, you will be
                     prompted to select a new password and verify it a second time.
                 

@@ -586,7 +577,7 @@
             
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
+                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.
@@ -594,12 +585,12 @@
             

                 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
+                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 theVitro.smtpHost
+                If you set theVitro.smtpHost
                 in Step IV and do NOT provide an email addressin this
                 step, your users will receive a java error in the interface.
             

@@ -616,14 +607,13 @@
             

                 Using the mod_jk connector allows for communication between Tomcat 
-                and the primary web server. The Quick
-                    Start HowTo
+                and the primary web server. The Quick Start HowTo
                 on the Apache site describes the minimum server configurations 
                 for several popular web servers. 
             

-                After setting up the mod_jk connector above, you will need to
-                modify the Tomcat's server.xml ([tomcat root]/conf/) to respond to
+                After setting up the mod_jk connector above, you will need to 
+                modify the Tomcat's server.xml (located in [tomcat root]/conf/) to respond to
                 requests from Apache via the connector. Look for the
                 <connector> directive and add the following properties:
             

@@ -632,13 +622,15 @@
             

                 Note: the value for maxThreads (320) is equal to the value for MaxClients 
-                in the apache's "httpd.conf" file. 
+                in the apache's httpd.conf
+                file. 
             

-                Locate the <Host name="localhost"...> directive and update as
+                Locate the <Host name="localhost"...>
+                directive and update as
                 follows:
             

-            
+            
 	    <Host name="localhost" appBase="webapps"
 	        DeployOnStartup="false"
 	        unpackWARs="true" autoDeploy="false"
@@ -672,9 +664,9 @@
             

                 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 
+                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, 
+                lot of instance data. If you would like to keep the default mode, 
                 skip to the next step. 
             

             

@@ -685,19 +677,17 @@
             

                 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 
+                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 
+                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
+                Finally, a class called PelletReasonerSetupPseudocompleteIgnoreDataproperties 
+                is provided to improve performance on ontologies with large literals where data
                 property entailments are not needed.
             

             

@@ -727,10 +717,7 @@
                     external authentication system.
                 

                 

-                    For VIVO, this secured page is named: 
-                    
-                        /loginExternalAuthReturn
-                    
+                    For VIVO, this secured page is named: /loginExternalAuthReturn
                 

                 

                     When your instructions call for the location of the secured page, this is the 
@@ -738,40 +725,49 @@
                 

                 
Configuring VIVO

                 

-                    To enable external authentication, VIVO requires three values in the 
-                    deploy.properties file.
+                    To enable external authentication, VIVO requires three values in the deploy.properties
+                    file.
                 

                 
    
                     
  • 
-                        The name of the HTTP header that will hold the external user’s network ID 
-                        When a user completes the authentication process, the Apache server will  
-                        put the user’s network ID into one of the headers of the HTTP request. 
-                        The instructions from your institution should tell you which header is  
+                        
    The name of the HTTP header that will hold the external user's network ID.
    
+                        When a user completes the authentication process, the Apache server will 
+                        put the user's network ID into one of the headers of the HTTP request.  
+                        The instructions from your institution should tell you which header is 
                         used for this purpose. 
-                        You need to tell VIVO the name of that HTTP header. Insert a line like  
-                        this in the deploy.properties file: 
    externalAuth.netIdHeaderName = [the header name]
    
-                        For example: 
    externalAuth.netIdHeaderName = remote_userID
    
+                        
    
+                            You need to tell VIVO the name of that HTTP header. Insert a line like 
+                            this in the deploy.properties file: 
    externalAuth.netIdHeaderName = [the header name]
    
+                            For example: 
+                        
    
+                        
    externalAuth.netIdHeaderName = remote_userID
    
                     
    • 
                     
  • 
-                        The text for the Login button 
-                        To start the authentication process, the user will click on a button in  
-                        the VIVO login form. You need to tell VIVO what text should appear in that 
-                        button.  
-                        Put a line like this in the deploy.properties file: 
-                        externalAuth.buttonText = [the text for your login button]  
-                        For example: 
    externalAuth.buttonText = Log in using BearCat Shibboleth
    
-                        The VIVO login form will display a button labelled “Log in using BearCat 
-                        Shibboleth”.
+                        
    The text for the Login button.
    
+                        To start the authentication process, the user will click on a button in 
+                        the VIVO login form. You need to tell VIVO what text should appear in that  
+                        button. 
+                        
    
+                            Put a line like this in the deploy.properties file: 
+                            externalAuth.buttonText = [the text for your login button]  
+                            For example: 
+                        
    
+                        
    externalAuth.buttonText = Log in using BearCat Shibboleth
    
+                        The VIVO login form will display a button labelled "Log in using BearCat 
+                        Shibboleth".
                     
    • 
                     
  • 
-                        Associating a User with a profile page 
-                        If VIVO has an account for the user, the user will be given the privileges  
+                        
    Associating a User with a profile page
    
+                        If VIVO has an account for the user, the user will be given the privileges 
                         assigned to that account. 
-                        In addition, VIVO will try to associate the user with a profile page, so  
-                        the user may edit his own profile data. VIVO will search the data model 
-                        for a person with a property that matches the User’s network ID.  
-                        You need to tell VIVO what property should be used for matching. Insert 
-                        a line like this in the deploy.properties file:
    selfEditing.idMatchingProperty = [the URI of the property]
    
+                        
    
+                            In addition, VIVO will try to associate the user with a profile page, so 
+                            the user may edit his own profile data. VIVO will search the data model  
+                            for a person with a property that matches the User’s network ID. 
+                            You need to tell VIVO what property should be used for matching. Insert 
+                            a line like this in the deploy.properties file:
+                        
    
+                        
    selfEditing.idMatchingProperty = [the URI of the property]
    
                         For example:
    selfEditing.idMatchingProperty = http://vivo.mydomain.edu/ns#networkId
    
                     
    • 
                 

@@ -814,7 +810,8 @@
             
    
                 
  • 
                     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  
+                    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.
                 
    • 
@@ -830,7 +827,7 @@
                     the next step. 
                 
                 
  • 
-                    Open a new web browser or browser tab to the page http://marbles.sourceforge.net/.
+                    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."
                 
    • 
@@ -847,11 +844,11 @@
             
    
             
      
                 
    • 
-                    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"  
+                    Type the word "Australia" into the search 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.
+                    border Australia, individuals that include Australia, and to  
+                    Australia itself.  To trigger the search index, you can log in as a site 
+                    administrator and go to "http://your-vivo-url/SearchIndex".
                 
      • 
             
    
         


                 

                     
                 

                 

                     
                         Specify a driver class name to use a database other than MySQL. 
-                        Otherwise, leave this value unchanged. 
+                        Otherwise, leave this value unchanged.  
                         This JAR file for this driver must be added to the the 
                         webapp/lib directory within the vitro.core.dir specified above.