VIVO Release 1 V1.2 Installation Guide
+VIVO Release 1 V1.2 Installation Guide
- January 28, 2011 + January 28, 2011 --
-
- - 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 deployI. 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:
- Java (SE) 1.6 or higher, http://java.sun.com - (Not OpenJDK) + (Not OpenJDK)
- Apache Tomcat 6.x or higher, http://tomcat.apache.org @@ -127,33 +207,32 @@
- 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 theinitialAdminUser+ 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".