410 lines
No EOL
17 KiB
HTML
410 lines
No EOL
17 KiB
HTML
<!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>
|
|
|