tweak doc and comment for Dockerfile and its readme

Author: qingfengxia

docker/Dockerfile_ppp_openmc

@@ -2,24 +2,33 @@
 # adapted from https://github.com/Shimwell/openmc_workshop_dependencies
 #
 # Changelog:  1) merge commands to improve performance
-#             2) add gmsh, ppp, occ_faceter
+#             2) add gmsh, ppp, occ_faceter, freecad
 #             3) both X11 and jupyter web interface should be supported
 #             4) ssh server
 #             5) base image can be selected from ubuntu:bionic (18.04), ubuntu:focal (20.04), jupyter/minimal-notebook
 ######################################
 #
 # build with the following command
 #       sudo docker build -f Dockerfile_ppp_openmc -t  ppp_openmc . --no-cache
-#       build from github source seems possible to cache  ( build without  --no-cache) if start quickly enough
-#       use --no-cache  if you know there is no error in this Dockerfile
+#       build without  `--no-cache` can help recover build from where error happened if start quickly enough, 
+#       useful when modify this Dockerfile. The drawback is lots of disk space will be used during trial-and-error process,
+#       It needs to reclaim by docker command afterwards.
+#       use --no-cache  if you know there is no error in this Dockerfile, to save disk space
 # USAGE:  see README.md
 ################################################
 
 
 # jupyter/minimal-notebook is based on ubuntu-focal, so FROM ubuntu:focal should be working
+# if you do not want jupyter-notebook, you can base on ubuntu:focal
 FROM jupyter/minimal-notebook
 #FROM ubuntu:focal
-#FROM ubuntu:bionic
+
+
+# only last CMD is working, if multiple CMD exists, interactive mode also suppress this CMD
+# jupyter can create a terminal, just like ssh
+# uncomment this CMD if the base image is not jupyter, assuming ssh server installation section is kept
+#CMD ["/usr/sbin/sshd","-D"]
+
 
 LABEL name="ppp_openmc" \
     maintainer="qingfeng.xia @ UKAEA" \
@@ -28,11 +37,11 @@ LABEL name="ppp_openmc" \
 
 
 ENV DEBIAN_FRONTEND=noninteractive
-#ENV OS_ID=`awk '/DISTRIB_ID=/' /etc/os-release | sed 's/DISTRIB_ID=//;' `
-#ENV OS_VERSION=`awk '/VERSION_ID=/' /etc/*-release | sed 's/VERSION_ID=//' | sed 's/\"//' | sed 's/\"$//'  `
 
 
-# this can be override by providing environment variable on docker command line
+# for local X11 forwarding, this env var gives a default value
+# this can be overridden to another DISPLAY value
+# by providing environment variable on docker command line `-e DISPLAY=xxx`
 ENV DISPLAY :0
 
 # this is required to install programs on the base image
@@ -43,53 +52,63 @@ RUN apt-get --yes update && apt-get --yes upgrade
 #  sudo is needed as the install NJOY script has a sudo make install command
 RUN apt-get -y install sudo git g++ cmake build-essential wget software-properties-common  
 
-################## if not using jupyter base docker image ########
+#########################################
+## if not using jupyter base docker image 
+#########################################
+# pip install is used later, but pip3 is not installed on ubuntu base images
+# this alias makes sure pip and pip3 are same
 RUN  if test "$NB_UID" = "" ; then \
             apt install -y python3 python3-pip  python3-matplotlib python3-numpy  && \
             apt-get --yes update && \
             ln -s /usr/bin/pip3 /usr/bin/pip && \
             ln -s /usr/bin/python3 /usr/bin/python; \
         fi
-########################################
+########################################################
 
+###################### 
+## ubuntu:bionic only 
+#####################
 # newer CMake version (3.12) allows us to set libraries, includes of the  imported DAGMC target in CMake
-# pip install is used in some of the travis scripts but pip3 is installed, this alias makes pip and pip3 the same 
-###################### ubuntu:bionic only ################
+# for ubuntu foal, cmake version is high enough,  freecad 0.18 is in focal repository
 RUN  if test $(awk '/VERSION_ID=/' /etc/*-release | sed 's/VERSION_ID=//' | sed 's/\"//' | sed 's/\"$//' ) = "18.04" ; then \
             add-apt-repository ppa:freecad-maintainers/freecad-stable && \
             apt remove -y cmake && \
             pip3 install cmake==3.12; \
-        fi
-######################################
+      fi
+##########################################################
+
 
-# install full QT software stack, to make sure matplotlib working with X11 forwording, 
-# it is not needed as freecad will be installed
+##########################
+install QT and full graphic software stack
+##########################
+# install full QT software stack, to make sure matplotlib working with X11 forwarding, 
+# it is not needed if freecad will be installed
 # RUN apt install -y python3-pyside2.qtgui
 
-# why non-root user is needed, because jupyter base image is used, put all files in user home
-# this environment is jupyter/minimal  specific 
+# add apt option --no-recommended to
+RUN apt update && apt install   freecad -y --no-install-recommends
+
+
+
+# why non-root user is needed? because jupyter base image is used, put all files in user home
+# this environment is jupyter/minimal specific 
 # ARG NB_USER="jovyan"
 # see https://github.com/jupyter/docker-stacks/blob/master/base-notebook/Dockerfile
+# if built on ubuntu:focal, build with  -e NB_USER=root
 USER $NB_USER
 
-###################### dependancies for openmc ###################
+###################### dependencies for openmc, maob, dagmc ###################
 # OpenMC required packages identified from openmc travis.yml
 # libnetcdf-dev is needed to allow NETCDF on MOAB which helps with tet meshes in OpenMC
-# RUN apt-get --yes install imagemagick hdf5-tools
 RUN apt-get --yes install imagemagick hdf5-tools mpich  libmpich-dev libhdf5-serial-dev libhdf5-mpich-dev libblas-dev liblapack-dev libnetcdf-dev libeigen3-dev
 
 
+##################################################################
 # MOAB Variables
 ENV MOAB_BRANCH='Version5.1.0'
 ENV MOAB_REPO='https://bitbucket.org/fathomteam/moab/'
 ENV MOAB_INSTALL_DIR=$HOME/MOAB/
 
-
-# DAGMC Variables
-ENV DAGMC_BRANCH='develop'
-ENV DAGMC_REPO='https://github.com/svalinn/dagmc'
-ENV DAGMC_INSTALL_DIR=$HOME/DAGMC/
-
 # MOAB Install
 RUN cd $HOME && \
     mkdir MOAB && \
@@ -103,6 +122,12 @@ RUN cd $HOME && \
     make -j$(nproc) && make  install && \
     rm -rf $HOME/MOAB/moab $HOME/MOAB/build
 
+####################################################################
+# DAGMC Variables
+ENV DAGMC_BRANCH='develop'
+ENV DAGMC_REPO='https://github.com/svalinn/dagmc'
+ENV DAGMC_INSTALL_DIR=$HOME/DAGMC/
+
 # DAGMC Install
 RUN cd $HOME && \
     mkdir DAGMC && cd DAGMC && \
@@ -114,68 +139,85 @@ RUN cd $HOME && \
     rm -rf $HOME/DAGMC/dagmc $HOME/DAGMC/build
 
 
-# /opt folder is owned by root
-USER root
+###############################################
+# Clone and install NJOY2016
+RUN cd $HOME && git clone https://github.com/njoy/NJOY2016 && \
+        cd NJOY2016 && mkdir build && cd build && \
+        cmake -Dstatic=on ..  && \
+        make 2>/dev/null && \
+        sudo make install && \
+        cd .. && rm -rf build
 
 
+###################### OpenMC ##########################
+# /opt folder is owned by root
+USER root
 
-RUN pip install --upgrade numpy matplotlib pyside2  pyansys
+# numpy is needed by openmc-python
+RUN pip install --upgrade numpy matplotlib pyside2
 
-# openmc must be installed to default location  /usr/local/ 
-# so cmake have OpenMCConfig.cmake, which is under /usr/local/lib/cmake/OpenMC
-# installs OpenMC from source (latest), if using jupyter
+# openmc should be installed to default location  /usr/local/ 
+# so cmake can find OpenMCConfig.cmake, which is under /usr/local/lib/cmake/OpenMC
+# installs OpenMC from source (latest)
 RUN cd /opt &&  git clone https://github.com/openmc-dev/openmc.git && \
         cd /opt/openmc && git checkout develop && \
         cd /opt/openmc && mkdir build && \
         cd /opt/openmc/build && cmake -Ddagmc=ON -DDAGMC_ROOT=$DAGMC_INSTALL_DIR -DHDF5_PREFER_PARALLEL=OFF -DCMAKE_INSTALL_PREFIX=..  ..  && \
         cd /opt/openmc/build && make -j$(nproc)  && \
         cd /opt/openmc/build && make install
 
+# build and install python interface for openmc
 RUN cd /opt/openmc/ && python setup.py install && \
         cd .. && rm -rf build
 
+## some python package is needed for openmc
+RUN pip install neutronics_material_maker --user
 
-# Clone and install NJOY2016
-RUN cd $HOME && git clone https://github.com/njoy/NJOY2016 && \
-        cd NJOY2016 && mkdir build && cd build && \
-        cmake -Dstatic=on ..  && \
-        make 2>/dev/null && \
-        sudo make install && \
-        cd .. && rm -rf build
+# Oct 2020, openmc must be installed to /opt/openmc, to install this parametric-plasma-source
+RUN pip install git+https://github.com/open-radiation-sources/parametric-plasma-source.git
 
 
+## to make sure openmc etc are on path for jupyter notebook
 ENV LD_LIBRARY_PATH=$HOME/MOAB/lib:$HOME/DAGMC/lib
 ENV PATH=$PATH:$HOME/MOAB/bin:/opt/openmc/bin:$HOME/DAGMC/bin
 
-RUN pip install git+https://github.com/open-radiation-sources/parametric-plasma-source.git
-
-# no recommended 
-RUN apt update && apt install   freecad -y
 
-#######  install ssh server #####
+####################  
+install ssh server 
+####################
 RUN apt install  openssh-server  nano  -y
 
+# to enable X11 forwarding via ssh
 RUN echo "ForwardX11 yes" >> /etc/ssh/ssh_config &&  echo "ForwardX11Trusted no" >> /etc/ssh/ssh_config 
 
-# change UID from 1000 to 1001, as 1000 has been used by another user
+# use UID 1001, as 1000 has been used by another user
 RUN useradd -rm -d /home/ubuntu -s /bin/bash -g root -G sudo -u 1001 test 
 
+# set password for the user test as "test"
 RUN  echo 'test:test' | chpasswd
 RUN service ssh start
 
-# only last CMD is working, if mutple CMD exists, interactive mode also suppress this
-# jupyter can create a terminal, just like ssh, so there is no needed to install ssh
-# uncomment this CMD is the base image is not jupyter
-#CMD ["/usr/sbin/sshd","-D"]
-
+# expose port, the default
 EXPOSE 22
+##################
+
 
-################### ppp ######################
+##############  
+## install gmsh and pygmsh 
+##############
+RUN apt-get install  -y  gmsh python3-gmsh
+RUN pip install pygmsh
 
-# install PPP & occ faceter, ubuntu 18.04 needs PPA to install occt and freecad
+############################################
+## install dependencies for PPP & occ_faceter
+#############################################
+
+# ubuntu 18.04 needs PPA to install occt and freecad
 # occ_faceter needs libcgal-dev, 
-RUN apt-get install  -y libocct*-dev occt* python3-dev pybind11-dev libtbb-dev libboost-dev libx11-dev libxmu-dev libxi-dev libcgal-dev gmsh
+RUN apt-get install  -y libocct*-dev occt* python3-dev pybind11-dev libtbb-dev libboost-dev libx11-dev libxmu-dev libxi-dev libcgal-dev 
+
 
+## install occ_faceter
 RUN cd $HOME && git clone https://github.com/makeclean/occ_faceter.git && \
     cd occ_faceter && \
     mkdir build && cd build && \
@@ -186,6 +228,7 @@ RUN cd $HOME && git clone https://github.com/makeclean/occ_faceter.git && \
     make install && \
     cd .. && rm -rf build
 
+## install parallel-preprocessor 
 RUN cd $HOME && git clone https://github.com/ukaea/parallel-preprocessor.git && \
     cd parallel-preprocessor && git submodule update --init --recursive && \
     mkdir build && cd build && \
@@ -194,38 +237,38 @@ RUN cd $HOME && git clone https://github.com/ukaea/parallel-preprocessor.git &&
     make install && \
     cd .. && rm -rf build
 
-##################  nuclear material data for openmc #########################
-# install endf nuclear data, this could be skipped and use volume map instead
-# must mapped to /mat_dir
+##################  
+## nuclear material data for openmc 
+###################
+# consider to split the docker image from here
+# copy data into docker image could be skipped and use volume map instead
+# but host folder must be mapped to /mat_dir in the container
 
-# installed on host, copy into container
+# installed on host, the copy into container
 COPY tendl-2019-hdf5 /mat_dir
 
 ENV MAT_DIR=/mat_dir
 ENV OPENMC_CROSS_SECTIONS=$MAT_DIR/cross_sections.xml
 
+##  another way to install material is 
 # clone data repository
-RUN cd $HOME  && git clone https://github.com/openmc-dev/data.git
-
+# RUN cd $HOME  && git clone https://github.com/openmc-dev/data.git
 # run script that converts ACE data to hdf5 data
 #RUN python data/convert_nndc71.py --cleanup
 
 
 ################# openmc workshop ###################
-# for jupyter to work:  
 
+# for jupyter to work:  switch to USER $NB_USER
 USER $NB_USER
 
 RUN git clone -b develop https://github.com/ukaea/openmc_workshop
 # currently there is some bug stop install parametric_plasma_source 
 #RUN cd openmc_workshop && pip install -r requirements.txt
 
-# some python package is needed for openmc
-RUN pip install neutronics_material_maker --user
-
-
 # can WORKDIR be override by command line option yes, by -w argument
 WORKDIR openmc_workshop/tasks
 
-RUN pip install --upgrade vtk pyansys  --user
+###################### some extra tools ###########################
+RUN pip install --upgrade vtk pyansys --user