VIVO Release 1 V1.2 Installation Guide
+-
+
- + Release announcement for V1.2 + +
- + Installation process for V1.2 + +
Release anouncement for V1.2
++ Text from the wiki page +
+Installation process for V1.2
++ This document is a summary of the VIVO installation process. This and other + documentation can be found on the spport page + at VIVOweb.org +
+-
+
- + These instructions assume that you are performing a clean install, including + emptying an existing database and removing a previous installation from the + Tomcat webapps directory. Product functionality may not be as expected if you + install over an existing installation of an earlier version. + +
- + If you are going to upgrade an existing service, please consult the upgrade.txt + in this directory. + +
Steps to Installation
+-
+
- + Install required software + +
- + Create an empty MySQL database + +
- + Download the VIVO Application Source + +
- + Specify deployment properties + +
- + Compile and deploy + +
- + Set Tomcat JVM parameters and security limits + +
- + Start Tomcat + +
- + Log in and add RDF data + +
- + Set the Contact Email Address (if using "Contact Us" form) + +
- + Setup Apache Tomcat Connector + +
- + Configure Pellet Reasoner + +
- + Using an External Authentication System with VIVO + +
- + Was the installation successful? + +
I. Install required software
++ Before installing VIVO, make sure that the following software is + installed on the desired machine: +
+-
+
- + Java (SE) 1.6 or higher, http://java.sun.com + (Not OpenJDK) + +
- + Apache Tomcat 6.x or higher, http://tomcat.apache.org + +
- + Apache Ant 1.7 or higher, http://ant.apache.org + +
- + MySQL 5.1 or higher, http://www.mysql.com + +
+ Be sure to setup 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 web sites. +
+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.1.1.zip or
+ rel-1.1.1.gz file and unpack it on your web
+ server:
+
+ http://vivoweb.org/download
+
IV. Specify deployment properties
++ At the top level of the unpacked distribution, 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 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, but it commonly points elsewhere during development. + | +|
| + vitro.core.dir + | ++ ./vitro-core + | +
| + Directory where tomcat is installed. + | +|
| + tomcat.home + | ++ /usr/local/tomcat + | +
| + Name of your VIVO application. + | +|
| + webapp.name + | ++ vivo + | +
| + Directory where uploaded files will be stored. You must create this directory ahead of time. + | +|
| + upload.directory + | ++ /usr/local/vivo/data/uploads + | +
| + Directory where the Lucene search index will be built. Depending on your + permissions and who Tomcat is running as, you may need to create this directory + ahead of time. + | +|
| + LuceneSetup.indexDir + | ++ /usr/local/vivo/data/luceneIndex + | +
| + Specify an SMTP host that the form will use for sending e-mail (Optional). If + this is left blank, the contact form will be hidden and disabled. + | +|
| + Vitro.smtpHost + | ++ smtp.servername.edu + | +
| + Specify the JDBC URL of your database. Change the end of theURL 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 name of your first admin user for the VIVO application. This user + will have an initial temporary password of 'defaultAdmin'. You will be prompted to + create a new password on first login. + | +|
| + initialAdminUser + | ++ defaultAdmin + | +
| + The name of a property that can be used to associate an Individualwith a user + account. When a user logs in with a name that matches the value of this property, + the user will be authorized to editthat Individual. + | +|
| + selfEditing.idMatchingProperty + | ++ http://vivo.mydomain.edu/ns#networkId + | +
V. Compile and deploy
++ At the command line, from the top level of the unpacked 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 databaseare 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.
+
+ 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 + catalina.out file in Tomcat's logs directory. +
+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 initialAdminUser + username you set up in Step IV. The initial password for the initialAdminUser + account is "defaultAdmin" (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 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 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 left 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 (Vitro.smtpHost), you will also need to add an email address + to the VIVO application. This is the email that the contact form + submits to. 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 theVitro.smtpHost + in Step IV and do NOT provide an email addressin 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 ([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: +
+ + + ++++ example.com ++ ++ +
XI. Configure Pellet Reasoner
++ VIVO uses the Pellet engine to perform reasoning, which runs in the + background at startup and also when the knowledge base is edited. VIVO + continues serving pages while the reasoner continues working; when the + reasoner finishes, the new inferences appear. Inferred statements are + cached in a database graph so that they are available immediately when + VIVO is restarted. By default, Pellet is fed only an incomplete view of + your ontology and only certain inferences are materialized. These + include rdf:type, rdfs:subClassOf,owl:equivalentClass, and + owl:disjointWith. This mode is typically suitable for ontologies with a + lot of instance data. If you would like to keep the default mode, + skip to the next step. To enable "complete" OWL inference (materialize + all significant entailed statements), open + "vitro-core/webapp/config/web.xml" and search for PelletReasonerSetup. + Then change the name of the listener class to + PelletReasonerSetupComplete. Because "complete" reasoning can be very + resource intensive, there is also an option to materialize nearly + all inferences except owl:sameAs and owl:differentFrom. This is enabled + by specifying PelletReasonerSetupPseudocomplete. For ontologies with + large numbers of individuals, this mode can offer enormous performance + improvements over the "complete" mode. Finally, a class called + PelletReasonerSetupPseudocompleteIgnoreDataproperties is provided to + improve performance on ontologies with large literals where data + property entailments are not needed. +
+XII. Using an External Authentication System with VIVO
++ VIVO can be configured to work with an external authentication + system + like Shibboleth or CUWebAuth. VIVO must be accessible only through an + Apache HTTP server. The Apache server will be configured to invoke the + external authentication system. When the user completes the + authentication, the Apache server will pass a network ID to VIVO, to + identify the user. If VIVO has an account for that user, the user will + be logged in with the privileges of that account. In the absence of an + account, VIVO will try to find a page associated with the user. + If such a page is found, the user can log in to edit his own profile + information.---- Configuring the Apache server: Your institution will + provide you with instructions for setting up the external + authentication system. The Apache server must be configured to secure a + page in VIVO. When a user reaches this secured page, the Apache + server will invoke the external authentication system.For VIVO, this + secured page is named: /loginExternalAuthReturn When your instructions + call for the location of the secured page, this is the value you should + use.---- Configuring VIVO: To enable external authentication, VIVO + requires three values in the deploy.properties file.* The name of the + HTTP header that will hold the external userâÃÑÃ¥s network + ID When a user completes the authentication process, the Apache server + will put the userâÃÑÃ¥s network ID into one of the headers + of the HTTP request. The instructions from your institution + should tell you which header is used for this purpose. You need + to tell VIVO the name of that HTTP header. Insert a line like this in + the deploy.properties file:externalAuth.netIdHeaderName = [the header + name]For example: externalAuth.netIdHeaderName = remote_userID * The + text for the Login button To start the authentication process, the user + will click on a button in the VIVO login form. You need to tell VIVO + what text should appear in that button.Put a line like this in the + deploy.properties file:externalAuth.buttonText = [the text for your + login button]For example:externalAuth.buttonText = Log in using BearCat + ShibbolethThe VIVO login form will display a button labelled + âÃÑúLog in using BearCat ShibbolethâÃÑù.* Associating a + User with a profile page If VIVO has an account for the user, the user + will be given the privileges assigned to that account.In addition, VIVO + will try to associate the user with a profile page, so the user + may edit his own profile data. VIVO will search the data model for a + person with a property that matches the UserâÃÑÃ¥s network + ID.You need to tell VIVO what property should be used for matching. + Insert a line like this in the deploy.properties + file:selfEditing.idMatchingProperty = [the URI of the property]For + example:selfEditing.idMatchingProperty = + http://vivo.mydomain.edu/ns#networkId +
+XIII. Was the installation successful?
++ If you have completed the previous steps, you have good indications + that the installation was successful. * Step VII showed that + Tomcat recognized the webapp, and that the webapp was able to present + the initial page.* Step VIII verified that you can log in to the + administrator account.Here is a simple test to see whether the ontology + files were loaded:* Click on the "Index" link on the upper left, below + the logo. You should seea "locations" section, with links for "Country" + and "Geographic Location."The index is built in a background thread, so + on your first login, you may see an empty index instead. Refresh the + page periodically to see whether the index will be populated. This may + take some time: with VIVO installed on a modest laptop computer, + loading the ontology files and building the index took more than 5 + minutes from the time that Tomcat was started. * Click on the "Country" + link. You should see an alphabetical list of the countries of the + world.Here is a test to see whether your system is configured to serve + linked data: * 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 + initialAdminUser username you set up in Step IV. 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 tothe 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 theprevious + 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.Finally, test the search index. * The + search box is on the right side, directly opposite the "Index" link. + Type the word "Australia" into the box, and click on the "Search" + button.You should see a page of results, with links to countries that + border Australia, individuals that include Australia, and to Australia + itself. +
+