Versions Compared

Old Version 3

changes.mady.by.user Jim Blake

Saved on

compared with

New Version Current

changes.mady.by.user Alvin Hutchinson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Panel
Excerpt
This section describes the process of getting

How to get VIVO up and running on your computer, for testing or experimentation, or just to

gain familiarity with the process

learn how to do it.

If you want to install VIVO on a production server, or if you want to develop VIVO code, you should also read the section on Installation options.

...

Preparing for VIVO

Install required software

Before installing VIVO, make sure that the following software is installed on the desired machineyour computer:

Be sure to set Set up the environment variables for JAVA_HOME and ANT_HOME and add the executables to your path, as required. This requirement depends on the operating system you are using. Consult the installation directions from the software support websites.

...

Log into your MySQL server and create a new database in MySQL that uses UTF-8 encoding. 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 be localhost.

...

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

...

At the top level of the VIVO distribution directory, copy rename the file example.build.properties to a file named simply build.properties. Edit the file to suit your installation, as described in the following tablesection.

These properties are used in compiling VIVO and deploying it to Tomcat. They will be incorporated into VIVO when it is compiled. If you want to change these properties at a later date, you will need to stop Tomcat, repeat the Compile and deploy step, and restart Tomcat.

...

Property name

vitro.core.dir

DescriptionThe directory where Vitro code is located. In most deploymentsthe simple installation, this is set to ./vitro-core (It is not uncommon for this setting to point elsewhere in development environments).
Default valueNONE
Example valueExample value./vitro-core
Property name

tomcat.home

DescriptionThe directory where tomcat is installed.
Default valueNONE
Example valueExample value/usr/local/tomcat
Property name

webapp.name

DescriptionThe name of your VIVO application. This is not a name that will be displayed to the user. This name appears in the URL used to access VIVO, and in the path to the VIVO directory within Tomcat.
Default valueNONE
Example valueExample valuevivo
Property name

vitro.home

DescriptionThe directory where VIVO 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 Tomcat service.
Default valueNONE
Example valueExample value/usr/local/vivo/home

Compile and deploy

In the previous step, you defined the location of the VIVO home directory, by specifying vitro.home in the build.properties file. If that directory does not exist, create it now.

 

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

...

The build script may run for as much as five minutes, and creates more than 100 lines of output. The process comprises includes several steps:

  • collecting the source files from the distribution directory,
  • compiling the Java source code,
  • compiling and running unit tests,
  • preparing the Solr search engine,
  • deploying VIVO and Solr to Tomcat.

Did it work?

The output of the build may include a variety of warning messages. The Java compiler may warn of code that is outdated. Unit tests may produce warning messages, and some tests may be ignored if they do not produce consistent results.

BUILD SUCCESSFUL
Total time: 1 minute 49 seconds

If the output ends with a success message, the build was successful. Proceed to the next step.

Panel

BUILD SUCCESSFUL

Total time: 1 minute 49 seconds

If the output ends with a success message, the build was successful. Proceed to the next step.

BUILD FAILED
Total time: 35 seconds

If the output ends with a failure message, the build has failed. Find the cause of the failure, fix the problem, and run the script again.

Running VIVO

Configure Tomcat

Set JVM parameters

VIVO copies small sections 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 may 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:

Code Block
export CATALINA_OPTS="-Xms512m -Xmx512m -XX:MaxPermSize=128m"

This configures Tomcat to allocate an initial heap of 512 megabytes, a maximum heap of 512 megabytes, and a PermGen space of 128 megs. Lower values may be sufficient, especially for small test installations.

If an OutOfMemoryError is encountered during VIVO execution, it can be remedied by increasing the heap parameters and restarting Tomcat.

Set 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:

Code Block
apache	hard	nproc	400
tomcat6	hard	nproc	1500

Set URI encoding

In order for VIVO to correctly handle international characters, you must configure Tomcat to conform to the URI standard by accepting percent-encoded UTF-8.

Edit Tomcat's conf/server.xml and add the following attribute to each of the Connector elements: URIEncoding="UTF-8".

Code Block
<Server ...>
  <Service ...>
    <Connector ... URIEncoding="UTF-8"/>
      ...
    </Connector>
  </Service>
</Server>
Note

Some versions of Tomcat already include this attribute as the default.

Take care when creating Context elements

Each of the webapps in the VIVO distribution (VIVO and Solr) includes a "context fragment" file, containing some of the deployment information for that webapp.

Tomcat allows you to override these context fragments by adding Context elements to server.xml. If you decide to do this, be sure that your new Context element includes the necessary deployment parameters from the overridden context fragment.

See the section entitled Running VIVO behind an Apache server for an example of overriding the VIVO context fragment.

Specify runtime properties

The build process in the Compile and deploy step created a file called example.runtime.properties in your VIVO home directory (specified by vitro.home in the build.properties file). Rename this file to runtime.properties and edit the file to suit your installation, as described below.

These properties are loaded when VIVO starts up. If you want to change these properties at a later date, you will need to restart Tomcat for them to take effect. You will not need to repeat the Compile and deploy step.

Note

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.

Basic properties

These properties define some fundamental aspects of your VIVO installation. Most sites will need to modify all of these values.

Property name

Vitro.defaultNamespace

Description

The default RDF namespace for this installation.

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

Default valueNONE
Example valuehttp://vivo.mydomain.edu/individual/
Property name

rootUser.emailAddress

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

Default valueNONE
Example valuevivoAdmin@my.domain.edu
Property name

VitroConnection.DataSource.url

Description Specify the JDBC URL of your database. Change the end of the URL to reflect your database name (if it is not "vivo").
Default valueNONE
Example valuejdbc:mysql://localhost/vivo
Property name

VitroConnection.DataSource.username

Description Change the username to match the authorized user you created in MySQL.
Default valueNONE
Example valueusername
Property name

VitroConnection.DataSource.password

Description Change the password to match the password you created in MySQL.
Default valueNONE
Example valuepassword
Property name

email.smtpHost

DescriptionSpecify 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.
Default valueNONE
Example valuesmtp.servername.edu
Property name

email.replyTo

DescriptionSpecify 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.
Default valueNONE
Example valuevivoAdmin@my.domain.edu

Extended properties

These are properties that many sites will not need to modify.

Property name

vitro.local.solr.url

Description

URL of Solr context used in local VIVO search. Should consist of:

Pre
scheme + servername + port + vivo_webapp_name + "solr"

 

In the standard installation, the Solr context will be on the same server as VIVO, and in the same Tomcat instance. The path will be the VIVO webapp.name (specified above) + "solr"

Default valueNONE
Example valuehttp://localhost:8080/vivosolr
Property name

selfEditing.idMatchingProperty

DescriptionThe URI of a property that can be used to associate an Individual with a user account. When a user logs in with a name that matches the value of this property, the user will be authorized to edit that Individual (the value of the property must be either a String literal or an untyped literal). 
Default valueNONE
Example valuehttp://vivo.mydomain.edu/ns#networkId
Property name

homePage.geoFocusMaps

DescriptionOn the VIVO home page, display a global map highlighting the geographical focus of foaf:person individuals.
Default valueenabled
Example valuedisabled
Property name

multiViews.profilePageTypes

DescriptionMultiViews for foaf:person profile pages. VIVO supports the simultaneous use of a full foaf:Person profile page view and a "quick" page view that emphasizes the individual's own webpage presence. Implementing this feature requires an installation to develop a web service that captures images of web pages or to use an existing service outside of VIVO, usually for a small fee.
Default valuedisabled
Example valueenabled
Property name

http.createCacheHeaders

DescriptionTell VIVO to generate HTTP headers on its responses to facilitate caching the profile pages that it creates. This can improve performance, but it can also result in serving stale data. The default is false. For more information, see the VIVO wiki page: Use HTTP caching to improve performance
Default valuefalse
Example valuetrue
Property name

harvester.location

DescriptionIf you intend to run the VIVO Harvester utility from the VIVO ingest menu, you must tell VIVO how to find the Harvester code. An absolute file path, pointing to the root directory of the Harvester installation. You must include the final slash.
Default valueNONE
Example value/usr/local/vivo/harvester/
Property name

visualization.topLevelOrg

DescriptionThe 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 guess at the top level organization in your instance. If you're unhappy with this selection, set the value of the property 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
Default valueVIVO will infer the top level organization in your instance.
Example valuehttp://vivo.psm.edu/individual/n2862
Property name

visualization.temporal

DescriptionThe temporal graph visualization can require extensive machine resources. This can have a particularly noticable impact on memory usage if
  • The organization tree is deep,
  • The number of grants and publications is large.
VIVO V1.4 (and later) mitigates this problem by the way of a caching mechanism and hence we can safely set this to be enabled by default. 
Default valueenabled
Example valueenabled
Panel

BUILD FAILED

Total time: 35 seconds

The output of the build may include warning messages. The Java compiler may warn of code that is outdated. Unit tests may produce warning messages, and some tests may be ignored if they do not produce consistent results. If the output ends with a success message, these warnings may be ignored.

Note

What user account owns the VIVO directories?

In many operating systems, the issue of file permissions is important. Who owns the files? Who is authorized to read them, or to write new files?

When running the VIVO build script, it must have permission to read and write to:

  • the VIVO distribution directory
  • the Tomcat webapps directory
  • the VIVO home directory

When VIVO is started under Tomcat, Tomcat must have permission to read and write to:

  • the Tomcat webapps directory
  • the VIVO home directory

There are several ways to make this work. People who are experimenting with VIVO often use their own account to create the VIVO distribution directory, to run the build script, and to run Tomcat.

In more formal environments, it may be necessary to run Tomcat as a service, under its own account. In that case, some people choose to run the build script with root privilege, and then assign the resulting files to Tomcat:

Code Block
sudo ant all
sudo chown -R tomcat /usr/local/vivo/home
sudo chown -R tomcat /usr/local/tomcat/webapps/vivo*

When installing on Microsoft Windows, this is not usually a problem.

Running VIVO

Configure Tomcat

Set JVM parameters

VIVO copies small sections 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 may 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:

Code Block
titlesetenv.sh
export CATALINA_OPTS="-Xms512m -Xmx512m -XX:MaxPermSize=128m"

This tells Tomcat to allocate an initial heap of 512 megabytes, a maximum heap of 512 megabytes, and a PermGen space of 128 megs. Lower values may be sufficient, especially for small test installations.

If an OutOfMemoryError occurs during VIVO execution, increase the heap parameters and restart Tomcat.

Set 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:

Code Block
apache	hard	nproc	400
tomcat6	hard	nproc	1500

Set URI encoding

In order for VIVO to correctly handle international characters, you must configure Tomcat to conform to the URI standard by accepting percent-encoded UTF-8.

Edit Tomcat's conf/server.xml and add the following attribute to each of the Connector elements: URIEncoding="UTF-8".

Code Block
<Server ...>
  <Service ...>
    <Connector ... URIEncoding="UTF-8"/>
      ...
    </Connector>
  </Service>
</Server>
Note

Some versions of Tomcat already include this attribute as the default.

Take care when creating Context elements

Each of the webapps in the VIVO distribution (VIVO and Solr) includes a "context fragment" file, containing some of the deployment information for that webapp.

Tomcat allows you to override these context fragments by adding Context elements to server.xml. If you decide to do this, be sure that your new Context element includes the necessary deployment parameters from the overridden context fragment.

See the section entitled Running VIVO behind an Apache server for an example of overriding the VIVO context fragment.

Specify runtime properties

The build process in the Compile and deploy step created a file called example.runtime.properties in your VIVO home directory (specified by vitro.home in the build.properties file). Rename this file to runtime.properties and edit the file to suit your installation, as described below.

These properties are loaded when VIVO starts up. If you want to change these properties at a later date, you will need to restart Tomcat for them to take effect. You will not need to repeat the Compile and deploy step.

Note

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.

Basic properties

These properties define some fundamental aspects of your VIVO installation. Most sites will need to modify all of these values.

Property name

Vitro.defaultNamespace

Description

The default RDF namespace for this installation.

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

Default valueNONE
Example valuehttp://vivo.mydomain.edu/individual/
Property name

rootUser.emailAddress

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

Default valueNONE
Example valuevivoAdmin@my.domain.edu
Property name

VitroConnection.DataSource.url

Description Specify the JDBC URL of your database. Change the end of the URL to reflect your database name (if it is not "vitrodb").
Default valueNONE
Example valuejdbc:mysql://localhost/vivo
Property name

VitroConnection.DataSource.username

Description Change the username to match the authorized user you created in MySQL.
Default valueNONE
Example valueusername
Property name

VitroConnection.DataSource.password

Description Change the password to match the password you created in MySQL.
Default valueNONE
Example valuepassword
Property name

email.smtpHost

DescriptionSpecify 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.
Default valueNONE
Example valuesmtp.servername.edu
Property name

email.replyTo

DescriptionSpecify 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.
Default valueNONE
Example valuevivoAdmin@my.domain.edu

Connecting to the Solr search index

VIVO and its search index are actually two distinct web applications, and the simple installation puts them both into the same instance of Tomcat. Even so, the VIVO webapp must be told how to reach the Solr webapp.

Property name

vitro.local.solr.url

Description

URL of Solr context used in local VIVO search. Should consist of:

Pre
scheme + servername + port + vivo_webapp_name + "solr"

In the standard installation, the Solr context will be on the same server as VIVO, and in the same Tomcat instance. The path will be the VIVO webapp.name (specified above) + "solr"

Property name

proxy.eligibleTypeList

Description Types of individual for which we can create proxy editors. If this is omitted, defaults to http://www.w3.org/2002/07/owl#Thing

Default valueNONE
Example valuehttp://xmlns.com/foaf/0.1/Person, http://xmlns.com/foaf/0.1/Organizationlocalhost:8080/vivosolr

Additional properties

The runtime.properties file can accept many additional properties, but most of them don't apply to the standard they aren't necessary for this simple installation. If you choose any of the Installation options, you may will probably need to set some of those properties.

...

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 [tomcat]/logs/catalina.out, [tomcat]/logs/vivo.all.log or [tomcat]/logs/localhost.log

...

Note

Remember that Tomcat must have permission to read and write its own files, and the files in the VIVO home directory. This may mean that you must use a particular script or a particular user account to start Tomcat.

 

Start using VIVO

Log in and add RDF data

Direct your browser to the VIVO home page. Click the "Log in" link near the upper right corner. Log in with the rootUser.emailAddress that you set in the runtime.properties file. The initial password for the root account is rootPassword. When you first log in, VIVO will require you to change the password. When login is complete, the search index is checked and, if it is empty, a full index build will be triggered in the background, in order to ensure complete functionality throughout the site.

...

  • Point your browser to the home page of your website, and click the "Log in" link near the upper right corner. Log in with the rootUser.emailAddress you set up in Step IVin runtime.properties. If this is your first time logging in, you will be prompted to change the password.
  • After you have successfully logged in, click "site admin" in the upper right corner. In the drop down under "Data Input" select "Faculty Member(core)" and click the "Add individual of this class" button.
  • Enter the name "test individual" under the field "Individual Name," scroll to the bottom, and click "Create New Record." You will be taken to the "Individual Control Panel." Make note of the value of the field "URI" - it will be used in the next step.
  • Open a new web browser or browser tab to the page http://marbles.sourceforge.net/. In the pink box on that page enter the URI of the individual you created in the previous step and click "open."
  • In the resulting page search for the URI of the "test individual." You should find it towards the bottom of the page next to a red dot followed by "redirect (303)." This indicates that you are successfully serving linked RDF data. If the URI of the "test individual" is followed by "failed (400)" you are not successfully serving linked data.

...