diff --git a/doc/install.html b/doc/install.html index 0cd75c2c..178a9711 100644 --- a/doc/install.html +++ b/doc/install.html @@ -1,2114 +1,663 @@ - - - VIVO Release 1 V1.3 Installation Guide - - - - - -
-

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

- -
- - - - ======= - - - VIVO Release 1 V1.2 Installation Guide - - - - - -
-

VIVO Release 1 V1.2 Installation Guide

- - February 16, 2011 - - - - -

Release anouncement for V1.2

-

- The VIVO 1.2 release incorporates major changes throughout the application - - notably a new templating system to support more versatile page rendering, plus - improvements to address scalability. The release also features a new personal - visualization option covering grants as well as publications. The VIVO Harvester - library has also been significantly improved and expanded in scope for its 1.0 - release through the VIVO SourceForge project at http://sourceforge.net/projects/vivo. -

-

Templating system for page generation, navigation, and theming

-

- A fresh installation of VIVO 1.2 looks strikingly different, with the introduction - of a new default theme which takes advantage of the navigation and browse features - delivered by the templating system. Individual pages now offer inline navigation to - streamline viewing of expanded personal and organizational profiles, as well as - improved content layout and organization. New browse controls on the home page and - menu pages help to provide an immediate overview of the size and range of content - and quick access down to the individual person, organization, research feature, or - event. -

-

Storage model

-

- While server memory capacity has increased significantly in recent years, VIVO's reliance - on in-memory caching of RDF data had put limits on the ultimate scalability of VIVO instances - and potentially increased the cost of servers required to support VIVO. -

-

- With version 1.2, VIVO has been converted to optionally use Jena's SPARQL database (SDB) - subsystem. SDB significantly reduces the baseline memory footprint, allowing VIVO installations - to scale well beyond what has previously been possible. -

-

New visualizations

-

- Visualizations of networks of co-authors are now complemented by visualizations of co-investigators - on grants, with similar interactivity and options for export as images or data. -

-

Ontology

-

- VIVO 1.2 includes a new ontology module representing research - resources including biological specimens, human studies, instruments, - organisms, protocols, reagents, and research opportunities. This module - is aligned with the top-level ontology classes and properties from the - NIH-funded eagle-i Project. -

-

Associated VIVO releases

-

VIVO Harvester

-

- The Harvester development team is releasing version 1.0 of the VIVO Harvester library shortly - following the release of VIVO 1.2. The Harvester is an extensible data ingest and updating - framework with sample configurations for loading PubMed publication, grants, and human resources - data. Pre-release versions of the Harvester are available at http://sourceforge.net/projects/vivo. -

-

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 - 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. Choose Triple Store

-

- VIVO 1.2 offers a choice of two triple store technologies: in-memory models backed by - Jena's legacy relational database store (RDB), and Jena's SPARQL database (SDB). RDB was - used by VIVO 1.1.1 and earlier. This mode offers fast response, but only by caching the - entire RDF model in the server's main memory. The memory available to VIVO limits the - number of RDF statements that may be stored. -

-

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

-

- Though a VIVO installation may be switched back and forth between RDB and SDB mode by changing - a configuration property and redeploying the application, it is important to note that data - added in one mode will not typically appear in the other. The exception is when a system is - first switched from RDB mode to SDB mode. In this case, the data from the RDB store will be - automatically migrated to SDB. -

-

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

- -
- -