From 60dfa6711078dbba7449bcea21f4bf702fc02936 Mon Sep 17 00:00:00 2001 From: ejc12 Date: Fri, 14 Jan 2011 22:27:13 +0000 Subject: [PATCH] The install.html is up2date with the content in index.txt, so I will ask developers to edit install.html instead of install.txt if no outstanding changes. --- doc/install.txt | 530 ------------------------------------------------ 1 file changed, 530 deletions(-) delete mode 100644 doc/install.txt diff --git a/doc/install.txt b/doc/install.txt deleted file mode 100644 index 2deeb1c3..00000000 --- a/doc/install.txt +++ /dev/null @@ -1,530 +0,0 @@ - -------------------------------------------------------------------------------- - -This document 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 Application Source - * IV. Specify deployment properties - * V. Compile and deploy - * VI. Set Tomcat JVM parameters and security limits - * VII. Start Tomcat - * VIII. Log in and add RDF data - * IX. Set the Contact Email Address (if using "Contact Us" form) - * X. Setup Apache Tomcat Connector - * XI. Configure Pellet Reasoner - * XII. Using an External Authentication System with VIVO - * XIII. 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. - -NOTE: 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". - - 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/ - Note: The namespace must end with "individual/" (including the - trailing slash). -property name: Vitro.defaultNamespace -example value: 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. -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. You must create - this directory ahead of time. -property name: upload.directory -example value: /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. -property name: LuceneSetup.indexDir -example value: /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. -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 Jena triple store technology to use. SDB is Jena's - SPARQL database; this setting allows RDF data to scale beyond the - limits of the JVM heap. Set to RDB to use the older Jena RDB - store with in-memory caching. -property name: VitroConnection.DataSource.tripleStoreType -example value: SDB - - Specify the maximum number of active connections in the database - connection pool to support the anticipated number of concurrent - page requests. It is not necessary to adjust this value when - using the RDB configuration. -property name: VitroConnection.DataSource.pool.maxActive -example value: 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. -property name: VitroConnection.DataSource.pool.maxIdle -example value: 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. -property name: VitroConnection.DataSource.dbtype -example value: 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. -property name: VitroConnection.DataSource.driver -example value: 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. -property name: VitroConnection.DataSource.validationQuery -example value: SELECT 1 - - 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. -property name: initialAdminUser -example value: defaultAdmin - - The name 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. -property name: selfEditing.idMatchingProperty -example value: http://vivo.mydomain.edu/ns#networkId - -NOTE: 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". - - Temporal Graph Visualization is used to compare different - organizations/people within an organization on different parameters - like number of publications, grants. This parameter will be used - as a default in case a URI is not provided. It will be also used - whenever this visualization is to be rendered for top level organization. - In absence of this parameter a SPARQL query will be fired which will - attempt to provide a top level organization.The name 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. -property name: visualization.topLevelOrg -example value: http://vivo-trunk.indiana.edu/individual/topLevelOrgURI - -NOTE: 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". - -------------------------------------------------------------------------------- - -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 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" - -This 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, 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 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, 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 the Vitro.smtpHost in Step IV and do NOT provide an email address -in 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). - -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. - -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 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 -httpd.conf file. - -Locate the 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 Shibboleth - - The 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 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. - -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 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. - -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.