beacon2ri/refgendetector repository overview

⁠(How to) Run refgendetector in a Docker container

This document explains how to install and use Docker to run refgendetector on a local machine.

⁠Contents

1. Install Docker
2. Test that it works
3. Get the refgendetector container image
4. Start up the refgendetector container
5. Connect to the container
6. Run a refgendetector command in the container
7. Use a mounted volume to access data that lives outside the container

⁠1. Install Docker

Follow the relevant link below depending on your computer system; on Mac and Windows, select the "Stable channel" download. Run through the installation instructions and initial setup page; they are very straightforward and should only take you a few minutes (not counting download time). We have included instructions below for all steps after that first page, so you shouldn't need to go to any other pages in the Docker documentation. Frankly their docs are targeted at people who want to do things like run web applications on the cloud and can be quite frustrating to deal with.

MacOS systems Click here for the MacOS install instructions⁠.

On Mac, the installation adds a menu bar item that looks like a whale/container-ship, which conveniently shows you the status of the Docker "daemon" (= program that runs in the background) and gives you GUI access to various Docker-related functionalities. But you can also just use it from the command-line, which is what we'll do in the rest of this tutorial.

Windows systems Click here for the Windows install instructions⁠.

Note that on some Windows systems (including non-Pro versions like Windows Home, and older versions) the "normal" Docker app doesn't work, and you have to use an older app called Docker Toolbox, which you can find here.

Linux systems Click here for the linux install instructions⁠.

⁠2. Test that it works

Now, open a terminal window and invoke the docker program directly. Checking the version is always a good way to test that a program will run without investing too much effort into finding a command that will work, so let's do:

docker --version

This should return something like "Docker version 20.10.14, build a224086".

If you run into trouble at this step, you may need to run one or more of the following commands:

docker-machine restart default

docker-machine regenerate-certs

docker-machine env

Let's just assume your Docker install worked fine. (If not, let us know and we'll try to help you)

⁠3. Get the refgendetector container image

Still in your terminal (it doesn't matter where your working directory is), run the following command to retrieve the refgendetector image from Docker Hub:

docker pull beacon2ri/refgendetector:v1.0.0

Note that the last bit after refgendetector: is the version tag, which you can change to get a different version than what we've specified here. At the time of writing, we're using the latest released version.

The refgendetector container image is quite small. The good news is that next time you need to pull a refgendetector image (e.g. to get another release), Docker will only pull the components that have been updated, so it will go faster.

⁠4. Start up the refgendetector container

There are several different ways to do this in Docker. Here we're going to use the simplest invocation that gets us the functionality we need, i.e. the ability to log into the container once it's running and execute commands from inside it.

docker run -tid --name refgendetector beacon2ri/refgendetector:v1.0.0

If all goes well, this will start up the container in detached mode and should be present in the container list. To view the containers run :

docker ps

⁠5. Connect to the container

The refgendetector container is running in detached mode or in the background. To connect, you should invoke from your terminal :

docker exec -ti refgendetector bash

And you will automatically get logged into it. Your terminal prompt will change to something like this:

root@a5b3750629a8:/usr/share/refgenDetector#

At this point, you can use classic shell commands to explore the container and see what's in there, if you like.

⁠6. Run a refgendetector command in the container

The container has the refgendetector in its path, all set up and ready to go, so you can now run any refgendetector or included utility tools command you want. Let's run refgendetector to list all commands available in this version.

refgenDetector

The output will start with a usage message (shown below) and then a full list of commands and their summary descriptions.

`usage: INFERRING THE REFERENCE GENOME USED TO ALIGN BAM OR CRAM FILE

   [-h] -p PATH -t {BAM/CRAM,Headers} [-m] [-a]

INFERRING THE REFERENCE GENOME USED TO ALIGN BAM OR CRAM FILE: error: argument -p/--path is required`

You can verify the tool works by running refgenDetector against our benchmarking data

cd /usr/share/refgenDetector

refgenDetector -p path_to_bam_cram -t BAM/CRAM

refgenDetector -p path_to_headers -t Headers

Once you've verified that this works for you, you know you can run any refgendetector commands you want. But before you proceed, there's one more setup thing to go through, which is technically optional but will make your life much easier.

⁠8. Use a mounted volume to access data that lives outside the container

This is the final piece of the puzzle. By default, when you're inside the container you can't access any data that lives on the filesystem outside of the container. One way to deal with that is to copy things back and forth, but that's wasteful and tedious. So we're going to follow the better path, which is to mount a volume in the container, i.e. establish a link that makes part of the filesystem visible from inside the container.

The hitch is that you can't do this after you started running the container, so you'll have to shut it down and run a new one (not just restart the first one) with an extra part to the command. In case you're wondering why we didn't do this from the get-go, it's because the first command we ran is simpler so there's less chance that something will go wrong, which is nice when you're trying something for the first time.

To close the connection to your container from inside it, you can just type exit while still inside the container:

exit

That should stop the connection to your running container and take you back to your regular prompt, although the container is still running in the background. Now, you need to stop and remove the previously created container ID (named refgendetector)

docker ps -aqf "name=refgendetector"

docker stop <Container_ID>

docker rm <Container_ID>

For now, let's focus on starting a new instance of the refgendetector container, specifying in the following command what is your particular container ID and the filesystem location you want to mount.

docker run -v ~/my_project:/usr/share/refgenDetector/my_data -tid --name refgendetector beacon2ri/refgendetector:v1.0.0

Here we set the external location to be an existing directory called my_project in my home directory (the key requirement is that it has to be an absolute path) and I'm setting the mount point inside the container's /refgendetector directory. The name of the mount point can be the same as the mount directory, or something completely different; the main constraint is that it should not conflict with an existing directory, otherwise that would make the existing directory unattainable.

Assuming your paths are valid, this command runs the container detached. To connect to the container, execute step number 5 and 6 in this documentation; but now you can see by using ls that you have access to your filesystem. So now you can run Beacon commands on any data you have lying around. Have fun!