-

VIVO Release 1 V1.2 Installation Guide

+

VIVO Release 1 V1.2 Installation Guide

- January 28, 2011 + January 28, 2011 -
- Missing pieces and fixes -
    -
  • - Add release announcemnet -
    • -
  • - Link to upgrade pdf online at SF -
    • -
-
  • @@ -38,29 +27,117 @@

    Release anouncement for V1.2

    - Text from the wiki page + The VIVO 1.2 release incorporates major changes to the entire + application - theming and navigation changes that will be immediately + evident to any user, and underlying changes to the system architecture + that are less visible but address important questions of scalability + and extensibility. +

    +

    Theming and Navigation

    +

    + A new installation of VIVO 1.2 will look strikingly different - the + User Interface team has designed a new visual theme that incorporates a + new navigation and browse structure as well as a much more modular + approach to page design. This theme is not only cosmetically different + but leverages entirely new page templates developed with the Freemarker + system, an open-source library for Java development that enables much + cleaner separation of application logic from the actual page design. + These changes extend the available configuration options controlling + VIVO's appearance and navigation options while also simplifying the + process of local customization and branding. +

    +

    + For existing installations of VIVO, the upgrade will not immediately + transition to the new theme, navigation, or page templates. The current + default theme and "tabs" (top-level and secondary navigation controls) + will be left intact on upgrade and will still function as they do in + version 1.1.1, with the caveat that local modifications to the default + theme may conflict with internal application changes. We highly + recommend that current VIVO installations use the time between release + 1.2 and the upcoming release of version 1.3 (targeted for June or July + 2011) to migrate local theme branding and navigation to the new VIVO + template. Many legacy features such as the "tab" infrastructure have + been deprecated with version 1.2 and will no longer be supported as of + version 1.3. +

    +

    Browsing

    +

    + In addition to changes in the top-level navigation, VIVO 1.2 + introduces a number of new browsing controls that will be made more + configurable and extensible in version 1.3 but which already offer + extensive functionality. +

    +

    + A fresh installation of VIVO 1.2 will feature the new theme and + additional browsing options on other top-level navigation pages (Home, + People, Research, Organizations, and Events). Primary among the new + browsing options will be browsing by type, organized + hierarchically with the same upper-level class groups + currently + visible in search results - people, courses, activities, topics, + events, organizations, and publications. Class groups combine the + similar types such as people or organizations into groups for browsing + and searching, and are locally configurable using the VIVO ontology + editor. +

    +

    + Once a group has been selected, browsing can continue to the very + specific, at the level of individual people, organizations, events, or + publications via A ... Z listing featuring thumbnail pictures where + available. Sites will be able to configure which groups and which types + within a group are exposed in search results and for browsing. +

    +

    Data Storage

    +

    + Before this release, VIVO has used the Jena (http://jena.sourceforge.net) + relational + database (RDB) subsystem for the storage of RDF data. The + performance of this persistence layer has never been fast enough for an + interactivity at any significant scale, so VIVO has also maintained a + complete copy of data in memory. While server memory capacity has + increased significantly in recent years, this requirement has put + limits on the ultimate scalability of VIVO instances and also increased + the cost of servers required to support VIVO. +

    +

    + With version 1.2 VIVO uses the SPARQL database (SDB) subsystem of + Jena, specifically designed to support scalable storage and query of + RDF datasets while still using standard relational database technology. + This transition will significantly reduce the initial memory footprint + of a VIVO application, and while the application will still require + adequate processor and memory resources to generate pages from so many + individual RDF statements, the scalability of VIVO installations is + greatly improved. +

    +

    + The transition to retrieving all data via SPARQL queries also + enables additional features important for tracking data provenance and + access to data outside the immediate local VIVO instance. These + features will be more fully explored and developed for version 1.3.

    Installation process for V1.2

    - This document is a summary of the VIVO installation process. This and other - documentation can be found on the support page + This document is a summary of the VIVO installation process. This + and other documentation can be found on the support page at VIVOweb.org

    • - 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. + 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.
    • - If you are going to upgrade an existing service, please consult the upgrade.txt - in this directory. + 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. + 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.

    Steps to Installation

    @@ -81,7 +158,8 @@ Compile and deploy
  • - Set Tomcat JVM parameters and security limits + Set Tomcat JVM parameters and + security limits
  • Start Tomcat @@ -90,7 +168,8 @@ Log in and add RDF data
  • - Set the Contact Email Address (if using "Contact Us" form) + Set the Contact Email Address (if + using "Contact Us" form)
  • Setup Apache Tomcat Connector @@ -99,7 +178,8 @@ Configure Pellet Reasoner
  • - Using an External Authentication System with VIVO + Using an External Authentication + System with VIVO
  • Was the installation successful? @@ -108,13 +188,13 @@

    I. Install required software

    - Before installing VIVO, make sure that the following software is - installed on the desired machine: + Before installing VIVO, make sure that the following software is + installed on the desired machine:

    - Be sure to setup the environment variables for + 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. + 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. + 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;
-
    + 
                    CREATE DATABASE dbname CHARACTER SET utf8;

    - Grant access to a database user. - For example: + Grant access to a database user. For example:

    - 
    -                GRANT ALL ON dbname.* TO 'username'@'hostname' IDENTIFIED BY 'password';
-
    + 
                    GRANT ALL ON dbname.* TO 'username'@'hostname' IDENTIFIED BY 'password';

    - Keep track of the database name, username, and password for Step IV. + Keep track of the database name, username, and password for Step + IV.

    III. Download the VIVO Application Source
    @@ -161,449 +240,463 @@

    Download the VIVO application source as either rel-1.2.zip or rel-1.2.gz - file and unpack it on your web server: -
    + 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. - This file sets several properties used in compilation and deployment. + 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. + 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.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    - Property Name - - Example Value -
    - Default namespace: VIVO installations make their RDF resources available - for harvest using linked data. Requests for RDF resource URIs redirect to HTML - or RDF representations as specified by the client. To make this possible, - VIVO's default namespace must have certain structure and begin with the public - web address of the VIVO installation. For example, if the web address of a VIVO - installation is "http://vivo.example.edu/" the default namespace must be set to - "http://vivo.example.edu/individual/" in order to support linked data. Similarly, - if VIVO is installed at "http://www.example.edu/vivo" the default namespace must be - set to "http://www.example.edu/vivo/individual/"
    * The namespace must end with "individual/" (including the trailing slash).
    -
    - Vitro.defaultNamespace - - http://vivo.mydomain.edu/individual/ -
    - Directory where Vitro code is located. In most deployments, this is set to - ./vitro-core, but it commonly points elsewhere during development. -
    - vitro.core.dir - - ./vitro-core -
    - Directory where tomcat is installed. -
    - tomcat.home - - /usr/local/tomcat -
    - Name of your VIVO application. -
    - webapp.name - - vivo -
    - Directory where uploaded files will be stored. You must create this directory ahead of time. -
    - upload.directory - - /usr/local/vivo/data/uploads -
    - Directory where the Lucene search index will be built. Depending on your - permissions and who Tomcat is running as, you may need to create this directory - ahead of time. -
    - LuceneSetup.indexDir - - /usr/local/vivo/data/luceneIndex -
    - Specify an SMTP host that the form will use for sending e-mail (Optional). If - this is left blank, the contact form will be hidden and disabled. -
    - Vitro.smtpHost - - smtp.servername.edu -
    - Specify the JDBC URL of your database. Change the end of theURL to reflect your - database name (if it is not "vivo"). -
    - VitroConnection.DataSource.url - - jdbc:mysql://localhost/vivo -
    - Change the username to match the authorized user you created in MySQL. -
    - VitroConnection.DataSource.username - - username -
    - Change the password to match the password you created in MySQL. -
    - VitroConnection.DataSource.password - - password -
    - Specify the Jena triple store technology to use. SDB is Jena's - SPARQL database; this setting allows RDF data to scale beyond the - limits of the JVM heap. Set to RDB to use the older Jena RDB - store with in-memory caching. -
    - VitroConnection.DataSource.tripleStoreType - - SDB -
    - Specify the maximum number of active connections in the database - connection pool to support the anticipated number of concurrent - page requests. It is not necessary to adjust this value when - using the RDB configuration. -
    - VitroConnection.DataSource.pool.maxActive - - 40 -
    - Specify the maximum number of database connections that will be - allowed to remain idle in the connection pool. Default is - 25% of the maximum number of active connections. -
    - VitroConnection.DataSource.pool.maxIdle - - 10 -
    - Change the dbtype setting to use a database other than MySQL. - Otherwise, leave this value unchanged. - Possible values are DB2, derby, HSQLDB, H2, MySQL, Oracle, - PostgreSQL, and SQLServer. - Refer to http://openjena.org/wiki/SDB/Databases_Supported - for additional information. -
    - VitroConnection.DataSource.dbtype - - MySQL -
    - Specify a driver class name to use a database other than MySQL. - Otherwise, leave this value unchanged. - This JAR file for this driver must be added to the the - webapp/lib directory within the vitro.core.dir specified above. -
    - VitroConnection.DataSource.driver - - com.mysql.jdbc.Driver -
    - Change the validation query used to test database connections - only if necessary to use a database other than MySQL. - Otherwise, leave this value unchanged. -
    - VitroConnection.DataSource.validationQuery - - SELECT 1 -
    - Specify the name of your first admin user for the VIVO application. This user - will have an initial temporary password of 'defaultAdmin'. You will be prompted to - create a new password on first login. -
    - initialAdminUser - - defaultAdmin -
    - The name of a property that can be used to associate an Individual with a user - account. When a user logs in with a name that matches the value of this property, - the user will be authorized to editthat Individual. -
    - selfEditing.idMatchingProperty - - http://vivo.mydomain.edu/ns#networkId -
    - Temporal Graph Visualization is used to compare different - organizations/people within an organization on different parameters like - number of publications, grants. This parameter will be used as a default - in case a URI is not provided. It will be also used whenever this - visualization is to be rendered for top level organization. - In absence of this parameter a SPARQL query will be fired which will - attempt to provide a top level organization. The name of a property that - can be used to associate an Individual with a user account. When a user - logs in with a name that matches the value of this property, the user - will be authorized to edit that Individual. -
    - visualization.topLevelOrg - - http://vivo-trunk.indiana.edu/individual/topLevelOrgURI -
    + Property Name + + Example Value +
    + Default namespace: VIVO installations make their + RDF resources available for harvest using linked data. Requests for RDF + resource URIs redirect to HTML or RDF representations as specified by + the client. To make this possible, VIVO's default namespace must have + certain structure and begin with the public web address of the VIVO + installation. For example, if the web address of a VIVO installation is + "http://vivo.example.edu/" the default namespace must be set to + "http://vivo.example.edu/individual/" in order to support linked data. + Similarly, if VIVO is installed at "http://www.example.edu/vivo" the + default namespace must be set to + "http://www.example.edu/vivo/individual/"
    * The namespace must end with "individual/" (including the + trailing slash).
    +
    + Vitro.defaultNamespace + + http://vivo.mydomain.edu/individual/ +
    + Directory where Vitro code is located. In most + deployments, this is set to ./vitro-core (It is not uncommon for this + setting to point elsewhere in development environments). +
    + vitro.core.dir + + ./vitro-core +
    + Directory where tomcat is installed. +
    + tomcat.home + + /usr/local/tomcat +
    + Name of your VIVO application. +
    + webapp.name + + vivo +
    + Directory where uploaded files will be stored. + Be sure this directory exists and is writable by the user that + the Tomcat service is running as. +
    + upload.directory + + /usr/local/vivo/data/uploads +
    + Directory where the Lucene search index will be + built. Be sure this directory exists and is writable by the user that + the Tomcat service is running as. +
    + LuceneSetup.indexDir + + /usr/local/vivo/data/luceneIndex +
    + Specify an SMTP host that the form will use for + sending e-mail (Optional). If this is left blank, the contact form will + be hidden and disabled. +
    + Vitro.smtpHost + + smtp.servername.edu +
    + Specify the JDBC URL of your database. Change + the end of theURL to reflect your database name (if it is not "vivo"). +
    + VitroConnection.DataSource.url + + jdbc:mysql://localhost/vivo +
    + Change the username to match the authorized user + you created in MySQL. +
    + VitroConnection.DataSource.username + + username +
    + Change the password to match the password you + created in MySQL. +
    + VitroConnection.DataSource.password + + password +
    + Specify the Jena triple store technology to use. + SDB is Jena's SPARQL database; this setting allows RDF data to scale + beyond the limits of the JVM heap. Set to RDB to use the older Jena RDB + store with in-memory caching. +
    + VitroConnection.DataSource.tripleStoreType + + SDB +
    + Specify the maximum number of active connections + in the database connection pool to support the anticipated number of + concurrent page requests. It is not necessary to adjust this value when + using the RDB configuration. +
    + VitroConnection.DataSource.pool.maxActive + + 40 +
    + Specify the maximum number of database + connections that will be allowed to remain idle in the connection pool. + Default is 25% of the maximum number of active connections. +
    + VitroConnection.DataSource.pool.maxIdle + + 10 +
    + Change the dbtype setting to use a database + other than MySQL. Otherwise, leave this value unchanged. Possible + values are DB2, derby, HSQLDB, H2, MySQL, Oracle, PostgreSQL, and + SQLServer. Refer to http://openjena.org/wiki/SDB/Databases_Supported + for additional information. +
    + VitroConnection.DataSource.dbtype + + MySQL +
    + Specify a driver class name to use a database + other than MySQL. Otherwise, leave this value unchanged. This JAR file + for this driver must be added to the the webapp/lib directory within + the vitro.core.dir specified above. +
    + VitroConnection.DataSource.driver + + com.mysql.jdbc.Driver +
    + Change the validation query used to test + database connections only if necessary to use a database other than + MySQL. Otherwise, leave this value unchanged. +
    + VitroConnection.DataSource.validationQuery + + SELECT 1 +
    + Specify the name of your first admin user for + the VIVO application. This user will have an initial temporary password + of 'defaultAdmin'. You will be prompted to create a new password on + first login. +
    + initialAdminUser + + defaultAdmin +
    + The URI of a property that can be used to + associate an Individual with a user account. When a user logs in with a + name that matches the value of this property, the user will be + authorized to edit that Individual. +
    + selfEditing.idMatchingProperty + + http://vivo.mydomain.edu/ns#networkId +
    + The temporal graph visualization is used to + compare different organizations/people within an organization on + parameters like number of publications or grants. By default, the app + will attempt to make its best guess at the top level organization in + your instance. If you're unhappy with this selection, uncomment out the + property below and set it to the URI of the organization individual you + want to identify as the top level organization. It will be used as the + default whenever the temporal graph visualization is rendered without + being passed an explicit org. For example, to use "Ponce School of + Medicine" as the top organization: +
    + visualization.topLevelOrg = + http://vivo.psm.edu/individual/n2862 +
    +
    + visualization.topLevelOrg + + http://vivo-trunk.indiana.edu/individual/topLevelOrgURI +

    V. Compile and deploy

    - At the command line, from the top level of the unpacked distribution - directory, type: + At the command line, from the top level of the unpacked + distribution directory, type:

    - 
    -                ant all
-
    + 
                    ant all

    - to build VIVO and deploy to Tomcat's webapps - directory. + to build VIVO and deploy to Tomcat's webapps directory.

    -

    VI. Set Tomcat JVM parameters and security limits

    +

    VI. Set Tomcat JVM parameters and security + limits

    - 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 databaseare 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="-Xms2048m -Xmx1024m -XX:MaxPermSize=128m"
-
    -

    - This sets Tomcat to allocate an initial heap of 2048 megabytes, a - maximum heap of 1024 megabytes, and a PermGen space of 128 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, 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: -

    - 
    -                    apache	hard	nproc	400
-                    tomcat6	hard	nproc	1500 
-
    -

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

    -

    - 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 right of - the page will show a simple index of the knowledge base. -

    -

    - See more - documentation for configuring VIVO, ingesting data, and manually adding - data at http://vivoweb.org/support. -

    + 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 databaseare kept in synch as edits are performed).

    -

    IX. Set the Contact Email Address (if using "Contact Us" form)

    +

    + 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="-Xms2048m -Xmx1024m -XX:MaxPermSize=128m"
    +

    + This sets Tomcat to allocate an initial heap of 2048 megabytes, a + maximum heap of 1024 megabytes, and a PermGen space of 128 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, 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: +

    + 
                        apache	hard	nproc	400
                        tomcat6	hard	nproc	1500
    +

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

    +

    + 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 right of + the page will show a simple index of the knowledge base. +

    +

    + See more documentation for configuring VIVO, ingesting data, and + manually adding data 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. + 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. + 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 theVitro.smtpHost - in Step IV and do NOT provide an email addressin this - step, your users will receive a java error in the interface. + in Step IV and do NOT + provide an email addressin this step, your users will receive a java + error in the interface.

    X. 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). + 8080) and an additional reference to the Tomcat context name (e.g. + /vivo).

    This will make VIVO available at "http://example.com" instead of @@ -611,48 +704,32 @@

    Using the mod_jk connector allows for communication between Tomcat - and the primary web server. The Quick Start HowTo - on the Apache site describes the minimum server configurations - for several popular web servers. + 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 (located in [tomcat root]/conf/) to respond to - requests from Apache via the connector. Look for the - <connector> directive and add the following properties: + 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:

    - 
    -                connectionTimeout="20000" maxThreads="320" keepAliveTimeout="20000"  
-
    + 
                    connectionTimeout="20000" maxThreads="320" keepAliveTimeout="20000" 

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

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

    - 
    -	    <Host name="localhost" appBase="webapps"
-	        DeployOnStartup="false"
-	        unpackWARs="true" autoDeploy="false"
-	        xmlValidation="false" xmlNamespaceAware="false">
-	
-		<Alias>example.com</Alias>
-		<Context path=""
-			docBase="/usr/local/tomcat/webapps/vivo"
-			reloadable="true"
-			cookies="true" >
-			<Manager pathname="" />
-			<Environment type="java.lang.String" override="false" 
-				name="path.configuration" 
-				value="deploy.properties"
-			/>
-		</Context>
-		...
-
    + 
    	    <Host name="localhost" appBase="webapps"
    	        DeployOnStartup="false"
    	        unpackWARs="true" autoDeploy="false"
    	        xmlValidation="false" xmlNamespaceAware="false">
    	
    		<Alias>example.com</Alias>
    		<Context path=""
    			docBase="/usr/local/tomcat/webapps/vivo"
    			reloadable="true"
    			cookies="true" >
    			<Manager pathname="" />
    			<Environment type="java.lang.String" override="false" 
    				name="path.configuration" 
    				value="deploy.properties"
    			/>
    		</Context>
    		...

    XI. Configure Pellet Reasoner

    Do we need this section still? - elly @@ -662,185 +739,192 @@ 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. + 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. + 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. + 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. + 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. + 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. + Finally, a class called + PelletReasonerSetupPseudocompleteIgnoreDataproperties is provided to + improve performance on ontologies with large literals where data + property entailments are not needed.

    -

    -

    XII. Using an External Authentication System with VIVO

    +

    XII. Using an External Authentication System + with VIVO

    -

    - VIVO can be configured to work with an external authentication system like - Shibboleth or CUWebAuth. -

    -

    - VIVO must be accessible only through an Apache HTTP server. The Apache server - will be configured to invoke the external authentication system. When the user - completes the authentication, the Apache server will pass a network ID to VIVO, - to identify the user. -

    -

    - If VIVO has an account for that user, the user will be logged in with the - privileges of that account. In the absence of an account, VIVO will try to find - a page associated with the user. If such a page is found, the user can log in - to edit his own profile information. -

    -

    Configuring the Apache server

    -

    - Your institution will provide you with instructions for setting up the external - authentication system. The Apache server must be configured to secure a page in - VIVO. When a user reaches this secured page, the Apache server will invoke the - external authentication system. -

    -

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

    -

    - When your instructions call for the location of the secured page, this is the - value you should use. -

    -

    Configuring VIVO

    -

    - 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 - 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
      -
      • -
    • -
      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 - 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]
      - For example:
      selfEditing.idMatchingProperty = http://vivo.mydomain.edu/ns#networkId
      -
      • -

    +

    + VIVO can be configured to work with an external authentication + system like Shibboleth or CUWebAuth. +

    +

    + VIVO must be accessible only through an Apache HTTP server. The + Apache server will be configured to invoke the external authentication + system. When the user completes the authentication, the Apache server + will pass a network ID to VIVO, to identify the user. +

    +

    + If VIVO has an account for that user, the user will be logged in + with the privileges of that account. In the absence of an account, VIVO + will try to find a page associated with the user. If such a page is + found, the user can log in to edit his own profile information. +

    +

    Configuring the Apache server

    +

    + Your institution will provide you with instructions for setting up + the external authentication system. The Apache server must be + configured to secure a page in VIVO. When a user reaches this secured + page, the Apache server will invoke the external authentication system. +

    +

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

    +

    + When your instructions call for the location of the secured page, + this is the value you should use. +

    +

    Configuring VIVO

    +

    + 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 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
      +
      • +
    • +
      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 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]
      + For example:
      selfEditing.idMatchingProperty = http://vivo.mydomain.edu/ns#networkId
      +
      • +

    XIII. Was the installation successful?

    - If you have completed the previous steps, you have good indications that the - installation was 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 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 VIII verified that you can log in to the administrator + account.

    - Here is a simple test to see whether the ontology files were loaded: + Here is a simple test to see whether the ontology files were + loaded:

    • - Click on the "Index" link on the upper right, 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 "Index" link on the upper right, 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. + 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: + 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. + 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. + 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. + 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 + 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. + 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.

    @@ -848,11 +932,11 @@

    • - 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. To trigger the search index, you can log in as a site - administrator and go to "http://your-vivo-url/SearchIndex". + 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. To trigger the search index, you can log in as a site + administrator and go to "http://your-vivo-url/SearchIndex".