299 lines
No EOL
13 KiB
Text
299 lines
No EOL
13 KiB
Text
|
||
-------------------------------------------------------------------------------
|
||
|
||
This is a brief summary of the VIVO installation process. A more detailed
|
||
explanation of the procedure can be found at:
|
||
|
||
http://vivoweb.org/support/user-guide/installation
|
||
|
||
The VIVO user guide is available at:
|
||
|
||
http://vivoweb.org/support/user-guide
|
||
|
||
PLEASE NOTE: It is assumed 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.
|
||
|
||
VIVO DEVELOPERS:
|
||
If you are working 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 <20>Pellet<65> 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, <20>Pellet<65> 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. |