Installing a local BioMOBY Central


You do not need to do this to use BioMOBY, nor to serve your own BioMOBY Services! Only follow these instructions if you wish to run your own local registry...

The following steps are for SuSE Linux Enterprise 9 servers. The principles are the same for other operating systems, but the details might differ slightly. Known essential differences are listed in the Platform Specific notes section. In summary, the steps are:
  1. Configure Apache 2
  2. Configure CVS
  3. Get and install BioMOBY code
  4. Install additional Perl modules using CPAN
  5. MySQL config
  6. Create databases and load data from THE central BioMOBY Central
  7. Setup BioMOBY Central Registry Scripts
  8. Setup your own ontology server
  9. Configure your clients
  10. Test your set up

Now, let's walk through each step in detail.

  • Configuring Apache 2
    • Get root privileges: 
          $> su
    • Check if Apache 2 is enabled: 
          root $> chkconfig apache2
    • Enable Apache 2 if necessary: 
          root $> chkconfig -a apache2
    • Check if Apache 2 is running: 
          root $> rcapache2 status
    • Start Apache 2 if necessary: 
          root $> rcapache2 start
    • Create httpd_biomoby.conf and make sure it will be included by Apache when it reads it's configuration. By default all *.conf files in /etc/apache2/conf/ will be included. Example httpd_biomoby.conf: 
          # 
    # httpd_biomoby.conf example file to be included in Apache 2 config.
    # 

    #
    # BioMOBY script aliases.
    #
    ScriptAlias   /biomoby/central/cgi-bin/   "/path/to/your/biomoby/central/cgi-bin/"
    #
    # Not required for MOBY Central, 
    # but you can uncomment the following line to create a ScriptAlias for your services.
    #
    #ScriptAlias   /biomoby/services/cgi-bin/   "/path/to/your/biomoby/services/cgi-bin/"
    #
    # Not required for MOBY Central, 
    # but you can uncomment the following line to create a ScriptAlias for your clients.
    #
    #ScriptAlias   /biomoby/clients/   "/path/to/your/biomoby/clients/"
 
    #
    # If you use symlinks in the path to your BioMOBY stuff: 
    # make sure Apache is allowed to follow them.
    #
    <Directory /somewhere/in/the/path/to/your/biomoby/stuff/>
        Options FollowSymlinks
    </Directory>

    <LocationMatch /biomoby/>
        # 
        # Security.
        # Specify who is allowed to access your central.
        #
        Order deny,allow
        Allow from all
        #Deny from all
        #Allow from localhost
        #Allow from 10.0.0.1/255.255.255.0
        # 
        # Uncomment the following 2 lines to enforce secure connections over https.
        # To use https you must make sure you also enable SSL support for example 
        # by installing mod_ssl and enabeling it in the main Apache config files.
        #
        #SSLRequireSSL
        #SSLRequire %{SSL_CIPHER_USEKEYSIZE} >= 128
        # 
        # Path to the MySQL config file.
        # This file contains the connection details to fetch data 
        # from the mobycentral databases.
        #
        SetEnv MOBY_CENTRAL_CONFIG "/etc/apache2/conf/mobycentral.config"
        # Full URL to the OntologyServer.cgi script 
        # that is copied to the cgi-bin
        #
        SetEnv MOBY_ONTOLOGY_SERVER "http://your.domain/cgi-bin/OntologyServer.cgi"
        # 
        # Path to additional Perl modules.
        # Tell Apache where to find Perl modules,
        # which are installed outside the default paths.
        #
        SetEnv PERL5LIB "/path/to/custom/perlmodules/:/another/place/for/perlmodules/"
        #
    </LocationMatch>
  • Configuring CVS
    • Install CVS
    • Set CVS_RSH environment variable to make sure CVS uses SSH. 
          for bash,ksh,etc.: $> export CVS_RSH=ssh 
          for csh or tcsh: $> setenv CVS_RSH ssh
  • Get and install BioMOBY code
    • Anonymous CVS checkout of moby-live into ~/moby-live (password is "cvs"): 
          $> cvs -d :pserver:cvs@cvs.open-bio.org:/home/repository/moby login 
          $> cvs -d :pserver:cvs@cvs.open-bio.org:/home/repository/moby checkout moby-live 
          $> cvs update -dP
      (the 'P' flag for the update will clean-up your checkout and get rid of unused directories)
    • Install BioMOBY Perl code
      •     $> cd ~/moby-live/Perl/MOBY-Server/
      To install in default path for Perl modules (root privileges required): 
          $> perl Makefile.PL
      To install in custom path (no root privileges required): 
          $> perl Makefile.PL --PREFIX=/custom/perlmodules/path/ \
          --LIB=/custom/lib/path/ \
          --INSTALLMAN1DIR=/custom/man/path/man1/ \
          --INSTALLMAN3DIR=/custom/man/path/man3/ 
          $> make 
          $> make test
      Root privileges only required in next step if installing in default path: 
          $> make install
      If perl or make are complaining about dependencies you might have to install additional Perl modules first.
    • Copy the main BioMOBY Central CGI script to the path you specified in your httpd_biomoby.conf 
          $> cp ~/moby-live/Perl/MOBY-Server/share/cgi/MOBY-Central.pl /path/to/your/biomoby/central/cgi-bin/
  • Install additional Perl modules using CPAN
    • Installing CPAN will make installing additional Perl modules a whole lot easier.
    • (If you want to install Perl modules in the default path, you will need to become root first.:) 
          $> su
    • Enter CPAN to install missing Perl modules: 
          $> perl -MCPAN -e shell
    • (To install in custom path. No root privileges required): 
          cpan $> o conf makepl_arg "LIB=/custom/lib/path/ \
               PREFIX=/custom/perlmodules/path/ \
               INSTALLMAN1DIR=/custom/man/path/man1/ \
               INSTALLMAN3DIR=/custom/man/path/man3/"
    • Run tests for the module you want to install: 
          cpan $> test Some::Perl::Module
    • If the tests were Ok: 
          cpan $> install Some::Perl::Module
    • When you are done: 
          cpan $> exit
  • MySQL config
    • Get root privileges: 
          $> su
    • Check if MySQL is enabled: 
          root $> chkconfig mysql
    • Enable MySQL if necessary: 
          root $> chkconfig -a mysql
    • Check if MySQL is running: 
          root $> rcmysql status
    • Start MySQL if necessary: 
          root $> rcmysql start
    • If this is the first time mysql is started you will receive a warning not to forget to create a root password for mysql. Do so if you haven't done so already.
    • Create a mobycentral.config file and make the following entries (note that a template mobycentral.config file exists in the moby-live/Database folder of your CVS checkout):
          [mobycentral]
    username = mysql_username
    password = mysql_password
    url = localhost
    port = 3306
    dbname = mobycentral
    lsid_authority = biomoby.org
    lsid_namespace = serviceinstance
    resourceURL = http://your.host.name/authority/RESOURCES/MOBY-S/ServiceInstances
    allResources = http://your.host.name/authority/RESOURCES/MOBY-S/FULL
    rdf_generator = http://mobycentral.icapture.ubc.ca/authority/RDFGenerator
 
    [mobyobject]
    username = mysql_username
    password = mysql_password
    url = localhost
    port = 3306
    dbname = mobyobject
    lsid_authority = biomoby.org
    lsid_namespace = objectclass
    resourceURL = http://your.host.name/authority/RESOURCES/MOBY-S/Objects

    [mobynamespace]
    username = mysql_username
    password = mysql_password
    url = localhost
    port = 3306
    dbname = mobynamespace
    lsid_authority = biomoby.org
    lsid_namespace = namespacetype
    resourceURL = http://your.host.name/authority/RESOURCES/MOBY-S/Namespaces
 
    [mobyservice]
    username = mysql_username
    password = mysql_password
    url = localhost
    port = 3306
    dbname = mobyservice
    lsid_authority = biomoby.org
    lsid_namespace = servicetype
    resourceURL = http://your.host.name/authority/RESOURCES/MOBY-S/Services
 
    [mobyrelationship]
    username = mysql_username
    password = mysql_password
    url = localhost
    port = 3306
    dbname = mobyrelationship
    lsid_authority = biomoby.org
    lsid_namespace = relationshiptype
    • Copy your mobycentral.config file to the path you specified in your httpd_biomoby.conf
    • restart Apache as root: 
          root $> rcapache2 restart
  • Create databases and load data from THE central BioMOBY Central
    • If you have come this far and the stuff above was configured correctly, you can use the 
          ~/moby-live/Perl/MOBY-Server/share/scripts/CloneCentralDatabases.pl
      script. This will create the databases, set privileges, fetch all data from THE central BioMOBY Central and load it into your local central.
    • If you prefer to configure your BioMOBY Central databases manually, proceed with the next steps.
      • If you are going to bootstrap the databases with only the most primitive information, then simply run the 
            ~/moby-live/Database/reset
        script and it will create all databases for you. (Note: some UNIX systems have a "reset" command, which resets the terminal, rather than your database. So be sure to specify the full path for this command.) You can then go on to the section on privileges.
      • Start mysql as root: 
            $> mysql -u root -p
      • Create databases:
        • mobycentral
        • mobyobject
        • mobynamespace
        • mobyservice
        • mobyrelationship
            mysql $> CREATE DATABASE moby_database;
      • Create a user and grant privileges for the BioMOBY Central databases. (User must have write access to all). The username and password you choose must be in sync with the data you have in your mobycentral.config file for Apache. 
            mysql $> USE moby_database;
    mysql $> GRANT ALL PRIVILEGES ON moby_database TO \
                    mysql_username@localhost identified by "mysql_password";
      • Exit mysql: 
            mysql $> exit;
      • For each database you need to load a mysql DUMP. Either a bootstrap dump (basic required info only) from the ~/moby-live/Database folder of the CVS, or a dump from the public MOBY Central registry. You can get a full dump from THE central MOBY Central using the 
            ~/moby-live/Perl/scripts/GetDump.pl
        script, by calling the Perl method $Central->DUMP on MOBY::Client:Central,
        or by calling the procedure "DUMP" on the public MOBY Central's SOAP interface. 
            $> mysql -u mysql_username -p moby_database< /path/to/sqldump/databasename.mysql
    • Append data for your local BioMOBY services by registering namespaces, objects and services.
    • In case you mess up your central during debugging you can simply nuke your databases and start with a fresh BioMOBY Central clone using the 
          ~/moby-live/Perl/MOBY-Server/share/scripts/CloneCentralDatabases.pl
      script.
  • Setup BioMOBY Central Registry Scripts
    • If you want to retrieve info from your local central in RDF format, you will need to install some scripts. Info in RDF format is required to use your local BioMOBY Central for example with the workflow enactor Taverna. Taverna uses your BioMOBY Central endpoint to request the URLs for the RDF files, which are dynamically generated by the scripts. Hence, using your local central with Taverna is a two step process that requires both a working BioMOBY Central CGI script at your BioMOBY Central endpoint and several scripts to generate RDF files.
    • For instructions on setting up the scripts, click here!
    • If you want to use Taverna with your local BioMOBY Central you will need Taverna 1.3 or better.
  • Setup your own ontology server
    • Copy the 
          ~/moby-live/Perl/scripts/OntologyServer.cgi
      CGI script into your webserver cgi-bin folder.
  • Configure your clients (if you wish)
    • The Perl MOBY::Client::Central module checks environment variables to determine its default MOBY Registry server. If you want the registry that you just created to be the server that you connect to by default then set up the following environment variables.
      For bash, ksh, etc. in your ~/.bashrc or ~/.kshrc or etc.: 
      export MOBY_SERVER=http://your.host.name/biomoby/central/cgi-bin/MOBY-Central.pl
export MOBY_URI=http://your.host.namet/MOBY/Central
export MOBY_ONTOLOGYSERVER=http://your.host.name/biomoby/central/cgi-bin/OntologyServer.cgi
      For csh or tcsh in your ~/.cshrc or ~/.tcshrc: 
      setenv MOBY_SERVER http://your.host.name/biomoby/central/cgi-bin/MOBY-Central.pl
setenv MOBY_URI http://your.host.name/MOBY/Central
setenv MOBY_ONTOLOGYSERVER=http://your.host.name/biomoby/central/cgi-bin/OntologyServer.cgi

Done!

To test your BioMOBY Central:

  • Ensure that the following environment variables are set: 
        MOBY_CENTRAL_CONFIG - the path to your mobycentral.config file created above
        MOBY_ONTOLOGYSERVER - the url to your OntologyServer.cgi file created above
        MOBY_SERVER - the endpoint of your local registry (see above, Configure your clients)
        MOBY_URI - the namespace of your local registry (see above, Configure your clients)
  • Rerun make test in ~moby-live/Perl/MOBY-Server/ (see Get and install BioMOBY code above): 
        $~/moby-live/Perl/MOBY-Server/> make test
    With the environment variables pointing to your local Central it will run a series of tests against your local registry. The tests 'clean up' after themselves, leaving your registry in the same state that it was in when you started the test suite. If there is a failure in the tests, you will need to track down the source of the failure and then re-run the test script to ensure that your registry is cleaned up.
    NOTE: these tests don't test whether the servlets in Tomcat are working.

If you have any comments to improve this documentation or questions on how to setup you local BioMOBY Central, please send an e-mail to the developers mailing list

  • Platform Specific notes
    • All:
      • If you are pretty sure that you have configured everything correctly and things are still failing, you might want to check whether the (configuration) files have to correct encoding and line endings for your platform.
      • Starting and stopping services like Apache, MySQL and Tomcat:
        On some Linux distro's you can do this with rc[name_of_the_service] [option]. The rc (= resource control) commands are usually links to scripts in the /etc/inint.d/ directory. So if the rc commands are missing have a look in /etc/init.d/ for scripts that are named after a service and try those.
    • SuSE Linux:
      • Use SuSE Linux Professional 9.2 or higher or SuSE Linux Enterprise Server 9. Older versions have to old versions of essential XML parsing libraries. If you try to upgrade them, you will run in dependency on dependency making you upgrade half your system.