+

Vitro Version 1.3 Installation Guide

+ + November 15, 2011 + + + + + +
+

+ This document is a summary of the Vitro installation process. +

+

+ These instructions assume that you are performing a clean install, + starting with an empty database, an empty Vitro home directory, + and a Tomcat installation with no Vitro webapp. + If you are upgrading a previous installation of Vitro, + you should consult the applicable “upgrade” file(s) in this directory. +

+

+ Before beginning the installation, + let’s discuss some of the major concepts relating to the Vitro installation. +

+ +
+

Introduction to the Vitro installation

+ +

Where does Vitro live on your computer?

+

+ Vitro exists in four locations on your computer, from the distribution to the runtime to the data storage. +

+

The Vitro distribution directory

+

+ This is created when you checkout the Vitro source code + (see installation step III, below). + This is where you will create your deploy.properties file + (see installation step V, below), + and where you will make any modifications to the Vitro + theme or code. You can create this wherever you choose. +

+

Vitro inside Tomcat

+

+ When you run the build script to compile and deploy Vitro + (see installation step VI, below), + the files will be deployed to a + directory inside Tomcat. This is the actual executing code for Vitro, + but you won’t need to look at it or change it. If you need to change + Vitro, make the changes in the distribution directory, and run the build + script again. Tell the build script where to find Tomcat by setting tomcat.home + in the deploy.properties file (see installation step V, + below). +

+

The Vitro home directory

+

+ Vitro will use this area to store some of the data it uses. Uploaded + image files are stored here, and the search index is stored here also. + You can create this wherever you choose. Tell Vitro where to find the + home directory by setting vitro.home.directory + in the + deploy.properties file (see installation step V, + below). You must create this directory before starting Vitro, and you + must ensure that Tomcat has permission to read and write to this + directory when it runs. +

+

The MySQL database

+

+ Essentially all of the data that you store in Vitro will be given to + MySQL for storage. The actual location of this data depends on what + system you have, and on how you install MySQL + (see installation step I, below). + but you won’t need to + know the location. You will access the data through Vitro, or + occasionally through the MySQL client application. +

+ +

The relationship between Vitro and VIVO

+ +

“Vitro Inside”

+

+ Vitro was developed as a + “general-purpose web-based ontology and instance editor with customizable public browsing.” + It is useful on its own, but also serves as the basis for several products, + including VIVO. [http://sourceforge.net/projects/vivo/] +

+

+ In 2009, the National Institutes of Health (NIH) awarded a major grant to advance the development of VIVO. + Much of the recent development on Vitro has been in support of that grant. +

+

+ However, Vitro retains its own identity, + and still serves as the core of many projects and products. + Some of these are currently in use, and some are still in the planning stages. +

+

+ Because VIVO was so well funded, and because it is widely used, + someone seeking help with Vitro might find information that applies to VIVO instead. + In many cases, that information will apply to Vitro as well. + However, there are some notable exceptions: +

+

+ +

Release schedule and names

+

+ Currently, the Vitro release schedule is coordinated with the VIVO releases, + so version 1.3 of Vitro forms the basis of version 1.3 of VIVO. + In the Vitro code repository, the release tags illustrate this relationship. + For example, the Vitro revision that was tagged for version 1.3 of VIVO is named “rel-vivo-1.3” +

+

+ As the project progresses, + we will also see Vitro releases named for versions of Datastar and other Vitro-based products. +

+ +

Installation process for Version 1.3

+

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

+ +

Steps to Installation

+
    +
  1. + Install required software +
    2. +
  2. + Create an empty MySQL database +
    3. +
  3. + Check out the Vitro Source Code +
    4. +
  4. + Specify deployment properties +
    5. +
  5. + Compile and deploy +
    6. +
  6. + Set Tomcat JVM parameters and + security limits +
    7. +
  7. + Start Tomcat +
    8. +
  8. + Log in and add RDF data +
    9. +
  9. + Set the Contact Email Address (if + using "Contact Us" form) +
    10. +
  10. + Setup Apache Tomcat Connector +
    11. +
  11. + Using an External Authentication + System with VIVO +
    12. +
  12. + Was the installation successful? +
    13. +
  13. + Review the VIVO Terms of Use +
    14. +
+ +

I. Install required software

+

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

+ +

+ Be sure to set up the environment variables for JAVA_HOME + and ANT_HOME + and add the executables to your path per + your operating system and installation directions from the software + support websites. +

+

+ * Note that VIVO V1.2 or V1.3 will not run on older versions of MySQL that + may have worked with 1.1.1. Be sure to run VIVO 1.2 with MySQL 5.1 or + higher. Using unsupported versions may result in strange error messages + related to table formatting or other unexpected problems. +

+

II. Create an empty MySQL database

+

+ Decide on a database name, username, and password. Log into your + MySQL server and create a new database in MySQL that uses UTF-8 + encoding. You will need these values for Step IV when you + configure the deployment properties. At the MySQL command line you can + create the database and user with these commands substituting your + values for dbname, username, and password. + Most + of + the + time, the hostname will equal localhost. +

+ 
                CREATE DATABASE dbname CHARACTER SET utf8;
+

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

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

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

+

III. Check out the Vitro Source Code +
+

+

+ Use subversion to check out the Vitro source code from SourceForge: + 

         svn checkout svn://svn.code.sf.net/p/vivo/vitro/code/trunk [Vitro_distribution_dir]
+

+

IV. Specify deployment properties

+

+ At the top level of the VIVO distribution directory, copy the file example.deploy.properties + to a file named simply deploy.properties. This file sets + several properties used in compilation and deployment. +

+

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

+

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ 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 a + 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 +
+ URL of Solr context used in local VIVO search. + Should consist of:
    scheme + servername + port + vivo_webapp_name + "solr"
+ In the standard installation, the Solr context will be on the same + server as VIVO, and in the same Tomcat instance. The path will be the + VIVO webapp.name (specified above) + "solr" +
+ vitro.local.solr.url + + http://localhost:8080/vivosolr +
+ Restricts access to the Solr search platform. + One or more regular expressions, separated by commas. When a request is + made to Solr, the IP address of the requestor must match one of the + patterns, or the request will be rejected. +
+ Examples: +
    +
  • + vitro.local.solr.ipaddress.mask = 127\.0\.0\.1 +
    • +
  • + vitro.local.solr.ipaddress.mask = + 127\.0\.0\.1,0:0:0:0:0:0:0:1 +
    • +
  • + vitro.local.solr.ipaddress.mask = 169.254.* +
    • +
+ +
+ vitro.local.solr.ipaddress.mask + + 127\.0\.0\.1,0:0:0:0:0:0:0:1 +
+ Directory where the VIVO application will store + the data that it creates. This includes uploaded files (usually images) + and the Solr search index. Be sure this directory exists and is + writable by the user who the Tomcat service is running as. +
+ vitro.home.directory + + /usr/local/vivo/data +
+ Specify an SMTP host that the application will + use for sending e-mail (Optional). If this is left blank, the contact + form will be hidden and disabled, and users will not be notified of + changes to their accounts. +
+ email.smtpHost + + smtp.servername.edu +
+ Specify an email address which will appear as + the sender in e-mail notifications to users (Optional). If a user + replies to the notification, this address will receive the reply. If a + user's e-mail address is invalid, this address will receive the error + notice. If this is left blank, users will not be notified of changes to + their accounts. +
+ email.replyTo + + vivoAdmin@my.domain.edu +
+ Specify the JDBC URL of your database. Change + the end of the URL 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 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 email address of the root user + account for the VIVO application. This user will have an initial + temporary password of 'rootPassword'. You will be prompted to create a + new password on first login. +

+ NOTE: The root user account has access to all data and all + operations in VIVO. Data views may be surprising when logged in as the + root user. It is best to create a Site Admin account to use for every + day administrative tasks. +

+
+ rootUser.emailAddress + + vivoAdmin@my.domain.edu +
+ 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 + (the value of the property must be either a String literal or an untyped literal). +
+ selfEditing.idMatchingProperty + + http://vivo.mydomain.edu/ns#networkId +
+ If an external authentication system like Shibboleth or CUWebAuth is to be + used, these properties say how the login button should be labeled, and which + HTTP header will contain the user ID from the authentication system. If such + a system is not to be used, leave these commented out. Consult the installation + instructions for more details. +
+ externalAuth.buttonText +
+ externalAuth.netIdHeaderName + 		+ Log in using BearCat Shibboleth +
+ remote_userID +
+ The temporal graph visualization can require + extensive machine resources. This can have a particularly noticable + impact on memory usage if +
    +
  • + The organization tree is deep, +
    • +
  • + The number of grants and publications is large. +
    • +
+ VIVO V1.3 mitigates this problem by the way of a caching + mechanism and hence we can safely set this to be enabled by default. +
+ visualization.temporal + + enabled +
+ 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 +
+ An absolute file path, pointing to the root directory of the Harvester utility. + You must include the final slash. +
+ harvester.location + + /usr/local/vivo/harvester/ +
+

V. Compile and deploy

+

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

+ 
                ant all
+

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

+

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

+

+ VIVO will require more memory than that allocated to Tomcat by + default. With most installations of Tomcat, the "setenv.sh" or + "setenv.bat" file in Tomcat's bin directory is a convenient place to + set the memory parameters. If this file does not exist in Tomcat's + bin directory, you can create it. +
+ 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 files in Tomcat's logs directory. Error messages are commonly found + in catalina.out + or localhost.log +

+

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 rootUser.emailAddress + you set up in Step IV. The initial password for the root account is + "rootPassword" (without the quotes). On first login, you will be + prompted to select a new password and verify it a second time. When login is + complete, the search index is checked and, if it is empty, + a full index build will be triggered in the background, in order to ensure + complete functionality throughout the site. +

+

+ After logging in, 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 are 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 from 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 (email.smtpHost), you will also need to + add an email address to the VIVO application.  This is the email + to which the contact form will submit. It can be a list server or an + individual's email address. +

+

+ Log in as a system administrator. Navigate to the "Site Admin" + table of contents (link in the right side of the header). Go to "Site + Information" (under "Site Configuration"). In the "Site Information + Editing Form," enter a functional email address in the field "Contact + Email Address" and submit the change. +

+

+ If you set the email.smtpHost + in Step IV and do NOT + provide an email address in this step, your users will receive a java + error in the interface. +

+

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

+

+ This will make VIVO available at "http://example.com" instead of + "http://example.com:8080/vivo" +

+

+ Using the mod_jk connector allows for communication between Tomcat + and the primary web server. The Quick + Start + HowTo + on the Apache site 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: +

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

+

+ Locate the <Host name="localhost"...> + 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>
		
				...
+

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

+ +

XII. Was the installation successful?

+

+ If you have completed the previous steps, you have good indications + that the installation was successful. +

+ +

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

+ +

+ Here is a test to see whether your system is configured to serve + linked data: +

+ +

+ Finally, test the search index. +

+ +

XIII. Review the VIVO Terms of Use

+

+ VIVO comes with a "Terms of Use" statement linked from the footer. + The "Site Name" you assign in the "Site Information" form under the Site Admin + area will be inserted into the "Terms of Use" + statement. If you want to edit the text content more than just the + "Site Name", the file can be found here:

[vivo_source_dir]/vitro-core/webapp/web/templates/freemarker/body/termsOfUse.ftl
+ Be sure to make the changes in your source files and deploy them to your + tomcat so you don't lose your changes next time you deploy for another reason. +

+

Next Step ...

+

+ Now that you have VIVO up and running, please go read the Site Administrator's Guide. +

+