Using Docker

This short guide should be viewed as a companion to the DAFNI Model preparation guide and the DAFNI model definition guide. You can also find several useful guides on the internet, as well as the Docker manual. One thing to note, is that Docker and Docker Desktop are not the same thing (it's really docker itself we want).

In order to obtain and use Docker, we recommend that you install Rancher Desktop, which is used by the DAFNI development team. Rancher Desktop will give you access to the Docker commands you need (Docker Desktop also gives access to these commands, but is now only available as a licensed commercial product).

Important to note : Docker Desktop is not the same thing as Docker !

Docker : A Quick Guide

When you are uploading a model to DAFNI, it will be a computer model that is written in one of a myriad of different computer languages, and will often use multiple external libraries. One of the challenges in using such a model, is ensuring the model is consistent when running it on different machines (and sometimes with different operating systems). An aspect that people sometimes overlook is that when you are compiling and running computer code on your machine, though it may superficially look just like another computer down the corridor, the two computers may in fact be set up very differently. Taking the example of Python, Python will often have different libraries installed on top of the base-level Python you download - the versions can vary from machine to machine, they could even be on your computer but missing on others, the Python itself can be a different version. The same goes for other languages too, libraries that may be used when compiling your code may be missing on other machines, resulting in your model code not compiling or running on other computers. What docker essentially does is create a miniature facsimile of your local computer setup so this problem can be avoided.

Downloading & Installing Rancher Desktop (includes Docker)

The very first thing you will need to do, is to to download and install Rancher-desktop. Installing rancher-desktop will give you access to all the docker commands you will need for running models on DAFNI. Note that on Windows you must have WSL2 properly setup before running the installer for Rancher Desktop (this is very important & should absolutely not be skipped on Windows machines).

A guide to switching on WSL2 can be found in the Microsoft WSL Guide.

Another thing to keep in mind, is that if you ever need to switch from Docker Desktop to Rancher Desktop be very careful that Docker Desktop has been properly uninstalled from your system (especially with the Windows OS). Carefully check that Docker Desktop has not left any configuration & setup files in user directories. These can conflict very badly with other programs, such as Rancher Desktop, and cause problems that can be hard to diagnose.

Docker Summary Sheet

Once Rancher Desktop has been correctly installed you should be able to run docker commands from a terminal or powershell (Win10/11).

The docker command used to prepare a model image for DAFNI is :-

docker build -t test-example .

You must have a properly structured Dockerfile for this command to work correctly. Note that it doesn't need to be called Dockerfile. You can name the file Alt_Dockerfile.test for example and build it with the extra option -f Alt_Dockerfile.test , added to the previous command.

After the build step you can then save the docker image to an archive file using the command :-

docker save -o test-example.tar test-example

You then will need to use something like gzip or 7-Zip to create a file test-example.tar.gz, which can then be uploaded to DAFNI (together with the config .yaml file, as described in the Model preparation guide)

Tips for Using Docker

One thing to keep in mind is that you'll need to manually start Rancher Desktop and have it running in the background, before running 'docker' commands !

Tip: On Windows, you may find the output text colours are quite hard to read when running docker from the command line (powershell especially). You can use the flag --progress=plain if you encounter this issue.

docker build --progress=plain -t test-example .

Tip: Occasionally you may wish to start a docker container in an interactive terminal, you can do this using the following command (the specific example command below demonstates how to start an interactive python session in a terminal using docker)

docker run -it python:3.9

If you would like to mount a directory to use in a docker container you can do this using the following command. This will run interactive docker session, allowing access to the data stored in $HOME/pythia (it wouldn't be visible within the docker session otherwise, this way it can be found in /home/pythia inside the session)

docker run -it -v $HOME/pythia:/home/pythia python:3.9