Docker
Contents
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