Describe how to run local scripts with the container

projects/README.md

@@ -6,5 +6,11 @@ Each project should come with a small README explaining the modelling project. T
 
 The [`docker`](projects/docker/) directory does not host a modelling project. It keeps the set up of a [Docker](https://www.docker.com) image that can be used to run the converter tools from the various projects.
 
+<!--
+Adding projects:
+- file permissions for the translation script (755) so it can be executed by any
+  user
+-->
+
 <!--  LocalWords:  README
  -->

projects/docker/README.md

@@ -2,7 +2,7 @@
 
 This directory contains all the files needed to create the base [Docker](https://www.docker.com) image used for the converter software in [`projects`](projects/).
 
-A specific project's translation script can be executed either in an [app like](#run-a-fixed-converter-from-within-the-docker-container-app-like) manner, calling it directly from within the container, using a local copy executed by the container (*I.O.U. a link to the anchor here*), or in an interactive shell within the container (*I.O.U. a link to the anchor here*).
+A specific project's translation script can be executed either in an [app like](#run-a-fixed-converter-from-within-the-docker-container-app-like) manner, calling it directly from within the container, using a [local copy executed by the container](#run-a-local-converter-script-with-the-docker-container), or in an interactive shell within the container (*I.O.U. a link to the anchor here*).
 
 [[_TOC_]]
 
@@ -62,7 +62,7 @@ $ DOCKER_BUILDKIT=1 docker build -f docker/Dockerfile --build-arg MMCIF_USER_ID=
 $
 ```
 
-After building the Docker image, its time to run the translation command. To do so, we need to make the data available inside the Docker container. This is achieved by [mounting]((https://docs.docker.com/storage/bind-mounts/)) the model-data directory into the Docker container. In the following example, the local `/home/user/models` directory of the host machine is made available as `/data` inside the container. So the command send to `docker run` has to use `/data` as it is executed inside the container:
+After building the Docker image, its time to run the translation command. To do so, we need to make the data available inside the Docker container. This is achieved by [mounting](https://docs.docker.com/storage/bind-mounts/) the model-data directory into the Docker container. In the following example, the local `/home/user/models` directory of the host machine is made available as `/data` inside the container. So the command send to `docker run` has to use `/data` as it is executed inside the container:
 
 ```terminal
 $ docker run --rm -v /home/user/models:/data -t converter:latest convert2modelcif /data/ /data/proteome_accessions.csv
@@ -70,19 +70,31 @@ $
 ```
 
 
+### Run a local converter script with the Docker container
+
+Instead of using the script which is statically copied inside the Docker image, you can also use the Docker container as run time environment executing a translation script from disk. This comes in handy when converting many different modelling project types to ModelCIF. Rather than building individual Docker images per modelling variant, use a single one (that guarantees that all ModelCIF files are build with exactly the same software stack) and iterate through the various translation scripts.
+
+That already works with the Docker image build for [app-like](#run-a-fixed-converter-from-within-the-docker-container-app-like) execution. But in the build example here, we use a file that can not be executed to be copied as `convert2modelcif`. This makes sure that the Docker container is not accidentally run without declaring a specific script (*Note*: don't try to use `docker/README.md` for `CONVERTERSCRIPT`, it is excluded from the build context by `.dockerignore`.):
+
+```terminal
+$ # DOCKER_BUILDKIT=1 is only needed for older versions of Docker.
+$ DOCKER_BUILDKIT=1 docker build -f docker/Dockerfile --build-arg MMCIF_USER_ID=1234 --build-arg CONVERTERSCRIPT=docker/requirements.txt -t converter:latest .
+$
+```
+
+The dedicated translation script is made available inside the Docker container as a direct [bind mount](https://docs.docker.com/storage/bind-mounts/) to the installed converter command. The remaining parameters are the same as for the [app-like](#run-a-fixed-converter-from-within-the-docker-container-app-like) `docker run` command:
+
+```terminal
+$ docker run --rm -v /home/user/models:/data -v $(pwd)/USDA-ASFVG/translate2modelcif.py:/usr/local/bin/convert2modelcif -t converter:latest convert2modelcif /data/ /data/proteome_accessions.csv
+$
+```
 
 <!--
 - Do single example call
 - show how to loop
 - all build use local UID!
 
-1. App like
-- own run command
 2. Local copy
-- works with every build
-- own run command
-- still has a default script installed as in 1.
-- can be overwritten by mounting
 3. Interactive shell
 - works with every build
 - most complicated run bit
@@ -107,5 +119,5 @@ docker run --rm -i -v /Users/stefan/.bash_profile:/home/mmcif/.bash_profile -v /
  -->
 
 <!--  LocalWords:  TOC modelcif cd whoami localuser uid arg CONVERTERSCRIPT
-      LocalWords:  CONVERTERCMD cif ASFVG BUILDKIT
+      LocalWords:  CONVERTERCMD cif ASFVG BUILDKIT pwd
  -->