Setting up VIVO to use OpenSocial Gadgets
Instructions for connecting VIVO and Open Research Networking GadgetsThis document contains instructions on how to configure your VIVO installation to use OpenSocial gadgets.
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, http://www.opengadgets.org/index.html
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.
Table of Contents
I. Create configuration files
In your VIVO home directory, create a directory called shindig. Under that, create directories called conf and openssl. Your VIVO home directory will look something like this:
[VIVO home directory]
|
|--shindig
| |
| |--conf
| |
| |--openssl
|
|--solr
|
|--uploads
A. Create a secure key file
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 shindig/openssl directory that you created.
On Unix-based systems (like Linux or Mac OS X), this command will create an encryption key from a random seed:
dd if=/dev/random bs=32 count=1 | openssl base64 > [key-file]For example, if your VIVO home directory is /usr/local/vivo/data, you might use the command this way:
dd if=/dev/random bs=32 count=1 | openssl base64 > /usr/local/vivo/data/shindig/openssl/securitytokenkey.txt
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.
B. Create the Create configuration files
In your VIVO distribution directory, find the file called
vitro-core/opensocial/shindig.orng.propertiesand copy it to the shindig/conf directory that you created.
Set these values in the shindig.orng.properties file
| Property Name | Example Value |
|---|---|
| Specify the location of the encryption key file. | |
| shindig.signing.key-file | /usr/local/vivo/data/shindig/openssl/securitytokenkey.txt |
| Specify the JDBC URL of your database. Change the end of the URL to reflect your database name (if it is not "vivo"). | |
| orng.dbURL | jdbc:mysql://localhost/vivo |
| Change the username to match the authorized user you created in MySQL when installing VIVO. | |
| orng.dbUser | username |
| Change the password to match the password you created in MySQL when installing VIVO. | |
| orng.dbPassword | password |
II. Create database tables and procedures
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.
In the VIVO distribution directory, a file called vitro-core/opensocial/shindig_orng_tables.sql contains SQL commands that create the tables and stored procedures for Shindig to use.
Tell MySQL to process this file with a command like this:
mysql -u username -p database < sql_fileSo, if your current directory is the VIVO distibution directory, and your VIVO database is vivoDb and your MySQL user account is vivoUser, then you might use the command this way:
mysql -u vivoUser -p vivoDb < vitro-core/opensocial/shindig_orng_tables.sqlMySQL will prompt you for the password for your MySQL user account, and then process the file.
You may want to start your gadget collection with some example gadgets that have been developed by the ORNG group. The file called vitro-core/opensocial/shindig_example_gadgets.sql contains SQL commands that will add these gadgets to your system's configuration.
If you want to load these example gadgets, you can use a command similar to the previous one:
mysql -u vivoUser -p vivoDb < vitro-core/opensocial/shindig_example_gadgets.sqlAs before, MySQL will prompt you for the password for your MySQL user account, and then process the file.
III. Modify Tomcat settings
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.
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. If this file does not exist in Tomcat's bin directory, you can create it.
Here is an example of the setenv file, showing only the Shindig requirements:
export CLASSPATH=/usr/local/vivo/data/shindig/conf export CATALINA_OPTS='-Dshindig.host=localhost -Dshindig.port=8080'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:
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'
IV. Deploy the web application
In the VIVO distribution directory, a file called vitro-core/opensocial/shindigorng.war contains the ORNG-Shindig web application. Copy this file to the webapps directory of your Tomcat server. For example, if your Tomcat server is located at /usr/local/tomcat, then you should copy this file to /usr/local/tomcat/webapps/shindigorng.war
V. Configure VIVO
In the VIVO distribution directory, the file called deploy.properties contains configuration options for the VIVO application. You must set some additional parameters so VIVO will be able to communicate with Shindig.
| Property Name | Example Value |
|---|---|
| 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 shindigorng | |
| OpenSocial.shindigURL | http://localhost:8080/shindigorng |
| The host name and port number of the Token Service that ORNG shindig creates. For now, a value of localhost or 127.0.0.1 will not work. You must provide the actual host name of your machine, followed by :8777 | |
| OpenSocial.tokenService | myhost.mydomain.edu:8777 |
VI. Does it work?
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.
If the gadgets do not appear as you expect, look for these symptoms, and check for the corresponding possible causes.
| Symptoms | Possible causes |
|---|---|
|
|
|
|
|
|
|
|
|
|