Add comments to scripts and update some directory names

Dockerfile

@@ -14,13 +14,20 @@
 #
 # -----------------------------------------------------------------------------
 
+# get base image
 FROM rockylinux:8.9
 
+# copy required bash scripts for installation and runtime.
+# eventually this can change to COPY . /atchem/ so it is version agnostic
+# but more testing required
 COPY docker/install.sh .
 COPY docker/entrypoint.sh .
 
+# run install script
 RUN /install.sh
 
+# add lable for github container registry
 LABEL org.opencontainers.image.source=https://github.com/wacl-york/AtChem2
 
+# set entrypoint as the script that runs on `docker run`
 ENTRYPOINT [ "/entrypoint.sh" ]

README.md

@@ -57,7 +57,7 @@ The image can be downloaded via:
 docker pull ghcr.io/wacl-york/atchem2:1.2.2
 ```
 
-When running the container, changes to the model (e.g. those made to configurations, constraints and mechanisms) should be in a folder that matches the AtChem2 directory structure. This folder is then mounted as a volume to the container with the name `/inout/`. The mechanism to use is provided as a positional argument to the image and must be stored in `mcm`.
+When running the container, changes to the model (e.g. those made to configurations, constraints and mechanisms) should be in a folder that matches the AtChem2 directory structure. This folder is then mounted as a volume to the container with the name `/data_transfer/`. The mechanism to use is provided as a positional argument to the image and must be stored in `mcm`.
 
 #### Example host file structure:
 ```
@@ -71,7 +71,7 @@ my_model_run
 #### Example Docker run command:
 
 ```
-docker run -it --rm -v /path/to/my_model_run:/inout ghcr.io/wacl-york/atchem2:1.2.2 ./model/my_mech.fac
+docker run -it --rm -v /path/to/my_model_run:/data_transfer ghcr.io/wacl-york/atchem2:1.2.2 ./model/my_mech.fac
 ```
 
 Outputs will be copied to `my_model_run/model/output` on completion.
@@ -86,7 +86,7 @@ apptainer pull path/to/image/atchem2.sif docker://ghcr.io/wacl-york/atchem2:1.2.
 #### Example Apptainer run command:
 
 ```
-apptainer run --bind /path/to/my_model_run/:/inout/ path/to/image/atchem2.sif ./model/my_mech.fac
+apptainer run --bind /path/to/my_model_run/:/data_transfer/ path/to/image/atchem2.sif ./model/my_mech.fac
 ```
 > [!Note]
 > The leading "/" is important when mounting the volume for apptainer, as the container opens in the users "~" directory whereas Docker opens at "/"

docker/entrypoint.sh

@@ -1,3 +1,4 @@
+#!/usr/bin/bash
 # -----------------------------------------------------------------------------
 #
 # Copyright (c) 2009 - 2012 Chris Martin, Kasia Boronska, Jenny Young,
@@ -14,15 +15,42 @@
 #
 # -----------------------------------------------------------------------------
 
-#!/usr/bin/bash
-\command cp -rf /AtChem2-1.2.2/ ~/ # make a copy to home to allow for compatibility with singularity 
-\command cp -rf /inout/* ~/AtChem2-1.2.2/
+# -----------------------------------------------------------------------------
+# This script is run everytime the container is run. 
+#
+# First it copies the /atchem/ directory that is created during the build to 
+# the home directory of the user running the container. This is for
+# compatibility with singularity, where the user running the container is not
+# root, and therfore cannot modify the model files in place. 
+#
+# Next it moves the user configuration from /data_transfer/ and copies it into
+# the ~/atchem/ directory. This /data_transfer/ directory is created when the
+# the user mounts a volume when running the container (e.g `docker run -v...`)
+#
+# We then move to the ~/atchem directory and build the model using the mechanism
+# specified by the user as a runtime argument to `docker run`. 
+#
+# Then the model is run by executing the newly built atchem2 file. 
+#
+# On completion the atchem model output directory is copied to the data_transfer
+# directory and as such onto the host filesystem
+# -----------------------------------------------------------------------------
+
+# make a copy to home to allow for compatibility with singularity 
+\command cp -rf /atchem/ ~/ 
+
+# Transfer in user config
+\command cp -rf /data_transfer/* ~/atchem/
 
-cd ~/AtChem2-1.2.2/
+# move into atchem dir
+cd ~/atchem/
 
+# build model using user specified mechanism
 ./build/build_atchem2.sh $1
 echo $1
 
+# run model
 ./atchem2
 
-cp -r ~/AtChem2-1.2.2/model/output /inout/model/output/
+# copy outputs to data_transfer / host filesystem
+cp -r ~/atchem/model/output /data_transfer/model/output/

docker/install.sh

@@ -1,3 +1,4 @@
+#!/bin/bash
 # -----------------------------------------------------------------------------
 #
 # Copyright (c) 2009 - 2012 Chris Martin, Kasia Boronska, Jenny Young,
@@ -14,17 +15,40 @@
 #
 # -----------------------------------------------------------------------------
 
-#!/bin/bash
+# -----------------------------------------------------------------------------
+# This is the install script that is run when the container is built. It 
+# installs the necessary dependacies for installing AtChem2 (gcc-gfortran,
+# wget, cmake and python3.11) and places the model files into /atchem. 
+#
+# It then runs the install scripts provided with the model (install_cvode.sh 
+# and install_openlibm.sh) to install additional dependancies required to build
+# the model.
+# 
+# Next it produces the Makefile from the skeleton, and ammends the dependancy 
+# paths.
+# 
+# Finally it does some housekeeping, updating the build_atchem2.sh to be able
+# to find the python installation, and makes the docker entrypoint script 
+# executable. 
+# -----------------------------------------------------------------------------
+
+# Install dependancies from package repository
 dnf install -y which gcc-gfortran wget cmake python3.11
-# could make the version number a variable so this can work with other releases?
+
+# make directories
+mkdir /atchem-lib
+mkdir /atchem
+
+# Download the AtChem2 1.2.2 release and unpack into /atchem
 curl -L https://github.com/AtChem/AtChem2/archive/refs/tags/v1.2.2.tar.gz > atchem.tar.gz
-tar -xzf atchem.tar.gz
+tar -xzf atchem.tar.gz -C /atchem --strip-components=1
 rm atchem.tar.gz
-mkdir /atchem-lib
-cd AtChem2-1.2.2
 
-# Install dependancies
-./tools/install/install_cvode.sh /atchem-lib/ # would use version number variable here too...
+# move to /atchem so the dependacy installation scripts work correctly.
+cd atchem
+
+# Install dependancies to /atchem-lib
+./tools/install/install_cvode.sh /atchem-lib/ 
 ./tools/install/install_openlibm.sh /atchem-lib/
 
 # Change atchem dependancy paths and create Makefile from skeleton