BioHPC Cloud:
: User Guide

JBrowse is a complicated genome browser that can be used to visualize genomes and their features. It requires a web server running, therefore we use Docker to run it in a container. The following instructions show how to start a JBrowse instance, add your data to it and access the resulting website. Before running JBrowse you should understand Docker @ BioHPC Lab - see our instructions here.

In the text below labid should be replaced with your Lab ID.

Preposition your data

• Copy your genome fasta file and any other files (gff, bed, bam) to /workdir/labid on the machine you reserved. Example below uses  Volvox genome.
  $ cp /home/labid/volvox/volvox.fa /workdir/labid
  $ cp /home/labid/volvox/volvox.gff3 /workdir/labid
  $ cp /home/labid/volvox/volvox.bam* /workdir/labid
• If you have JBrowse fromatted data from previous JBrowse runs you can copy it to /workdir/labid, the best way is to unarchive from a tar archive made after successfull JBrowse run
  $ cd /workdir/labid
  $ tar -xvf /home/labid/myJBrowsedata.tar

Start JBrowse instance

• First, load docker image from the file
  $ docker1 import /programs/docker/images/jbrowse.tar
• Verify the name of the imported image - should be "biohpc_labid/jbrowse", where labid is your Lab id.
  $ docker1 images
  REPOSITORY                 TAG          IMAGE ID            CREATED             SIZE
  biohpc_labid/jbrowse      latest       30023f4e0c2c        28 seconds ago      1.183 GB
• Now start JBrowse container using image name from last step. (replace labid with your Lab id)
  $ docker1 run -d -t  -p 127.0.0.1:8080:80 biohpc_labid/jbrowse /docker-entrypoint.sh
• Make sure it runs and find the container ID
  $ docker1 ps -a
  CONTAINER ID        IMAGE                 COMMAND                  CREATED             STATUS              PORTS                    NAMES
  d3d74e7869a6        biohpc_labid/jbrowse  "/docker-entrypoint.s"   6 seconds ago       Up 2 seconds        127.0.0.1:8080->80/tcp   labid__biohpc_1

Add your data

• If you have JBrowse formatted data from a previous run and it has been copied to /workdir/labid you are all done here. Go to the next section.
• Start interactive shell inside JBrowse container
  $ docker1 exec -it d3d74e7869a6 /bin/bash
  root@d3d74e7869a6:/workdir#
• Format data
  # cd /jbrowse
  # bin/prepare-refseqs.pl --fasta /workdir/volvox.fa -out data
  # bin/flatfile-to-json.pl --gff /workdir/volvox.gff3 --trackType CanvasFeatures --trackLabel gene --out data
  adding bam files requires two steps - copy to data and then format
  # cp /workdir/volvox.bam* data
  # bin/add-bam-track.pl --label mybam --bam_url /data/volvox.bam --in data/trackList.json
• For more formatting options go to JBrowse documentation.
• Exit the container shell
  # exit

Access JBrowse

• There are two options here:

1. Run Firefox on the machine you reserved and display the graphics on your client machine, in this case you need to start X-Windows client (like MobaXTerm on Windows) - check our online documentation on how to use GUI programs 
   $ firefox http://localhost:8080/
   Firefox window will open and you can explore your genome.
    
2. Tunnel website access via your ssh client and use web browser on your client machine.
   You need to map port 8080 on your reserved machine to port 8080 on your client machine using ssh.
   Windows.
   Open PuTTY and go to Connection->SSH->Tunnels in the left panel. Type 8080 in the Source port box and localhost:8080 in the Destination box, click Add. Now click on Session and proceed with normal session, i.e. connect to the rented machine. Once connected, start a Web browser on your client machine and type the following URL http://localhost:8080/
   Mac.
   Connect to the rented machine with ssh using "-D 8080:localhost:8080", e.g.
   ssh -D 8080:localhost:8080 labid@cbsuXXX.tc.cornell.edu
   then start a Web browser on your local client machine and type the following URL http://localhost:8080/

Stop JBrowse and (optionally) save formatted genome files for future use

Once you are finished please stop the container.
$ docker1 stop d3d74e7869a6

You can now save the formatted files for future use.
$ cd /workdir/labid
$ tar -cf /home/labid/myjbrowsedata.tar data

Remove the container
$ docker1 rm d3d74e7869a6