+

VIVO Release 1 V1.3 Installation Guide

+ + July 22, 2011 + + + + +

Release anouncement for V1.3

+ See wiki page. +
+

Installation process for V1.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 +

+ +

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

+

Where does VIVO live on your computer?

+

+ Before beginning the installation, let's look at the four locations + on your computer that will hold VIVO. +

+

The VIVO distribution directory

+

+ This is created when you unpack the VIVO distribution file (see Step III, below). This is where you will + create your deploy.properties file (see Step + V, below), and where you will make any modifications to the VIVO + theme or code. You can create this wherever you choose. +

+

VIVO inside Tomcat

+

+ When you run the build script to compile and deploy VIVO (see Step VI, below), the files will be deployed to a + directory inside Tomcat. This is the actual executing code for VIVO, + but you won’t need to look at it or change it. If you need to change + VIVO, 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 Step V, + below). +

+

The VIVO home directory

+

+ VIVO 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 VIVO where to find the + home directory by setting vitro.home.directory + in the + deploy.properties file (see Step V, + below). You must create this directory before starting VIVO, 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 VIVO 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 Step I, below). but you won’t need to + know the location. You will access the data through VIVO, or + occasionally through the MySQL client application. +

+ +

Steps to Installation

+
    +
  1. + Install required software +
    2. +
  2. + Create an empty MySQL database +
    3. +
  3. + Download the VIVO Application Source +
    4. +
  4. + Choose Triple Store +
    5. +
  5. + Specify deployment properties +
    6. +
  6. + Compile and deploy +
    7. +
  7. + Set Tomcat JVM parameters and + security limits +
    8. +
  8. + Start Tomcat +
    9. +
  9. + Log in and add RDF data +
    10. +
  10. + Set the Contact Email Address (if + using "Contact Us" form) +
    11. +
  11. + Setup Apache Tomcat Connector +
    12. +
  12. + Using an External Authentication + System with VIVO +
    13. +
  13. + Was the installation successful? +
    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 1.2 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. +

+

+ * Note that VIVO is not yet compatible with Tomcat 7. +

+

II. Create an empty MySQL database

+

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

+ 
                CREATE DATABASE dbname CHARACTER SET utf8;
+

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

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

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

+

III. Download the VIVO Application Source +
+

+

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

+

IV. Triple Store

+

+ VIVO 1.3 now requires you to use Jena's SPARQL database (SDB) for + the triple store technology.  Jena's legacy relational database + store (RDB) was used by VIVO 1.1.1 and earlier.  Both SDB and RDB + were available in VIVO 1.2 and 1.2.1.  A VIVO 1.2 system running + in RDB mode ... [WHAT HAPPENS + IF THEY UPGRADE in RDB MODE? - elly] +

+

+ SDB mode caches only a fraction of the RDF data in memory. Most + queries are issued directly against the underlying database. This + allows VIVO installations to display data from large RDF models while + requiring only a small amount of server memory to run the application. + There is a tradeoff in response time: pages make take slightly longer + to load in SDB mode, and performance will depend on the configuration + parameters of the database server. Additionally, advanced OWL reasoning + (not enabled by default in either mode) is not possible in SDB mode. + With SDB, only the default set of inferences (inferred rdf:type + statements) are generated, though they are generated as soon as data is + edited rather than in a background process. +

+

+ This copying process can take a number of hours to complete if the + installation contains a large amount of RDF data (roughly a million + triples or more). See section Set + Up SDB Store in + the Background (Optional) + for instructions on how to run this + lengthy conversion process in the background while an RDB system is + operating. Doing this will reduce the time necessary to start VIVO the + first time it is run in SDB mode. +

+

V. 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 + vivocontextpath + "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 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 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. +
+ selfEditing.idMatchingProperty + + http://vivo.mydomain.edu/ns#networkId +
+ The temporal graph visualization can require + extensive machine resources. This can have a particularly noticable + impact on memory usage if +
    +
  • + VIVO is configured to use Jena SDB, +
    • +
  • + The organization tree is deep, +
    • +
  • + The number of grants and publications is large. +
    • +
+ The VIVO developers are working to make this visualization more + efficient. In the meantime, VIVO release 1.2 guards against this impact + by disabling the temporal graph visualization unless the + "visualization.temporal" flag is set to "enabled". To enable it, + uncomment the line for this setting. +
+ 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 +
+

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

+

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

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

+

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

+

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

+

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

+

XI. Set up Apache Tomcat Connector

+

+ It is recommended that a Tomcat Connector such as mod_jk be used to + ensure that the site address does not include the port number (e.g. + 8080) and an additional reference to the Tomcat context name (e.g. + /vivo). +

+

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

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

+ +

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

+ +