-

Vitro Version 1.6. Installation Guide

- - October 9, 2013 - - - - - -
-

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

-

- These instructions assume that you are performing a clean install, - starting with an empty database, an empty Vitro home directory, - and a Tomcat installation with no Vitro webapp. - If you are upgrading a previous installation of Vitro, - you may need to adjust your procedure accordingly. -

-

- Other servlet containers: If you want to use a servlet container - other than Tomcat, please consult - instructions for other servlet containers in this directory. -

- -

Introduction to the Vitro installation

- -

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

- -

Where does Vitro live on your computer?

-

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

-

The Vitro distribution directory

-

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

-

Vitro inside Tomcat

-

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

-

The Vitro home directory

-

- This directory contains the runtime configuration properties for Vitro. - Vitro will also use this area to store some of the data it uses. Uploaded - image files are stored here, and the Solr home directory is stored here also. - You can create this wherever you choose. Tell Vitro where to find the - home directory by setting vitro.home in the - build.properties file (see installation step IV, - below). You must create this directory before starting Vitro, - you must create the runtime.properties file in this directory - (see Step VI, below), and you - must ensure that Tomcat has permission to read and write to this - directory when it runs. -

-

The MySQL database

-

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

- -

The relationship between Vitro and VIVO

- -

“Vitro Inside”

-

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

-

- In 2009, the National Institutes of Health (NIH) awarded a major grant to advance the development of VIVO. - Much of the recent development on Vitro has been in support of that grant. - However, Vitro retains its own identity, - and still serves as the core of many projects and products. - Some of these are currently in use, and some are still in the planning stages. -

-

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

-

- -

Release schedule and names

-

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

- -

Installation process for Version 1.6

-

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

- -

Steps to Installation

-
    -
  1. - Install required software -
    2. -
  2. - Create an empty MySQL database -
    3. -
  3. - Check out the Vitro Source Code -
    4. -
  4. - Specify build properties -
    5. -
  5. - Compile and deploy -
    6. -
  6. - Specify runtime properties -
    7. -
  7. - Configure Tomcat -
    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. - Set up Apache HTTPD -
    12. -
  12. - Using an External Authentication - System with Vitro -
    13. -
  13. - Was the installation successful? -
    14. -
  14. - Review the Vitro Terms of Use -
    15. -
- -

I. Install required software

-

- Before installing Vitro, 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. -

- -

- The following browsers are supported for this release -

- - -

II. Create an empty MySQL database

-

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

- 
                CREATE DATABASE dbname CHARACTER SET utf8;
-

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

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

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

-

III. Check out the Vitro Source Code -
-

-

- Download the latest stable release of Vitro from SourceForge: - go to - 

      http://sourceforge.net/projects/vivo/files/Vitro%20Application%20Source/
- and download either vitro-rel-1.6.zip or vitro-rel-1.6.tar.gz -

-

- If you want the very latest Vitro source, you can use subversion to check it out from SourceForge: - 

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

- -

IV. Specify build properties

-

- In the webapp/config directory of the Vitro distribution, - copy the file example.build.properties - to a file named simply build.properties. - Edit the file to suit your installation, as described in the following table. -

-

- These properties are used in compilation and deployment. - They will be incorporated into Vitro when it is compiled in - Step V. If you want to change these properties at - a later date, you will need to stop Tomcat, repeat Step V, - and restart Tomcat. -

-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Directory where tomcat is installed. -
- tomcat.home - - /usr/local/tomcat -
- Name of your Vitro application. -
- webapp.name - - vitro -
- Directory where the Vitro 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 - - /usr/local/vitro/home -
- Languages (in addition to American English) that will be built into your - Vitro site. The languages must be found in the - languages directory of the Vitro distribution. - See - the VIVO Wiki for more information. -
- languages.addToBuild - - es_MX -
- -

V. Compile and deploy

-

- In Step IV, you defined the location of the VIVO home directory, - by specifying vitro.home in the build.properties file. - Create that directory now. -

-

- At the command line, change to the webapp directory inside the Vitro distribution - directory. Then type: -

- 
    ant all
-

- to build Vitro and deploy to Tomcat's webapps directory. -

-

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

-

-

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

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

- -

VI. Specify runtime properties

-

- The build process in Step V created a file called example.runtime.properties - in your Vitro home directory (vitro.home in the build.properties file). - Rename this file to runtime.properties, and - edit the file to suit your installation, as described in the following table. -

-

- These properties are loaded when Vitro 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 Step V. -

-

- 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 an additional property in this file. See the section below - entitled Using an External Authentication System with Vitro. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Property Name - - Example Value -
- Default namespace: Vitro 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, Vitro's default namespace must have a - certain structure and begin with the public web address of the Vitro - installation. For example, if the web address of a Vitro installation is - "http://vitro.example.edu/" the default namespace must be set to - "http://vitro.example.edu/individual/" in order to support linked data. - Similarly, if Vitro is installed at "http://www.example.edu/vitro" the - default namespace must be set to - "http://www.example.edu/vitro/individual/" -
* The namespace must end with "individual/" (including the trailing slash).
-
- Vitro.defaultNamespace - - http://vitro.mydomain.edu/individual/ -
- URL of Solr context used in local Vitro search. - Should consist of:
    scheme + servername + port + vitro_webapp_name + "solr"
- In the standard installation, the Solr context will be on the same - server as Vitro, and in the same Tomcat instance. The path will be the - Vitro webapp.name (specified above) + "solr" -
- vitro.local.solr.url - - http://localhost:8080/vitrosolr -
- 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 - - vitroAdmin@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 "vitro"). -
- VitroConnection.DataSource.url - - jdbc:mysql://localhost/vitro -
- Change the username to match the authorized user - you created in MySQL. -
- VitroConnection.DataSource.username - - username -
- Change the password to match the password you - created in MySQL. -
- VitroConnection.DataSource.password - - password -
- Specify the maximum number of active connections - in the database connection pool to support the anticipated number of - concurrent page requests. -
- 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 Vitro 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 Vitro. 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 - - vitroAdmin@my.domain.edu -
- The URI of a property that can be used to - associate an Individual with a user account. When a user logs in with a - name that matches the value of this property, the user will be - authorized to edit that Individual - (the value of the property must be either a String literal or an untyped literal). -
- selfEditing.idMatchingProperty - - http://vitro.mydomain.edu/ns#networkId -
- If an external authentication system like Shibboleth or CUWebAuth is to be - used, this property says which HTTP header will contain the user ID from - the authentication system. If such a system is not to be used, - leave this commented out. -
- externalAuth.netIdHeaderName - - remote_userID -
- Tell Vitro 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. Default is false if not set. - For more information, see the VIVO wiki page: - - Use HTTP caching to improve performance -
- http.createCacheHeaders - - true -
- Show only the most appropriate data values based on the Accept-Language - header supplied by the browser. Default is false if not set. -
- RDFService.languageFilter - - false -
- Force VIVO to use a specific language or Locale instead of those - specified by the browser. - This affects RDF data retrieved from the model, if RDFService.languageFilter is true. - This also affects the text of pages that have been modified to support multiple languages. -
- languages.forceLocale - - en_US -
- A list of supported languages or Locales that the user may choose to - use instead of the one specified by the browser. Selection images must - be available in the i18n/images directory of the theme. - This affects RDF data retrieved from the model, if RDFService.languageFilter is true. - This also affects the text of pages that have been modified to support multiple languages. -
- languages.selectableLocales - - en, es, fr_FR -
- -

VII. Configure Tomcat

-

Set JVM parameters

-

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

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

- This sets 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 suffice, especially for small test installations. -

-

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

-

Set security limits

-

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

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

- 
-                    <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 Vitro distribution (Vitro 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 Section XI below, - for an example of overriding the Vitro context fragment. -

- -

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/vitro/" to test the application. -

-

- On start up Vitro will run some diagnostic tests. If a - problem is detected, the normal Vitro pages will redirect - to a startup status page describing the problem. You - can stop tomcat, attempt to fix the problem and - proceed from Step V. If the problem is not serious, the - startup status page may offer a continue link which - will allow you to use VIVO in spite of the problems. -

-

- If Tomcat does not start up, or the Vitro 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 Vitro. Click the "Log - in" link near the upper right corner. Log in with the rootUser.emailAddress - you set up in Step IV. The initial password for the root account is - "rootPassword" (without the quotes). On first login, you will be - prompted to select a new password and verify it a second time. When login is - complete, the search index is checked and, if it is empty, - a full index build will be triggered in the background, in order to ensure - complete functionality throughout the site. -

-

- After logging in, you will be presented with a - menu of editing options. Here you can create OWL classes, object - properties, data properties, and configure the display of data. - Currently, any classes you wish to make visible on your website must be - part of a class group, and there are a number of visibility and display - options available for each ontology entity. Vitro comes with a minimal - ontology. You will likely want to upload additional 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. -

- -

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 Vitro 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 HTTPD

-

- It is recommended to run an Apache HTTPD web server to accept requests - and then proxy them to the VIVO Tomcat context. This will make Vitro - available at "http://example.com" instead of "http://example.com:8080/vitro". - It will also allow the use of external authentication. -

-

- Setup HTTPD to send all of the requests that it receives to Tomcat's AJP - connector. This can be done in HTTPD 2.x with a simple directive in httpd.conf: -

- 
     ProxyPass / ajp://localhost:8009/

-

- Modify the <Host> in Tomcat server.xml (located in [tomcat root]/conf/) - so that the context path is empty to allow VIVO to be servred from the root path. - 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/vitro"
-                           reloadable="true"
-                           cookies="true" >
-
-                       <Manager pathname="" />
-                   </Context>
-
-                   ...
-
-

- After setting up the above, it is recommended that you modify the Tomcat AJP connector - parameters in server.xml. Look for the <connector> directive and add the - following properties: -

- 
    connectionTimeout="20000" maxThreads="320" keepAliveTimeout="20000" 

-

- Note: the value for maxThreads (320) is equal or greater than the value for - MaxClients in the apache's httpd.conf file. -

- -

XII. Using an External Authentication System - with Vitro

-

-

-

- Vitro can be configured to work with an external authentication - system like Shibboleth or CUWebAuth. -

-

- Vitro 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 Vitro, to identify the user. -

-

- If Vitro has an account for that user, the user will be logged in - with the privileges of that account. In the absence of an account, Vitro - 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 Vitro. When a user reaches this secured - page, the Apache server will invoke the external authentication system. -

-

- For Vitro, 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 Vitro

-

- To enable external authentication, Vitro requires three values in - the runtime.properties - file. -

- -

XIII. Was the installation successful?

-

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

- -

- Step VIII also shows that the Vitro self-tests ran successfully. - When Tomcat starts the Vitro webapp, it runs several tests. - If any of these tests produce warnings or error message, - you would see them instead of the Vitro home page. -

-

- Among other things, the self-tests check -

- If you saw the Vitro home page in Step VII, you know that your installation passed all of these tests. -

- -

XIV. Review the Vitro Terms of Use

-

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

[vitro_source_dir]/webapp/web/templates/freemarker/body/termsOfUse.ftl
-

-

- Your "Terms of Use" statement is also referenced in the Linked Open Data (RDF) - that your site produces, so you should be sure that it accurately reflects - the way that your data may be used. -

-

- Be sure to make the changes in your source files and deploy them to your - tomcat so you don't lose your changes next time you deploy for another reason. -

-

Next Steps

-

- For more information about Vitro see the Vitro public website. - In addition, you may find helpful information in the - VIVO Site Administrator's Guide. -

-

- Send questions or comments to Vitro developers and designers at vivo-dev-all@lists.sourceforge.net. -

-

-

-