Setting up VIVO to use OpenSocial Gadgets
+ + Instructions for connecting VIVO and Open Research Networking Gadgets + ++ This 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_file+ So, 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.sql+ MySQL 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.sql+ As 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 | +
|---|---|
+
|
+
+
|
+
+
|
+
+
|
+
+
|
+
+
|
+
+
|
+
+
|
+
+
|
+
+
|
+