+

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

+ +
    +
  1. Create configuration files
    2. +
  2. Create database tables and procedures
    3. +
  3. Modify Tomcat settings
    4. +
  4. Deploy the web application
    +
  5. Configure VIVO
    6. +
  6. Does it work?
    7. +
+ +
+

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.properties
and 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.shindigURLhttp://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.tokenServicemyhost.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. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SymptomsPossible causes
+
    +
  • + Gadgets do not appear on Individual page or in search results. +
    • +
  • + Tomcat "localhost" log file contains an error message: + 
    Unable to load properties: shindig.orng.properties
    +
    • +
+ 		+
    +
  • Configuration file is not correctly named.
    • +
  • Tomcat's setenv file does not specify the correct CLASSPATH
    • +
+
+
    +
  • + Dialog box appears in the browser with the message: + "Error 500 reading application data: internalError" +
    • +
  • + Tomcat "catalina" log file contains an error message: + 
    java.sql.SQLException: Access denied for user
    +
    • +
+ 		+
    +
  • + Configuration file contains incorrect value for one or more of these: +
      +
    • orng.dbURL
      • +
    • orng.dbUser
      • +
    • orng.dbPassword
      • +
    +
    • +
+
+
    +
  • + Gadgets appear to work as desired. +
    • +
  • + Tomcat "catalina" log file contains an error message: + 
    org.apache.shindig.protocol.ProtocolException: java.net.UnknownHostException:
    +
    • +
+ 		+
    +
  • + 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? +
    • +
+
+
    +
  • + Gadgets do not appear on Individual page or in search results +
    • +
  • + vivo.all.log contains an error message: + 
    MySQLSyntaxErrorException: Table 'vivo.shindig_apps' doesn't exist
    +
    • +
+ 		+
    +
  • + MySQL does not contain the shindig tables. + 
    shindig_orng_tables.sql
    was not processed. +
    • +
+
+
    +
  • + Gadgets do not appear on Individual page or in search results +
    • +
  • + vivo.all.log contains an error message: + 
    java.net.ConnectException: Connection refused
    +
    • +
+ 		+
    +
  • + In deploy.properties, OpenSocial.tokenService is not set correctly. +
    • +
+
+