Hosting Your Own IGV-Web

The instructions in this section are for developers or others wishing to install and customize a copy of the IGV-Web app. The IGV team also hosts the app at https://igv.org/app.

Installation#

IGV-Web is a pure client web application consisting entirely of static files and can be served from virtually any web server, e.g. Apache, Flask, Tomcat, nginx, or Amazon S3. You can install it from the pre-built IGV-Web distribution package or by building it from source code. To run the app, refer to your web server documentation for information on serving web content. Some examples are provided in the section on Running the app below.

Option 1: Use a pre-built package#

Zip files of the current and previous versions of the IGV-Web app are available for download here.

Option 2: Build from source code#

Get the IGV-Web source code from our GitHub repository at https://github.com/igvteam/igv-webapp.

Note that the master branch in the GitHub repository contains the current development snapshot, which may not be fully tested yet and may not correspond to the current documentation. For most users we recommend downloading the latest pre-built package in Option 1, which will correspond to the latest released version of the app.

Pre-requisites

To build the app:

  1. Change directories to project
    cd ./igv-webapp
  1. Install
    npm install
  1. Build. This step creates a dist directory with the same contents as the pre-built package.
    npm run build

Serving and running the app#

As noted above, refer to your web server documentation for instructions on serving the installed IGV-Web app. As examples, instructions for use with the NPM package http-server and Amazon S3 follow.

Example 1: http-server#

For more information about http-server, including installing it locally, see the http-server documentation.

  1. Start http-server and pass it the path to the built IGV-Web folder as a parameter. The folder is either the folder created when you downloaded the pre-packaged distribution described above, or it is the dist folder you built from the source code.
    npx http-server -a localhost <IGV-Web folder>
  1. Open a browser and enter localhost:8080 or localhost:8080/index.html

Example 2: Amazon S3#

To serve the app from Amazon S3, simply upload the contents from the IGV-Web content folder (i.e., the pre-packaged distribution described above, or the dist folder if building from source) to an Amazon S3 bucket. Keep the directory structure intact, and make all files public. An example of an S3 hosted app can be found at https://s3.amazonaws.com/igv.org.app/app/index.html.

Note this is an example only; it is an older version of the app that is that is not kept up to date.

Configuration#

A number of IGV-Web app properties are customizable and are configured through the global igvwebConfig, which is defined in the file igvwebConfig.js.

Configurable properties#

Where to find the configuration files#

NOTE: if you change the configuration files, you may need to clear the browser cache before seeing the effect.

Example configuration#

var igvwebConfig = {

    genomes: "resources/genomes.json",
    trackRegistryFile: "resources/tracks/trackRegistry.json",

    // Supply a drobpox api key to enable the Dropbox file picker in the load menus.  This is optional
    //dropboxAPIKey: "...",

    // Supply a Google client id to enable Google file access.  This is optional
    // clientId: "...",

    googleDriveEnabled: false,

    // Provide a URL shorterner function or object.   This is optional.  
    // If not supplied sharable URLs will not be shortened.  
    // If using tinyURL supply an api token.
    // urlShortener: {
    //     provider: "tinyURL",
    //     api_token: "<your tinyurl token>"
    // },
    // urlShortener: function(longURL) {...   return shortendURL}

    igvConfig:
        {
            genome: "hg19",
            locus: "all",
            genomeList: "resources/genomes.json",
            queryParametersSupported: true,
            showChromosomeWidget: true,
            showSVGButton: false,
            tracks: [
        // TODO -- add default tracks here.  
            // For example:
                // {
                //     name: "CTCF - string url",
                //     type: "wig",
                //     format: "bigwig",
                //     url: "https://www.encodeproject.org/files/ENCFF563PAW/@@download/ENCFF563PAW.bigWig"
                // }
        ]
        }

}

Track registry#

The set of pre-defined tracks presented in the Tracks menu is different depending on the currently selected reference genome. The items presented in the menu are defined in the file specified by the trackRegistryFile property in igvwebConfig.js by associating lists of track configuration files with genome IDs.

The example track registry file below will result in two items for the Tracks menu when the hg19 genome is selected, and a single menu item for hg38.

Note: make sure to include the comma after every item in the list, except the last one.

{
  "hg19" : [
    "resources/tracks/hg19_annotations.json", 
    "resources/tracks/hg19_my_platinum_genomes.json"
  ],

  "hg38" : [
    "resources/tracks/hg38_annotations.json"
  ]
}

Each .json track configuration file associated with a genome ID corresponds to one menu item presented in the Tracks pulldown menu. The configuration file defines:

1. Simple list of track names. The example below defines a menu item labeled "Annotations" that presents a list of just one track, a BED file of Gencode gene annotations. The details of the track are defined by a track configuration object as described in the igv.js documentation.

{
  "label": "Annotations",
  "description": "Annotations - source <a href=http://hgdownload.soe.ucsc.edu/downloads.html target=_blank>UCSC Genome Browser</a>",
  "tracks": [
    {
      "type": "bed",
      "url": "https://s3.amazonaws.com/igv.org.test/data/gencode.v18.collapsed.bed",
      "indexURL": "https://s3.amazonaws.com/igv.org.test/data/gencode.v18.collapsed.bed.idx",
      "name": "Gencode V18"
    }
  ]
}

2. Annotated table of tracks. Setting a type property in the track configuration file to "custom-data-modal" specifies that a custom annotated table of tracks will be used. Each row in the table corresponds to a track, and columns represent attributes of the track. The resulting table can be sorted and filtered interactively by the user based on column values. Selecting a row in the table will load the corresponding track.

The data property in the configuration file defines the attribute values for each row, and also the details of the track to be loaded when the row is selected. The track details are used to create a track configuration object as described in the igv.js documentation. The data property can either point to an external tab- or comma-delimited file, or contain the data inline as JSON, as shown in the two examples below. The columns property in the configuration file defines which track attributes are displayed in the table. An optional columnDefs property can be used to rename the column headers displayed in the table.

The following example defines a menu item labeled "My Favorite Platinum Genomes Trio", sets the type property to "custom-data-modal", and defines the data for the table inline as JSON. The resulting table has 3 tracks and displays 3 attributes for each. The property columnDefs is used to set the displayed column heading for the track attribute "name" to "Sample". 

{  
  "label": "My Favorite Platinum Genomes Trio",
  "type": "custom-data-modal",
  "description": "Example custom data modal: Data from <a href=https://cloud.google.com/genomics/docs/public-datasets/illumina-platinum-genomes target=_blank>Illumina Platinum Genomes hosted at Google</a>",

  "columns":
  [
    "name",
    "Relation",
    "Population"
  ],
  "columnDefs":
  {
    "name":
    {
      "title": "Sample"
    }
  },

  "data":
  [
    {
      "Relation": "Daughter",
      "Population": "CEPH",
      "sourceType": "gcs",
      "type": "alignment",
      "url": "gs://genomics-public-data/platinum-genomes/bam/NA12878_S1.bam",
      "indexURL": "gs://genomics-public-data/platinum-genomes/bam/NA12878_S1.bam.bai",
      "name": "NA12878"
    },
    {
      "Relation": "Father",
      "Population": "CEPH",
      "sourceType": "gcs",
      "type": "alignment",
      "url": "gs://genomics-public-data/platinum-genomes/bam/NA12891_S1.bam",
      "indexURL": "gs://genomics-public-data/platinum-genomes/bam/NA12891_S1.bam.bai",
      "name": "NA12891"
    },
    {
      "Relation": "Mother",
      "Population": "CEPH",
      "sourceType": "gcs",
      "type": "alignment",
      "url": "gs://genomics-public-data/platinum-genomes/bam/NA12892_S1.bam",
      "indexURL": "gs://genomics-public-data/platinum-genomes/bam/NA12892_S1.bam.bai",
      "name": "NA12892"
    }
  ]
}

The following example shows the track configuration file for the same menu item and table as the example above, but in this case the track details are in a tab or comma delimited file describing a table with column headers. Each column header is mapped to a track configuration JSON property. A url column is required to load the track. The table file is specified with the "data" property and can be either a relative local path or URL. 

{  
  "label": "My Favorite Platinum Genomes Trio",
  "type": "custom-data-modal",
  "description": "Example custom data modal: Data from <a href=https://cloud.google.com/genomics/docs/public-datasets/illumina-platinum-genomes target=_blank>Illumina Platinum Genomes hosted at Google</a>",

  "columns":
  [
    "name",
    "Relation",
    "Population"
  ],
  "columnDefs":
  {
    "name":
    {
      "title": "Sample"
    }
  },
  "delimiter": ",",
  "data": "resources/tracks/my_custom_track_table.csv"
}

The data file can be tab- or comma-separated, specified by setting a delimiter property to "," or "\t". If the property is not set, the .csv or .tab filename extensions specify the file type. The file in this example is a .csv file. It has the same information as the JSON example above, but formatted as follows:

Relation,Population,sourceType,type,url,indexURL,name
Daughter,CEPH,gcs,alignment,gs://genomics-public-data/platinum-genomes/bam/NA12878_S1.bam,gs://genomics-public-data/platinum-genomes/bam/NA12878_S1.bam.bai,NA12878
Father,CEPH,gcs,alignment,gs://genomics-public-data/platinum-genomes/bam/NA12891_S1.bam,gs://genomics-public-data/platinum-genomes/bam/NA12891_S1.bam.bai,NA12891
Mother,CEPH,gcs,alignment,gs://genomics-public-data/platinum-genomes/bam/NA12892_S1.bam,gs://genomics-public-data/platinum-genomes/bam/NA12892_S1.bam.bai,NA12892

Session registry#

Predefined sessions presented in the Session menu are defined in the file specified by the sessionRegistryFile property in igvwebConfig.js.

The example session registry file below will add two pre-defined sessions to the Session menu. The two session files gbm-copynumber.json and 1kg-variants-session.json are regular IGV-Web session files; they can be created by clicking on Save in the Session menu.

Note: make sure to include the comma after every item in the lists, except the last one.

{
"sessions": [
  {
    "name": "Segmented Copy Number",
    "description": "Segmented copy number for TCGA GBM data",
    "url": "resources/sessions/gbm-copynumber.json"
  },
  {
    "name": "1KG Variants",
    "description": "1000 genomes variants",
    "url": "resources/sessions/1kg-variants-session.json"
  }
]
}

Data servers#

IGV-Web uses igv.js, a JavaScript client. To host your own track data, note that the hosting server must support CORS access and Range requests. See the igv.js documentation for more details.