diff --git a/projects/docker/README.md b/projects/docker/README.md index 55c9bfb9fad2f1525a8a98c1f989c04c1b08e86c..ea4f89240d808e148fa844f9eb959d1fb71e4776 100644 --- a/projects/docker/README.md +++ b/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](#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*). +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](#run-the-converter-command-in-an-interactive-shell-from-within-the-docker-container) within the container. [[_TOC_]] @@ -74,7 +74,7 @@ $ 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`.): +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. @@ -89,16 +89,31 @@ $ docker run --rm -v /home/user/models:/data -v $(pwd)/USDA-ASFVG/translate2mode $ ``` + +### Run the converter command in an interactive shell from within the Docker container + +As the Docker image comes with a shell ([bash](https://tiswww.case.edu/php/chet/bash/bashtop.html)) installed, the translation script can be started from an interactive session within the Docker container. + +The Docker image does not need a special build command to allow interactive sessions, any from the [app-like](#run-a-fixed-converter-from-within-the-docker-container-app-like) and the [local](#run-a-local-converter-script-with-the-docker-container) variant will work. The magic comes in with the `docker run` command. + +A drawback of running bash inside a Docker container is the lack of your personal configuration which stays outside of the shell by default. That can be mended with a bind mount and with the example call, we also add a bash history file to not lose complex command lines: + +```terminal +$ touch .history +$ docker run --rm -i -t -v /home/user/models:/data -v $HOME/.bashrc:/home/mmcif/.bashrc -v $(pwd)/.history:/home/mmcif/.bash_history -t converter:latest bash +$ +``` + +In the interactive shell, the `convert2modelcif` command is available, as well as any script/ data that is mounted by `docker run -v ...`. + +Be aware of the `touch .history` command before `docker run`. This makes sure a file `.history` exists before starting the Docker container. If the file does not exist, Docker will create a directory `.history` itself but that does not record the bash command history. + <!-- - Do single example call - show how to loop - all build use local UID! -2. Local copy 3. Interactive shell -- works with every build -- most complicated run bit -- include history! 4. Development environment - include pylint, black and pyproject.toml --> @@ -106,8 +121,6 @@ $ <!-- build: - execute: docker build -f docker/Dockerfile -t converter . -- explain how to install a dedicated converter script in the container -- mention how to change user - mention dev stuff - mention .dockerignore in projects readme, like when adding projects consider..., add a reference to it, here