------------------------------------------------------------------------------- This is a summary of the VIVO installation process. This and other documentation can be found at: http://vivoweb.org/support PLEASE NOTE! 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. Upgrade: If you are going to upgrade an existing service, please consult the upgrade.txt in this directory. 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. ------------------------------------------------------------------------------- * I. Install required software * II. Create an empty MySQL database * III. Download the VIVO code distribution * IV. Specify deployment properties * V. Compile and deploy * VI. Set Tomcat JVM Parameters * VII. Start Tomcat * VIII. Log in and add RDF data * IX. Create an initial Lucene search index * X. Setup Apache Tomcat Connector * XI. Configure Pellet Reasoner * XII. 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.5 or higher [http://java.sun.com/javase/downloads/] * Apache Tomcat 5.x or higher* [http://tomcat.apache.org] * Apache Ant [http://ant.apache.org/] * MySQL 4.1 or higher [http://www.mysql.com/downloads/mysql/#downloads] * Subversion client (developers only) ------------------------------------------------------------------------------- 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 the next step. ------------------------------------------------------------------------------- III. Download the VIVO code distribution Download either a zip or gz file and unpack it on your web server: ftp://download.mannlib.cornell.edu/pub/Vivo/rel-1.0.zip ftp://download.mannlib.cornell.edu/pub/Vivo/rel-1.0.tar.gz ------------------------------------------------------------------------------- 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. Directory where Vitro code is located (this is used by developers, and should not be changed) property name: vitro.core.dir example value: ./vitro-core Directory where tomcat is installed property name: tomcat.home example value: /usr/local/tomcat Name of your VIVO application property name: webapp.name example value: vivo Directory where uploaded files will be stored property name: upload.directory example value: /usr/local/vivo/data/uploads Directory where the Lucene search index will be built. property name: LuceneSetup.indexDir example value: /usr/local/vivo/data/luceneIndex Specify the namespace in which the Vitro editor should create new ABox and portal resources Note that the trailing slash is essential. property name: Vitro.defaultNamespace example value: http://vivo.mydomain.edu/individual/ Specify an SMTP host that the form will use for sending e-mail (Optional) property name: Vitro.smtpHost example value: smtp.servername.edu Specify the JDBC URL of your database. Change the end of the URL to reflect your database name (if it is not "vivo"). property name: VitroConnection.DataSource.url example value: jdbc:mysql://localhost/vivo Change the username to match the authorized user you created in MySQL property name: VitroConnection.DataSource.username example value: username Change the password to match the password you created in MySQL property name: VitroConnection.DataSource.password example value: password Specify the name of your first admin user for the VIVO application. This user will have an initial password of 'defaultAdmin'. This will be changed on first login. property name: initialAdminUser example value: defaultAdmin ------------------------------------------------------------------------------- V. Compile and deploy At the command line, from the top level of the unpacked distribution directory, type: ant clean deploy to build VIVO and deploy to Tomcat's webapps directory. ------------------------------------------------------------------------------- VI. Set Tomcat JVM Parameters 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. For example: export CATALINA_OPTS="-Xms1024m -Xmx1024m -XX:MaxPermSize=64m" sets Tomcat to allocate an initial heap of 1024 megabytes, a maximum heap of 1024 megabytes, and a PermGen space of 64 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, increasing the heap parameters is the typical remedy. ------------------------------------------------------------------------------- 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. (More information about detailed error logging to be added here.) ------------------------------------------------------------------------------- VIII. Log in and add RDF data If the startup was successful, you will see a relatively empty screen with the VIVO logo in the header. 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 the initialAdminUser is defaultAdmin. 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, datatype 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. More documentation is forthcoming. VIVO comes with an ontology, but you may also upload another ontology 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 at vivoweb.org. ------------------------------------------------------------------------------- IX. Create an initial Lucene search index Invoke the indexing servlet by requesting http://localhost:8080/vivo/SearchIndex You will not see any output to the browser (though this will change in future versions). When your browser switches to a blank screen, the indexing has completed and the search box on the Vitro portal will be usable. Individuals that are created, edited, or deleted from the Vitro editing interface will trigger incremental updates of the search index. ------------------------------------------------------------------------------- X. Setup Apache Tomcat Connector It is recommend that a Tomcat Connector, such as mod_jk be used to ensure that the site address does not include the port number and any extraneous Tomcat context. For example - 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 http://tomcat.apache.org/connectors-doc/generic_howto/quick.html describes the minimum server configurations for several popular web servers. ------------------------------------------------------------------------------- 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 it 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), openvitro-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 datatype property entailments are not needed. ------------------------------------------------------------------------------- XII. 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. * Step IX initialized the Lucene Search system. Though there is very little feedback for a successful installation, there are dramatic indications for failures. Here is a simple test to see whether the ontology files were loaded: * Point your browser to http://localhost:8080/vivo, 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. * Click on the "Index" link on the upper left, below the logo. You should see a "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. Finally, test the search index. * The search box is on the right side, directly opposite the "Index" link. Type the word "Afghanistan" into the box, and click on the "Search" button.You should see a page of results, with links to countries that border Afghanistan, entities that include Afghanistan, and to Afghanistan itself.