Athena in Mac OS X using Docker containers

Last update: 23 Aug 2024 [History] [Edit]

Install Docker for Mac

Docker for Mac is a macOS native application that uses HyperKit as a lightweight virtualization layer. You can find a detailed installation guide for Docker for Mac here:

Install Docker for Mac

You have the option of installing either the Stable channel or the Edge channel, the latter of which is the development version of Docker for Mac. Start the docker application and verify that it is in your system tray. If you are planning to run resource intensive tasks that will require more memory than the default 2 GB, reconfigure your docker machine in the Docker Preferences menu.

Install CVMFS

Install CVMFS natively on your Mac. Instructions for installing cvmfs are provided by the CVMFS developers here and some ATLAS specific information is here.

The only special thing you need to do for using CVMFS from within docker is to enable /cvmfs as a shareable directory: in the Docker Menu, open Preferences -> File Sharing and add /cvmfs.

Loading an image

Like similar virtualization programs docker uses images to setup and configure a new operating system environment. You can setup, e.g., a new scientific Linux image from scratch and use it on your local machine or distribute it to other machines. Pre-configured images can be stored in Docker Hub and be made available to other users.

Test your docker installation by launching the hello-world docker image:

docker run hello-world

Docker will first attempt to find the hello-world image in the local host. If it fails, it will download the image and run it to display a “Hello from Docker!” message.

X11 forwarding in Docker

When using docker containers interactively you may want to open windows from inside the container. This will require setting up X11 forwarding. First install XQuartz if you have not done so, then update the XQuartz preferences ‘Security’ tab - turn on ‘Allow connection from network clients.’ Finally, restart XQuartz and add your IP address as an allowed client:

ip=$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}') # Adapt en0 to the active interface
xhost + ${ip}

Generic Docker images with HEP software

An example docker image is available with access to ATLAS software over a local installation of CVMFS. Pull the image to the local machine with:

docker pull atlas/atlas_external_cvmfs

The current implementations of bind mounts on macOS provides a consistent view of the host directory tree inside a container. However, the overhead of maintaining perfect consistency can result in very slow I/O. As of version 17.06.0 of the Stable channel a new feature has been introduced to help mitigate this performance degradation. Two options have been provided to relax the requirement of immediate consistency between the host’s view of the filesystem and that from the container. The following flags can be added to the bind mount arguments:

  • consistent: perfect consistency. The host and the container have an identical view of the mount at all times
  • cached: the host’s view is authoritative. Delays are allowed before updates on the host appear in the container
  • delegated: the container’s view is authoritative. Delays are allowed before updates on the container appear in the host

For example, load the HEP image with:

docker run -i -t -v /cvmfs:/cvmfs:cached -v $HOME:$HOME:delegated -e DISPLAY=${ip}:0 atlas/atlas_external_cvmfs 

Note the different command line options for docker run:

  • -it is needed to enter the docker container in interactive mode, i.e., it allows you to execute commands inside the container as you type them at the prompt
  • -v $HOME:$HOME will mount your local machine’s user home directory under /Users/myusername
  • -v /cvmfs:/cvmfs:cached will mount your local CVMFS area. The additional cached (or delegated) option can be used to optimize the access to bind mounted volumes in osxfs (see Optimizing Generic File System Sharing from Bind Mounts)
  • /bin/bash. Depending on how the docker image is configured you may need to specify a login script or command. It is not necessary for the image in the example above, which initiates as the user atlas

Once the container is running, you will be presented with a prompt where you can setup atlas software as usual:

-bash-4.1$ setupATLAS
-bash-4.1$ asetup main,latest,Athena
Using Athena/24.0.6 [cmake] with platform x86_64-centos7-gcc11-opt
	at /cvmfs/atlas-nightlies.cern.ch/repo/sw/main/2023-07-04T2101

You can now start a ROOT session or run a test job in the container:

mkdir run && cd run
Reco_tf.py --AMI q431 --outputESDFile myESD

Save and upload a Docker image

How to commit (save) and push a docker image to a public repository is covered in the Save a Docker image section of Athena for Developers and other Commands.