diff --git a/doc/install.html b/doc/install.html index 178a9711..380f2866 100644 --- a/doc/install.html +++ b/doc/install.html @@ -1,663 +1,1086 @@ - - - - VIVO Release 1 V1.3 Installation Guide - - - VIVO Release 1 V1.2 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. 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. -
- -

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

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.

-

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

-

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.

- -
- - - + + + + VIVO Release 1 V1.3 Installation Guide + + + VIVO Release 1 V1.2 Installation Guide + + + + +
+

VIVO Release 1 V1.3 Installation Guide

+ + July 22, 2011 + + + + +

Release anouncement for V1.3

+ VIVO Release 1.3 incorporates changes to the search indexing, user + accounts, menu management, ontology, and visualizations. +
+

Search

+ VIVO 1.3 will feature notable improvements to the local search, + primarily to improve relevance ranking but also to boost the influence + of semantic relationships in the search. This will improve recall by + including text from related resources (e.g., adding a person’s grant + and publication titles to his or her search entry) and by boosting + overall relevance ranking based on the number and nature of connections + from one individual to others. +
+ VIVO is now using Apache Solr (http://lucene.apache.org/solr/) in place + of Apache Lucene to improve indexing and faceting of search results. + The migration to Solr also aligns the local search with the VIVO + multi-site search site under development for release prior to the 2011 + VIVO Conference. +
+

Authorization

+ Release 1.3 provides an entirely new model of authorization within the + VIVO application to allow more granular control over system + configuration and editing. The first phase of the new user account + interface is included in V1.3. This interface provides a user search, a + root acount, and password reset functionality where the password gets + emailed to the user. The next phase will provide the ability to create + new roles. +
+

Menu management

+ The menus across the top of the site (Home, People, Organizations, + Research, Events) can now be managed in a web form instead of editing + an RDF file. In addition to making site management much easier, + form-based editing also allows more control over what classes of data + are displayed and provides a mechanism to limit certain menu pages to + content identified as internal to the institution. +
+

FreeMaker template improvements

+ While less directly visible to the public, version 1.3 also includes + additional changes focused directly on supporting open source community + involvement in extending and customizing VIVO. The development team + began a year ago to transition VIVO’s code base away from Java Server + Pages to the FreeMarker page templating system that much more cleanly + separates internal application programming logic from page display. +
+

Visualization

+ The visualization team has implemented a Science Map visualization, + which allows users to visually explore the scientific strengths of a + university, school, department, or person in the VIVO instance. Users + will be able to see where an organization or person’s interests lay + across 13 major scientific disciplines or 554 sub-disciplines, and will + be able to see how these disciplines and sub-disciplines interrelate + with one another on the map of science. Wireframes and design + documentation for upcoming enhanced versions of the Science Map + visualization have already been developed; the Science Map + visualization will most likely be in the form of a PDF that a user can + download. +
+ Several visualization also now provide a caching feature that improves + performance after the initial processing. +
+

QR Codes

+ Pages for people in VIVO have the option of displaying QR codes. +
+

Ontology changes

+ +

Linked open data

+ Responses to linked data requests have been enhanced to include + additional context about any individual, in working toward a goal of + being able to provide all the data in a person's profile available as + RDF via a single web request. +
+
+

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

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

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

+

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

+

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

+ +
+ + +