Docker provides a platform for distribution of application state. This facilitates the highest level of scientific reproducibility - as a Docker image can bundle operating system, Java version, update site and plugin state, and even sample data. These images can then be reused by remote users and scientists worldwide, with no dependency concerns (beyond Docker itself).

Pre-Requisites

You will need to install Docker for your system.

How to use the Fiji Docker images

The base Fiji images are provided on Docker Hub. These images call the Fiji executable by default. For example:

 docker run -it --rm fiji/fiji

will call the default Fiji image, attempting to open the ImageJ UI with Java 7.

Several tags are provided to run Fiji with different Java versions. For example, if you wanted to run with Oracle's Java 6, you would use:

 docker run -it --rm fiji/fiji:fiji-oracle-jdk6

Important - without some extra setup, there is no display used by Docker. So if you just tried one of the above commands, you likely got an error:

 No GUI detected.  Falling back to headless mode.

The following sections cover headless and graphical uses.

Running headless

Running ImageJ headlessly in Docker is not much different than normal headless operation - see the headless guide for general information. To start a headless ImageJ invocation from Docker, use:

 docker run -it --rm fiji/fiji fiji-linux64 --headless

If you want to manually explore the Fiji Docker image, e.g. to install additional plugins or utility software, you can start the command prompt via:

 docker run -it --rm fiji/fiji bash

Just be sure to commit any changes!

Running the UI

This is, unfortunately, currently quite platform-specific. Docker has tight Linux integration, so it is much easier to share displays with a Docker image if you are using a Linux host. However, it is not impossible on other architectures.

Note that this is highly experimental right now, and the steps to get Fiji running can be fairly involved. Please report issues and contribute suggestions if you have ideas for improving interoperability between Fiji's UI and Docker.

On Linux

We can adapt this blog post on running GUI applications with Docker to share the X11 port.

Use this Dockerfile as a starting point:

 # Modify this tag if a different java version is desired
 FROM fiji/fiji:fiji-openjdk-7
 # Replace 1000 with your user / group id
 RUN export uid=1000 gid=1000 && \
     mkdir -p /home/developer && \
     echo "developer:x:${uid}:${gid}:Developer,,,:/home/developer:/bin/bash" >> /etc/passwd && \
     echo "developer:x:${uid}:" >> /etc/group && \
     echo "developer ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/developer && \
     chmod 0440 /etc/sudoers.d/developer && \
     chown ${uid}:${gid} -R /home/developer
 USER developer
 ENV HOME /home/developer
 CMD fiji-linux64

Install the Dockerfile with:

 docker build -t fiji .

Run Fiji with:

 docker run -ti --rm \
      -e DISPLAY=$DISPLAY \
      -v /tmp/.X11-unix:/tmp/.X11-unix \
      fiji/fiji

Which should pop up a window with Fiji running.

On OSX

boot2docker

To get a GUI application running on OSX, we can adapt the techniques discussed in this docker issue to run an X11 session, and share it with Docker.

First, you will need to install the following:

Then, from a terminal, use Homebrew to install socat and XQuartz via:

 brew install socat

 brew cask install xquartz

Now open a new terminal window and type

 echo $DISPLAY

and ensure it is not empty (it should print something like /private/tmp/com.apple.launchd.GYg5TvcMIf/org.macosforge.xquartz:0).

Then run:

 ifconfig

which will print output that should end with something like:

 vboxnet0: flags=0000<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST>
 ether 00:00:00:00:00:00
 inet 192.168.15.2 netmask 0xffffffff broadcast 192.168.0.0

And take note of the ip address on the last line (192.168.15.2 in this case).

Since you are using OSX it is assumed you are using boot2docker. Now, in the same terminal you started boot2docker, you should have set up the environment variables e.g. with

 $(boot2docker shellinit)

From this same terminal, open XQuartz with:

 open -a XQuartz

This will start up a new X11 session. You will want two X11 terminals open here (Application > Terminal to open a new X11 terminal).

In one X11 terminal, run:

 socat TCP-LISTEN:6000,reuseaddr,fork UNIX-CLIENT:\"$DISPLAY\"

to start listening for X11 forwarding. In the second terminal, you can now use Docker to launch a Fiji GUI. For example:

 docker run -e DISPLAY=192.168.15.2:0 fiji/fiji

Where the IP address was what we found earlier with ifconfig.

Congratulations! You should now be running Fiji in a Docker image.

Kitematic

Kitematic is a UI-oriented way to start Docker containers on Macs. It makes it very easy to download and run new images. However we have not yet investigated how to run the Fiji UI with Kitematic.

Exposing your data

Once you have Fiji up and running, you will probably want to open some images.

The best way to share data with Docker is to use volumes, as described in this blog post.

For example, if your data is in /Users/foo/data, launching the Fiji image with:

 docker run -v /Users/foo/data:/fiji/data -e DISPLAY=192.168.15.2:0 fiji/fiji

will create a data subdirectory in the Fiji installation, which you can then open images from as normal.

For more information on using volumes, see the Docker user guide.

Dockerfiles

Dockerfiles for Fiji can be found on GitHub. See the official documentation for directions on building images from Dockerfiles.

Docker image structure

In these docker images, you will find Fiji installed in the /fiji directory, which has been added to the PATH of the image (so that Fiji can be run as the default command).

Troubleshooting

If you run into any problems or have questions about ImageJ + Docker, please use:

GitHub
The mailing lists

Docker

Contents