CIAO-4.17 Docker Image

This is not an officially supported CXC product. This Docker image was created from the CIAO 4.17 conda installation; it is built in a Debian base image layer.

This is not a guide to using Docker nor using containers. There are numerous online resources for users of all experience levels.

Install podman (or docker)

Docker is a commercial product; users should check the license for terms of use before using it.

podman is a open source alternative to Docker. It is a drop-in replacement. It also does not require root/admin privileges to run, and does not require any system services to be running.

podman is available in most Linux distro’s repositories. It is also available for Mac and Windows and comes with a nice Desktop graphical user interface.

Note: mac will need Xquartz; windows needs an X server. Linux wayland users … don’t know.

In the examples below I will be using the terminal command line to setup and run the docker image. We use the variable $docker to reference the command to run,

podman

for podman use

docker=podman

docker

for docker use

docker=docker

Download ciao-4.17 image tar file

Download the ciao-4.17 image

curl -O https://saotrace.cfa.harvard.edu/ciao/ciao-4.17.0.pod.tar.gz

The download is ~3Gb. Do not un-tar and do not un-gzip the file. Note: this is just a temporary URL and subject to change without notice.

Install docker image

By default $docker will store all the large files in your home directory. Please make sure you have sufficient space and/or quota.

Run

$docker load -i ciao-4.17.0.pod.tar.gz

Check the image is loaded

Run

$docker image ls
REPOSITORY                TAG         IMAGE ID      CREATED         SIZE
localhost/ciao            4.17        6c2c8a2b5041  11 minutes ago  6.85 GB

You can refer to the image as ciao:4.17 or by the SHA 6c2c8a2b5041

Run the image

Linux:

Run:

$docker run -i -t --rm \
  -h $HOSTNAME -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v $XAUTHORITY:/home/docker/.Xauthority \
  -p 8888:8888 \
  ciao:4.17

The last ciao:4.17 is the tag for the image.

Most of the various flags are to get X11 to work securely. Note: You may not have $XAUTHORITY set. If that’s the case then try $HOME/.Xauthority. Are you using Wayland? No idea if this will work; you might need to try the macOS instructions.

The -p flag is needed to run Jupyter labs/notebooks.

You will probably need to chown the .Xauthority file

sudo chown docker:docker /home/docker/.Xauthority

to allow ds9/matplotlib to display correctly.

macOS

Before starting you need to install Xquartz. You will need to logout or reboot after installing Xquartz for the DISPLAY to be set.

In Xquartz go to Settings, Security, and enable “Allow connections from network clients” then exit and restart Xquartz for the setting to take effect.

Next, in your terminal you will need to run

xhost + 127.0.0.1

before running the container.

Then

$docker run --rm -i -t \
    -e DISPLAY=host.docker.internal:0 \
    -p 8888:8888 \
    ciao:4.17

After you exit the container, you should run xhost -.

Windows

Window users – if you have an Xserver running you can try the same command as macos. Otherwise you can simply run

$docker run --rm -i -t -p 8888:8888 ciao:4.17

Note that ds9 and matplotlib will not work w/o an Xserver.

Go to work

At this point you will be logged into the container and the prompt will change and look something like:

(ciao-4.17.0) docker@my_laptop_name:~$

The (ciao-4.17.0) is the standard conda prompt change. docker is the username inside the container.

Note that there is no CALDB installed so you would need to install it separately or use the download_obsid_caldb script.

This also probably is not too useful because it is not able to see any files/folders on your host machine. You might want to exit out of the container and add another “-v” flag to add a data directory to share/export/mount to the container

For example:

$docker run -i -t \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -h $HOSTNAME -e DISPLAY=$DISPLAY \
  -v $XAUTHORITY:/home/docker/.Xauthority \
  -v $HOME/MyDataDirectory:/home/docker/data \
  -p 8888:8888 \
  ciao:4.17

would mount the $HOME/MyDataDirectory directory on the host as /home/docker/data, eg $HOME/data, on the container. If you have a CALDB then you can also mount it the same way.

Note on Dockerfile

The google oracles recommend installing into the base environment because w/ containers not really meant to be switching between environments. But since base is using a different version of Python, I had to install into a separate environment.

Note on Jupyter

The Dockerfile adds files to the ~/.jupyter container to allow jupyter notebook and lab to listen to external IP address ‘0.0.0.0’ You can run

jupyter lab

and then access the notebook server using the 127.0.0.1 URL it provides.