Skip to content

Download and Installation

Jump to bottom
Pedro Furió edited this page Sep 8, 2016 · 5 revisions

Currently, in order to use OpenCGA, you have to download the code and build it. This build process is handled with maven. If you want to compile it you will need Java JDK 1.8, in particular JDK 1.8.0_60+, Apache Maven 3, MongoDB 2 as default storage engine, and Apache Tomcat 8 if you want the web services running.

Please note that Java 1.7 is outdated, and it is mandatory to use java 8 for OpenCGA 0.6+.

Stable releases are merged and tagged at master branch, you are encouraged to use latest stable release for production. Current active development is carried out at develop branch and need Java 8, only compilation is guaranteed and bugs are expected, use this branch for development or for testing new functionalities. Only dependencies of master branch are ensured to be deployed at Maven Central Repository, develop branch may require users to download and install other active OpenCB repositories:

Cloning

OpenCGA is an open-source and free project, you can download default develop branch by executing:

$ git clone https://github.com/opencb/opencga.git
Cloning into 'opencga'...
remote: Counting objects: 20267, done.
remote: Compressing objects: 100% (219/219), done.
remote: Total 20267 (delta 105), reused 229 (delta 35)
Receiving objects: 100% (20267/20267), 7.23 MiB | 944.00 KiB/s, done.
Resolving deltas: 100% (6363/6363), done.

Latest stable release at master branch can be downloaded executing:

$ git clone -b master https://github.com/opencb/opencga.git
Cloning into 'opencga'...
remote: Counting objects: 20267, done.
remote: Compressing objects: 100% (219/219), done.
remote: Total 20267 (delta 105), reused 229 (delta 35)
Receiving objects: 100% (20267/20267), 7.23 MiB | 812.00 KiB/s, done.
Resolving deltas: 100% (6363/6363), done.

Build

OpenCGA can be compiled directly, just by executing mvn install -DskipTests, but some configuration files can be customized with the content of the file ~/.m2/settings.xml.

This file is not needed for the installation, but makes easier to compile, install and configure at the same time the program, by filtering the resources files. Also, this information is used to run the tests. In that case, this file is required.

An example of that file can be found in the README. The description of each property can be found below:

  • OPENCGA.CATALOG.DB.HOSTS: This property should be configured with the host and port of the MongoDB installation. By default, for development purposes, we have it set with "localhost:27017".

  • OPENCGA.CATALOG.DB.DATABASE: This property indicates the database name that will be created to store the catalog information. Default: opencga_catalog.

  • OPENCGA.CATALOG.DB.USER: This property should only be set if the MongoDB needs authentication. In this case, this property will contain the user name with permissions for the database. *This can be left empty in any case. The admin will be able to set this credentials using the command line.

  • OPENCGA.CATALOG.DB.PASSWORD: This property should only be set if the MongoDB needs authentication. In this case, this property will contain the password of the user with permissions for the database. *Like in the user property, this can be left empty. The admin will be able to set this credentials using the command line.

  • OPENCGA.INSTALLATION.DIR: This property is extremely important when using Tomcat to deploy the webservices. This property will have to point to the final OpenCGA installation directory after everything has been built. This property will be used by Tomcat to locate the configuration files. If this is not properly set, none of the webservices will work. Default: /opt/opencga.

  • OPENCGA.CATALOG.ROOTDIR: In Catalog, users are allowed to build their own directory structure, upload their own files, run analysis, etc. This path should be pointing to a physical location where Catalog will be storing those files and directory structure. By default, we normally put it in a folder called "sessions" within the installation directory (file:///opt/opencga/sessions/). Be aware of the "file://" annotation. In version 0.8 this is still necessary but will not be needed for future releases (see issue).

  • OPENCGA.STORAGE.VARIANT.DB.HOSTS:

  • OPENCGA.STORAGE.VARIANT.DB.USER:

  • OPENCGA.STORAGE.VARIANT.DB.PASSWORD:

  • OPENCGA.STORAGE.ALIGNMENT.DB.HOSTS:

  • OPENCGA.STORAGE.ALIGNMENT.DB.USER:

  • OPENCGA.STORAGE.ALIGNMENT.DB.PASSWORD:

  • OPENCGA.ANALYSIS.EXECUTION.MANAGER: OpenCGA Catalog allows users to run jobs. This property indicates how the jobs will be launched. At the moment we only support two types: LOCAL to run the jobs locally in a thread or SGE to run the jobs using Sun Grid Engine. More queuing systems will be supported soon.

  • OPENCGA.CLIENT.HOST: This property should be pointing to the URL where the webservices will be available. For development purposes, the default is http://localhost:8080/opencga/. This property is read by the command line opencga.sh in order to communicate with the webservices.

  • OPENCGA.CELLBASE.HOST:

  • OPENCGA.CELLBASE.VERSION:

After creating and configuring the default profile, you can build OpenCGA by executing the following command from the root of the cloned repository:

$ mvn clean install -DskipTests

Remember that develop branch dependencies are not ensured to be deployed at Maven Central, you may need to clone and install develop branches from OpenCB biodata, datastore and cellbase repositories. After this you should have this file structure in your OPENCGA.INSTALLATION.DIR:

opencga/
├── tools/
├── bin/
├── conf/
└── libs/

You can copy the content of the build folder into the installation directory such as /opt/opencga.

mkdir /opt/opencga
cp build/* /opt/opencga

The updated list of configurable properties and their default values can be found in the main pom.xml.

Testing

You can run the unit tests using Maven or your favorite IDE. Just notice that some tests may require of certain database back-ends such as MongoDB or Apache HBase and may fail if they are not available.

Command Line Interface (CLI)

If the build process has gone well you should get an integrated help by executing:

./bin/opencga.sh --help

Head over Command Line for a further description of the CLI, or Indexing Variant Data for a quick CLI-based tutorial.

Web Services

This is main interface to do anything on OpenCGA. If you want to use it, you will have two different options:

  1. Install Apache Tomcat and deploy our opencga.war. To do this, just copy it from the compilation directory (where you downloaded the OpenCGA repository) into the Tomcat webapps directory:

    cp opencga-server/target/opencga.war $(path_to_tomcat)/webapps

path_to_tomcat is where you downloaded it, or probably /var/lib/tomcat8 if you installed via apt-get. Then, you should be able to see the swagger page at http://localhost:8080/opencga/. See Using RESTful web services for a tutorial.

Tomcat server will look for the configuration files in the installation directory, that can be changed in compilation time changing the property OPENCGA.INSTALLATION.DIR.

If the installation directory is empty at compilation time, the web services will search for the environment variable OPENCGA_HOME. If none of this are properly set, the webservices will not work.

  1. Serving the webservices using the admin command line. These webservices will be served with Jetty as follows:

/opencga-admin.sh server rest --start -p

Warning: This method is still under development.

OpenCGA is an open source project and it is freely available.

General

OpenCGA Catalog

OpenCGA Storage

About

Clone this wiki locally