Skip to main content

Docker image

Since we use Docker in our tools, we need to prepare an image first, unless there is already one we can use (in this case, we can skip to the next step).

We start with the source code, available in some repo on GitHub or ORNL's GitLab. What we need is to add an appropriate Dockerfile to this source code and configure automatic image build. If we can work in the original repo - fine, if not - we can create a project with a forked source in https://code.ornl.gov/ndip/tool-sources and work there.

Check if the code is ready for Docker and Galaxy​

Before creating an image, we should understand if the source code is ready to be "dockerized". That means no hard-coded paths (ideally), no assumptions about an environment where the code runs, etc. The inputs should be command line arguments, input files, or mountable input folders. The outputs should be stdout/stderr or in a mountable folder. If the output should be stored in Galaxy, there should be no complex hierarchy of output subfolders.

If the code does not satisfy these conditions, it might be necessary to refactor it. Usually, a couple of simple changes is enough.

Preparing Dockerfile​

So, after a project with the original source code is there, you can add a Dockerfile. You'd need to figure out all the dependencies the code needs and install them as well.

Here are some examples:

You can also use Dockerfile reference for more information.

note

Your image should not rely on ENTRYPOINT, since Galaxy ignores it. You can still have it in Dockerfile (e.g. if you want to use it somewhere else), but you should use the command from entrypoint in the tool command when you create a tool file

tip

One can use same image with for multiple tools, e.g. when the source code contains multiple executables or the same executable can be used for different purpose.

tip

One can use already existing image which already has some dependencies installed (e.g. CUDA image, or Python image , etc) as a base for another one.

Building Image​

You can build an image manually and push it to some registry, but it makes more sense to automate the process. See an example how we do that in GitLab. After a successful build, the image is available at ONRL's public registry in the ndip project.

Verify Image​

Before moving to the next step, it would make sense to check if the image works as expected. Just run it locally and check if it accepts inputs and produces expected outputs. Note that inputs and outputs should be external to image, as they will be later when the tool runs in Galaxy.

note

It can be that your tool require access to SNS/HFIR storage. Although not recommended (since in this case Galaxy does not manage the data, and you create infrastructure dependency in a tool), in some cases this is unavoidable. So, if your software needs that storage you can assume that it will be mounted in the container and accessible from standard /SNS or /HFIR folders. Note that currently it can only be read-only access.