NIHVIVO-3772 NIHVIVO-3721 Incorporate the OpenSocial integration from Eric Meeks at CTSI, UCSF. Add instructions on how to install and configure ORNG Shindig.
This commit is contained in:
j2blake
parent
182b4e7226
commit
2e69f0379b
16 changed files with 684 additions and 7 deletions
410
doc/setting_up_orng.html
Normal file
410
doc/setting_up_orng.html
Normal file
|
|
@ -0,0 +1,410 @@
|
|||
<!DOCTYPE HTML>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
||||
<meta charset="utf-8">
|
||||
<title>Setting up VIVO to use OpenSocial Gadgets</title>
|
||||
<link rel="stylesheet" href="./css/doc.css" media="screen">
|
||||
</head>
|
||||
<body>
|
||||
<div id="branding" role="banner">
|
||||
<h1 class="vivo-logo"><a href="/"><span class="displace">VIVO</span></a></h1>
|
||||
</div>
|
||||
<!-- Start of content -->
|
||||
<div id="wrapper-content" role="main">
|
||||
<h1>Setting up VIVO to use OpenSocial Gadgets</h1>
|
||||
<small>
|
||||
Instructions for connecting VIVO and Open Research Networking Gadgets
|
||||
</small>
|
||||
<p>
|
||||
This document contains instructions on how to configure your VIVO
|
||||
installation to use OpenSocial gadgets.
|
||||
</p>
|
||||
<p>
|
||||
VIVO uses an extension of the OpenSocial protocols called
|
||||
Open Research Networking Gadgets, or ORNG.
|
||||
ORNG is a project of the Clinical & Translational Science Institute at the
|
||||
University of California, San Francisco.
|
||||
You can find out more about the ORNG project at their web site,
|
||||
<a href="http://www.opengadgets.org/index.html">http://www.opengadgets.org/index.html</a>
|
||||
</p>
|
||||
<p>
|
||||
ORNG supports gadgets using a modified version of Apache Shindig.
|
||||
These instructions tell you how to install the ORNG Shindig web application,
|
||||
and how to configure it to work with VIVO.
|
||||
</p>
|
||||
|
||||
<hr/>
|
||||
<h3 id="tableofcontents">Table of Contents</h3>
|
||||
<toc>
|
||||
<ol class="roman2">
|
||||
<li><a href="#config_files">Create configuration files</a></li>
|
||||
<li><a href="#database">Create database tables and procedures</a></li>
|
||||
<li><a href="#tomcat_settings">Modify Tomcat settings</a></li>
|
||||
<li><a href="#deploy">Deploy the web application</a> <br>
|
||||
<li><a href="#vivo_settings">Configure VIVO</a></li>
|
||||
<li><a href="#confirm">Does it work?</a></li>
|
||||
</ol>
|
||||
</toc>
|
||||
<hr/>
|
||||
<h3 id="config_files">I. Create configuration files</h3>
|
||||
<p>
|
||||
In your VIVO home directory, create a directory called <em>shindig</em>.
|
||||
Under that, create directories called <em>conf</em> and <em>openssl</em>.
|
||||
Your VIVO home directory will look something like this:
|
||||
<pre> [VIVO home directory]
|
||||
|
|
||||
|--shindig
|
||||
| |
|
||||
| |--conf
|
||||
| |
|
||||
| |--openssl
|
||||
|
|
||||
|--solr
|
||||
|
|
||||
|--uploads</pre>
|
||||
</p>
|
||||
|
||||
<h4>A. Create a secure key file</h4>
|
||||
<p>
|
||||
Shindig uses an encryption key to insure that the communication
|
||||
between the gadget and the server is secure.
|
||||
You should create a file that contains the encryption key,
|
||||
and store that file in the <em>shindig/openssl</em> directory that you created.
|
||||
</p>
|
||||
<p>
|
||||
On Unix-based systems (like Linux or Mac OS X), this command will create
|
||||
an encryption key from a random seed:
|
||||
<pre>dd if=/dev/random bs=32 count=1 | openssl base64 > <em>[key-file]</em></pre>
|
||||
For example, if your VIVO home directory is <em>/usr/local/vivo/data</em>,
|
||||
you might use the command this way:
|
||||
<pre>dd if=/dev/random bs=32 count=1 | openssl base64 > /usr/local/vivo/data/shindig/openssl/securitytokenkey.txt</pre>
|
||||
</p>
|
||||
<p>
|
||||
If your VIVO installation is installed on a machine that runs Microsoft Windows,
|
||||
you will need to find another way to create an encryption key.
|
||||
The easiest way might be to find a Unix-based machine,
|
||||
issue the command above, and copy the resulting file to your Windows machine.
|
||||
</p>
|
||||
|
||||
<h4>B. Create the Create configuration files</h4>
|
||||
<p>
|
||||
In your VIVO distribution directory, find the file called
|
||||
<pre>vitro-core/opensocial/shindig.orng.properties</pre> and copy it to the
|
||||
<em>shindig/conf</em> directory that you created.
|
||||
</p>
|
||||
<p>
|
||||
Set these values in the <em>shindig.orng.properties</em> file
|
||||
</p>
|
||||
<table border='1' bordercolor="#CCCCCC" cellspacing="5">
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>
|
||||
Property Name
|
||||
</th>
|
||||
<th>
|
||||
Example Value
|
||||
</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
Specify the location of the encryption key file.
|
||||
</td>
|
||||
</tr>
|
||||
<tr class="odd_row">
|
||||
<td>
|
||||
shindig.signing.key-file
|
||||
</td>
|
||||
<td>
|
||||
/usr/local/vivo/data/shindig/openssl/securitytokenkey.txt
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
Specify the JDBC URL of your database. Change
|
||||
the end of the URL to reflect your database name (if it is not "vivo").
|
||||
</td>
|
||||
</tr>
|
||||
<tr class="odd_row">
|
||||
<td>
|
||||
orng.dbURL
|
||||
</td>
|
||||
<td>
|
||||
jdbc:mysql://localhost/vivo
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
Change the username to match the authorized user
|
||||
you created in MySQL when installing VIVO.
|
||||
</td>
|
||||
</tr>
|
||||
<tr class="odd_row">
|
||||
<td>
|
||||
orng.dbUser
|
||||
</td>
|
||||
<td>
|
||||
username
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
Change the password to match the password you
|
||||
created in MySQL when installing VIVO.
|
||||
</td>
|
||||
</tr>
|
||||
<tr class="odd_row">
|
||||
<td>
|
||||
orng.dbPassword
|
||||
</td>
|
||||
<td>
|
||||
password
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3 id="database">II. Create database tables and procedures</h3>
|
||||
<p>
|
||||
Shindig uses several database tables in MySQL to store its data:
|
||||
which gadgets appear on which pages, what size are the gadgets,
|
||||
what information applies to each individual, and more.
|
||||
Shindig also creates stored procedures in MySQL. These are small
|
||||
pieces of code that simplify the use of the database tables.
|
||||
</p>
|
||||
<p>
|
||||
In the VIVO distribution directory, a file called
|
||||
<em>vitro-core/opensocial/shindig_orng_tables.sql</em>
|
||||
contains SQL commands that create the tables and
|
||||
stored procedures for Shindig to use.
|
||||
</p>
|
||||
<p>
|
||||
Tell MySQL to process this file with a command like this:
|
||||
<pre>mysql -u <em>username</em> -p <em>database</em> < <em>sql_file</em></pre>
|
||||
So, if your current directory is the VIVO distibution directory, and your
|
||||
VIVO database is <em>vivoDb</em> and your MySQL user account is <em>vivoUser</em>,
|
||||
then you might use the command this way:
|
||||
<pre>mysql -u vivoUser -p vivoDb < vitro-core/opensocial/shindig_orng_tables.sql</pre>
|
||||
MySQL will prompt you for the password for your MySQL user account, and then
|
||||
process the file.
|
||||
</p>
|
||||
<p>
|
||||
You may want to start your gadget collection with some example gadgets
|
||||
that have been developed by the ORNG group. The file called
|
||||
<em>vitro-core/opensocial/shindig_example_gadgets.sql</em>
|
||||
contains SQL commands that will add these gadgets to your system's configuration.
|
||||
</p>
|
||||
<p>
|
||||
If you want to load these example gadgets, you can use a command similar to the previous one:
|
||||
<pre>mysql -u vivoUser -p vivoDb < vitro-core/opensocial/shindig_example_gadgets.sql</pre>
|
||||
As before, MySQL will prompt you for the password for your MySQL user account, and then
|
||||
process the file.
|
||||
</p>
|
||||
|
||||
<h3 id="tomcat_settings">III. Modify Tomcat settings</h3>
|
||||
<p>
|
||||
The Shindig application must know where to find the configuration file that you created in
|
||||
Step I.
|
||||
It must also know its own URL, so that URL can be inserted into the gadgets.
|
||||
</p>
|
||||
<p>
|
||||
This information is provided through startup parameters in Tomcat.
|
||||
With most installations of Tomcat, the "setenv.sh" or
|
||||
"setenv.bat" file in Tomcat's bin directory is a convenient place to
|
||||
set these parameters.
|
||||
<em>If this file does not exist in Tomcat's bin directory, you can create it.</em>
|
||||
</p>
|
||||
<p>
|
||||
Here is an example of the setenv file, showing only the Shindig requirements:
|
||||
<pre>export CLASSPATH=/usr/local/vivo/data/shindig/conf
|
||||
export CATALINA_OPTS='-Dshindig.host=localhost -Dshindig.port=8080'</pre>
|
||||
This assumes that your setenv file was empty before starting this process,
|
||||
and that you used the default location for the Shindig configuration file in Step I.
|
||||
In fact, it's more common for the setenv file to contain other parameters besides
|
||||
those used for Shindig. In that case, it might look more like this:
|
||||
<pre>export CLASSPATH=/usr/local/vivo/data/shindig/conf
|
||||
export CATALINA_OPTS='-Dshindig.host=localhost -Dshindig.port=8080 -Djava.awt.headless=true -Xms1024m -Xmx1024m -XX:MaxPermSize=128m'</pre>
|
||||
</p>
|
||||
|
||||
<h3 id="deploy">IV. Deploy the web application</h3>
|
||||
<p>
|
||||
In the VIVO distribution directory, a file called <em>vitro-core/opensocial/shindigorng.war</em>
|
||||
contains the ORNG-Shindig web application.
|
||||
Copy this file to the <em>webapps</em> directory of your Tomcat server.
|
||||
For example, if your Tomcat server is located at <em>/usr/local/tomcat</em>,
|
||||
then you should copy this file to <em>/usr/local/tomcat/webapps/shindigorng.war</em>
|
||||
</p>
|
||||
|
||||
<h3 id="vivo_settings">V. Configure VIVO</h3>
|
||||
<p>
|
||||
In the VIVO distribution directory, the file called <em>deploy.properties</em>
|
||||
contains configuration options for the VIVO application.
|
||||
You must set some additional parameters so VIVO will be able to communicate with Shindig.
|
||||
</p>
|
||||
<table border='1' bordercolor="#CCCCCC" cellspacing="5">
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>
|
||||
Property Name
|
||||
</th>
|
||||
<th>
|
||||
Example Value
|
||||
</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
The base URL that VIVO will use when contacting the ORNG Shindig application.
|
||||
Usually, this is the same host and port number as VIVO itself,
|
||||
with a context path of <em>shindigorng</em>
|
||||
</td>
|
||||
</tr>
|
||||
<tr class="odd_row">
|
||||
<td>OpenSocial.shindigURL</td>
|
||||
<td>http://localhost:8080/shindigorng</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
The host name and port number of the Token Service that ORNG shindig creates.
|
||||
For now, a value of <em>localhost</em> or <em>127.0.0.1</em> will not work.
|
||||
You must provide the actual host name of your machine, followed by <em>:8777</em>
|
||||
</td>
|
||||
</tr>
|
||||
<tr class="odd_row">
|
||||
<td>OpenSocial.tokenService</td>
|
||||
<td>myhost.mydomain.edu:8777</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3 id="confirm">VI. Does it work?</h3>
|
||||
<p>
|
||||
Start VIVO. Enter a search term in the search box, and view the results. Check the gadgets there.
|
||||
Navigate to a person's profile page. Again, check for the expected gadgets.
|
||||
</p>
|
||||
<p>
|
||||
If the gadgets do not appear as you expect, look for these symptoms,
|
||||
and check for the corresponding possible causes.
|
||||
</p>
|
||||
<table>
|
||||
<tr>
|
||||
<th>Symptoms</th>
|
||||
<th>Possible causes</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<ul>
|
||||
<li>
|
||||
Gadgets do not appear on Individual page or in search results.
|
||||
</li>
|
||||
<li>
|
||||
Tomcat "localhost" log file contains an error message:
|
||||
<pre>Unable to load properties: shindig.orng.properties</pre>
|
||||
</li>
|
||||
</ul>
|
||||
</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>Configuration file is not correctly named.</li>
|
||||
<li>Tomcat's setenv file does not specify the correct CLASSPATH</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr class="odd_row"><td colspan="2"></td></tr>
|
||||
<tr>
|
||||
<td>
|
||||
<ul>
|
||||
<li>
|
||||
Dialog box appears in the browser with the message:
|
||||
"Error 500 reading application data: internalError"
|
||||
</li>
|
||||
<li>
|
||||
Tomcat "catalina" log file contains an error message:
|
||||
<pre>java.sql.SQLException: Access denied for user</pre>
|
||||
</li>
|
||||
</ul>
|
||||
</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>
|
||||
Configuration file contains incorrect value for one or more of these:
|
||||
<ul>
|
||||
<li>orng.dbURL</li>
|
||||
<li>orng.dbUser</li>
|
||||
<li>orng.dbPassword</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr class="odd_row"><td colspan="2"></td></tr>
|
||||
<tr>
|
||||
<td>
|
||||
<ul>
|
||||
<li>
|
||||
Gadgets appear to work as desired.
|
||||
</li>
|
||||
<li>
|
||||
Tomcat "catalina" log file contains an error message:
|
||||
<pre>org.apache.shindig.protocol.ProtocolException: java.net.UnknownHostException:</pre>
|
||||
</li>
|
||||
</ul>
|
||||
</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>
|
||||
<b>What's up?
|
||||
This is a result of not setting key-file, or pointing it to a file that doesn't exist.
|
||||
Is there no better diagnostic?</b>
|
||||
</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr class="odd_row"><td colspan="2"></td></tr>
|
||||
<tr>
|
||||
<td>
|
||||
<ul>
|
||||
<li>
|
||||
Gadgets do not appear on Individual page or in search results
|
||||
</li>
|
||||
<li>
|
||||
vivo.all.log contains an error message:
|
||||
<pre>MySQLSyntaxErrorException: Table 'vivo.shindig_apps' doesn't exist</pre>
|
||||
</li>
|
||||
</ul>
|
||||
</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>
|
||||
MySQL does not contain the shindig tables.
|
||||
<pre>shindig_orng_tables.sql</pre> was not processed.
|
||||
</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr class="odd_row"><td colspan="2"></td></tr>
|
||||
<tr>
|
||||
<td>
|
||||
<ul>
|
||||
<li>
|
||||
Gadgets do not appear on Individual page or in search results
|
||||
</li>
|
||||
<li>
|
||||
vivo.all.log contains an error message:
|
||||
<pre>java.net.ConnectException: Connection refused</pre>
|
||||
</li>
|
||||
</ul>
|
||||
</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>
|
||||
In <em>deploy.properties</em>, <em>OpenSocial.tokenService</em> is not set correctly.
|
||||
</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr class="odd_row"><td colspan="2"></td></tr>
|
||||
</table>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue