Creating a Docker Virtual Environment for a Bmad Distribution

---

---

Overview

NOTE: Using Docker to setup a Bmad Release has essentially been abandoned in favor of using Conda-Forge. The Docker setup instructions are kept here for reference.

Docker is a program where software can be run in a virtual environment called a container. In particular, containers may be setup to build Bmad Distributions . The advantage is that for people with no experience, it is easier to setup a container than it is to setup a Bmad Distribution directly on your local computer. The drawback is that a container adds a layer between a program to be run and the user. Alternatively, using Conda-Forge is oftentimes the better solution.

Note: Running Docker on Linux requres sudo privileges.

Some definitions:

• Image: A Docker image is a file that contains code that is executed in a Docker container.
• Container: A Docker container packages up an image and all its dependencies so the application runs from one computing environment to another.

Some Docker commands:

docker                           # List of docker commands
docker help             # Help on a command
docker ps -a                     # List all docker containers
docker rm $(docker ps -aq)       # Remove all containers
docker images                    # List docker images
docker rmi $(docker images -q)   # Remove all images

---

---

Creating a Docker Container on Windows

Instructions here.

---

---

Non-Windows Docker Setup

Linux:

Linux Ubuntu:

1. sudo apt update
2. sudo apt install docker.io
3. sudo docker run hello-world. Expected output:

   Unable to find image 'hello-world:latest' locally
   latest: Pulling from library/hello-world
   0e03bdcc26d7: Pull complete
   Digest: sha256:d58e752213a51785838f9eed2b7a498ffa1cb3aa7f946dda11af39286c3db9a9
   Status: Downloaded newer image for hello-world:latest
   
   Hello from Docker!
   This message shows that your installation appears to be working correctly

MacOS:

If docker is already installed, check that the docker daemon is running. On a Mac you will see a docker icon in the menu bar (bar at top of screen) towards the right. If the daemon is not running, Run the docker program and this should start the daemon.

1. From docker.com download and install Docker Desktop.
2. Open Docker to complete the install process.
3. You can check to see if Docker is running by issueing the ‘docker’ command in a terminal window.

---

---

Non-Windows X11 Setup

X11 is used by Tao and other programs displaying graphics.

Linux:

Needed is the X11 Core and Development Libraries (libX11 and libX11-devel). For installation instructions, see the section Libraries and Tools Needed for Compiling of the Bmad Distribution Setup page.

MacOS:

1. Install XQuartz from XQuartz.org.
2. In the XQuartz preferences, go to the "Security" tab and make sure the “Allow connections from network clients” box is checked.
3. Restart XQuartz.
4. X11 communication between the container and the local computer is via the computer's IP address. To find the IP address, use the ifconfig command

   ifconfig en0

   In the output, if you see a line beginning with inet (but not inet6) like

   inet 192.168.1.211 netmask 0xffffff00 broadcast 192.168.1.255

   then the IP address is 192.168.1.211. If there is no inet line, the IP address should be associated with port en1. So use en1 in place of en0 in the ifconfig command. The IP address can be bound to a variable using the command

   export IP_ADDR=$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}')

   (use en1 instead of en0 if the IP addresss is associated with en1). To check if the IP address is correctly bound, use the echo command:

   > echo $IP_ADDR
   192.168.1.255

5. To Add the IP address to the list of authorized clients that can connect, use the command

   xhost + $IP_ADDR

   To check that the authorized client list is properly setup, use the command xhost. The result should look something like:

   > xhost
   access control enabled, only authorized clients can connect
   INET:192.168.1.211

---

---

Non-Windows Building a Container

Linux:

FROM centos:8 as builder 
ARG USER_ID 
ARG GROUP_ID
ARG BMADDIST
# Install developer tools 
RUN groupadd --gid $GROUP_ID bmad 
RUN adduser --uid $USER_ID --gid $GROUP_ID bmad 
RUN dnf -y update \ 
   && dnf -y group install "Development Tools" 
RUN dnf config-manager --enable PowerTools 
RUN dnf install -y xorg-x11-apps 
ENV buildDeps gcc-gfortran cmake libtool libXt-devel readline-devel bc pango-devel cairo-devel 
RUN dnf install -y $buildDeps 
# Get Bmad distribution 
RUN echo "Distribution name is: $BMADDIST"
RUN curl -O https://www.classe.cornell.edu/~cesrulib/downloads/tarballs/$BMADDIST.tgz \ 
 && tar -xzf /$BMADDIST.tgz \ 
 && mv $BMADDIST bmad_dist \ 
 && rm -rf /$BMADDIST.tgz 
RUN chown -R bmad:bmad bmad_dist 
USER bmad 
WORKDIR /bmad_dist 
# Make RUN commands use bash 
SHELL ["/bin/bash", "-c"] 
# Bmad dependencies 
# Build Bmad 
RUN echo "export ACC_PLOT_PACKAGE=plplot" >> util/dist_prefs \ 
   && echo "export ACC_ENABLE_SHARED=Y" >> util/dist_prefs \ 
   && echo "export ACC_ENABLE_FPIC=Y" >> util/dist_prefs \ 
   && . util/dist_source_me \ 
   #&& cd plplot;mk # For testing 
   && util/dist_build_production 
ENV DIST_BASE_DIR /bmad_dist 
ENV PATH $PATH:$DIST_BASE_DIR/production/bin:$DIST_BASE_DIR/util 
ENV LD_LIBRARY_PATH $LD_LIBRARY_PATH:$DIST_BASE_DIR/production/lib 
ENV TAO_DIR $DIST_BASE_DIR/tao 
ENV lat $DIST_BASE_DIR/tao/examples/cesr/bmad_L9A18A000-_MOVEREC.lat 
CMD ["bash"]

MacOS:

FROM centos:8 as builder
ARG BMADDIST
# Install developer tools
RUN dnf -y update \
    && dnf -y group install "Development Tools" 
# Get Bmad distribution
RUN echo "Distribution name is: $BMADDIST"
RUN curl -O https://www.classe.cornell.edu/~cesrulib/downloads/tarballs/$BMADDIST.tgz \
  && tar -xzf /$BMADDIST.tgz \
  && mv $BMADDIST bmad_dist \
  && rm -rf /$BMADDIST.tgz
WORKDIR /bmad_dist
# Make RUN commands use bash
SHELL ["/bin/bash", "-c"]
# Bmad dependencies
ENV buildDeps gcc-gfortran cmake libtool libXt-devel readline-devel bc pango-devel cairo-devel
RUN dnf install -y  $buildDeps

RUN dnf config-manager --enable PowerTools
RUN dnf install -y xorg-x11-apps

# Build Bmad
RUN echo "export ACC_PLOT_PACKAGE=plplot" >> util/dist_prefs \
    && echo "export ACC_ENABLE_SHARED=Y" >> util/dist_prefs \
    && echo "export ACC_ENABLE_FPIC=Y" >> util/dist_prefs \
    && . util/dist_source_me \
    #&& cd plplot;mk  # For testing
    && util/dist_build_production

ENV DIST_BASE_DIR /bmad_dist
ENV PATH $PATH:$DIST_BASE_DIR/production/bin:$DIST_BASE_DIR/util
ENV LD_LIBRARY_PATH $LD_LIBRARY_PATH:$DIST_BASE_DIR/production/lib
ENV TAO_DIR $DIST_BASE_DIR/tao
ENV lat $DIST_BASE_DIR/tao/examples/cesr/bmad_L9A18A000-_MOVEREC.lat

CMD ["bash"]

1. It is assumed that you know how to use a command line terminal app on your computer. If not, please seek local guidance.
2. Make sure the docker app is running. See above.
3. Copy the above script to a directory on your computer and name it Dockerfile-full
4. In the directory that holds the Dockerfile-full file, build the Docker container using the command
   Linux

   BMADDIST=$(curl https://www.classe.cornell.edu/~cesrulib/downloads/latest_distribution_file_prefix)
   sudo docker build -f Dockerfile-full -t docker_bmad \
    --build-arg USER_ID=$(id -u) --build-arg GROUP_ID=$(id -g) 

   --build-arg BMADDIST=$BMADDIST MacOS
   

   BMADDIST=$(curl https://www.classe.cornell.edu/~cesrulib/downloads/latest_distribution_file_prefix)
   docker build -f Dockerfile-full -t docker_bmad --build-arg BMADDIST=$BMADDIST .

   Notice the period at the end the command. The above command will create a Docker container called docker_bmad. Note: Docker containers are held by Docker in a central location and not in the directory from which the container was made.

---

---

Non-Windows Running a Container

First make sure you have followed the steps for the X11 setup.

To run a container use one of the following commands. The -v option mounts (associates) a local volume (directory) with a directory in the container. A colon separates the local directory name from the container directory name. If the container directory does not exist, Docker will create it. Modify the local directory name in the examples to correspond to an actual local directory. Mounting volumes is optional and is used as a way to share files between the container and the local computer.

Linux:

sudo docker run --rm -ti -u $(id -u):$(id -g) \
-e DISPLAY=unix$DISPLAY -v "/tmp/.X11-unix:/tmp/.X11-unix" \
-v "/etc/group:/etc/group:ro" -v "/etc/passwd:/etc/passwd:ro" docker_bmad

MacOS:

docker run --rm -ti -e DISPLAY=$IP_ADDR:0 -v /Users/dcs16/:/dcs16 docker_bmad

This example mounts the local mac directory /Users/dcs16 with the docker container directory /dcs16. Modify this to match your home directory.

---

---

Test

On the container command line the following test can be made:

xclock                       # A window with a clock should appear
tao -lat $lat -geom 400x500  # This runs tao and a plot window should appear