CAMI

How to put my tool into a docker container?

(One of many ways)

CAMI docker containers should work with

This tutorial is based on the bioboxes interfaces version 0.8

There is now a 0.9 version for an assembler biobox. Bioboxes.org offers a tutorial for building 0.9.0 Bioboxes.

Contents

  1. Install Docker
  2. Download an Image
  3. Image Interface
  4. Install your Tool
  5. Share your Container
  6. Contact

The example sections show
how I put MetaBAT into a docker container.

1. Install Docker

Docker is available on almost every system.

On a linux based system like Ubuntu you can use the package manager:


$ sudo apt-get update
$ sudo apt-get install docker.io
                    

For Mac OS X, Microsoft Windows you have to follow the docker installation instructions

2. Download an Image

We have prepared images that make it easy for you to build docker containers.

You can choose between assembly, binning and profiling

Get an image from Docker Hub with:


$ docker pull cami/binning
                        

Every image defines an interface (next section).

3.1 Image Interface

Every image interface defines a set of environment variables.

You get a definition for every variable on GitHub

Example:
CONT_CONTIGS_FILE defines the path to the contigs file.


Press arrow key down for an interface example.

3.1 Image Interface - Example

The first step is to pull the base image


$ docker pull cami/binning
                            

Now I can build my image on top of cami/binning.


Press arrow key down for the next step.

3.1 Image Interface - Example

The binning interface defines which environment variables are optional and which one are mandatory.

In this case we have the environment variables:

  • CONT_FASTQ_FILE_LISTING and
  • CONT_CONTIGS_FILE_LISTING as input
  • CONT_BINNING_FILE as output

Furthermore you have to define a default task (This will be explained in the 'Install your tool section'.


Press arrow key down for the next step.

3.1 Image Interface - Example

--list-mount tells you which directories must be mounted to the container:


$ docker run  cami/binning --list-mount
/dckr/mnt/input/
/dckr/mnt/output/
                            

Everything inside the directories that are mounted to /dckr/mnt/input and /dckr/mnt/output will be visible inside the container.


Press arrow key down for the next step.

3.1 Image Interface - Example

You can list the CAMI image specific variables with --list-spec


$ docker run  cami/binning --list-spec
CONT_BINNING_FILE=/dckr/mnt/output/sample.camib
CONT_CONTIGS_FILE_LISTING=/dckr/mnt/input/contigs.fna.list
CONT_FASTQ_FILE_LISTING=/dckr/mnt/input/sample.fq.gz.list
...
                            

Since the container expects sample.fq.gz.list and contigs.fna.list in the same directory, I have renamed and moved my sample and contigs to one directory (/home/belmann/cami/input)


Press arrow key down for the next step.

3.1 Image Interface - Example

Now I can start the container with:

$ docker run \
-v /home/belmann/cami/input:/dckr/mnt/input:ro \
-v /home/belmann/cami/output:/dckr/mnt/output:rw \
-v /home/belmann/cami/scripts:/scripts:ro \
-t -i cami/binning --shell
$ root@c4asdfsdaf43:/#

Note! I mounted a scripts directory with different tools

  • -v : Mounts the directory to the container
  • -t : Allocates a pseudo-TTY
  • -i : Keep STDIN open
  • --shell:Starts a shell

3.2 Image Interface

Note! If any variable that you need for your container is missing then please contact us!

  • email to support@cami-challenge.org
  • or
  • Write an issue at GitHub

We will update the specifications as soon as possible.

4.1 Install your Tool

You can install any tool like in any other operating system.

If you want to add scripts/tools from your local host, you can do this by mounting a host directory as already described in the previous example or by using an ADD command in a Dockerfile.

You have to add a task in /dckr/mnt/task.d/ that will be executed when running the container.


Press arrow key down for a practical example.

4.1 Install your Tool - Example

For MetaBAT I had to install some libraries. First I started the container like this and installed libraries like:


$ apt-get update
$ apt-get install samtools
$ apt-get install libboost-all-dev
$ apt-get install scons
$ apt-get install g++
                            

Press arrow key down for the next step.

4.1 Install your Tool - Example

In /dckr/etc/task.d I implemented a default task that you can run with:

$ docker run \
-v /home/belmann/cami/input:/dckr/mnt/input:ro \
-v /home/belmann/cami/output:/dckr/mnt/output:rw \
-v /home/belmann/cami/scripts:/scripts:ro \
-t -i cami/metabat_example default
                            

4.1 Install your Tool - Example

I have tested my scripts and metabat first inside the Container

Every intermediate step, like index files, were moved to /tmp because it is cleaned up after the execution of the container.

4.2 Install your Tool

When you have installed your tool, you have to do the following steps:

  • logout (like a normal shell logout)
  • list your just terminated container with `docker ps -a`
  • persist your container `docker < container_id> < name>`

Now you can share your image with the world!

Press arrow key down for a practical example.

4.2 Install your Tool - Example

After the installation and the logout I first listed the just terminated container:

$ docker ps -a
CONTAINER ID    IMAGE        COMMAND        CREATED    STATUS    PORTS    NAMES
d8s23sd8d8fu    cami/binning    "/bin/bash"    2 hours    Exited            stupefied_blackwell
and then committed it to the image name "cami/metabat_example":
$ docker commit d8s2 cami/metabat_example

5. Share your Container

You can share your docker container by getting an account at docker.com and uploading it to Docker Hub

When you have uploaded your docker container, tell us the repository name of your container and the task you have executed for the specific data set.

6. Contact

Please contact us if you face any problems with docker!

support@cami-challenge.org