diff --git a/CHANGES.md b/CHANGES.md index d2dfe6c..12c2889 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -3,8 +3,9 @@ * Improve handling of environment file specification (#63) * Stop running container on SIGINT (#62) * `xcetool image run --server` prints server and viewer URLs (#46) -* Improve documentation (#54) +* Improve documentation (#54, #55) * Improve type annotations and checks (#68) +* Include Dockerfile in built images (#55) ## Changes in 0.1.1 diff --git a/docs/running-eoaps.md b/docs/running-eoaps.md index e9216b7..54f6724 100644 --- a/docs/running-eoaps.md +++ b/docs/running-eoaps.md @@ -3,6 +3,49 @@ Application Packages are generally deployed to cloud platforms, but there are also ways to run CWL files and complete Application Packages locally. +## Understanding and debugging xcengine container images + +### The base image + +When generating a container image, xcengine uses a +[micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html) +image as a base. If you need to investigate or +debug an xcengine image, or if you're just curious about its structure, you may +find the [micromamba-docker +documentation](https://micromamba-docker.readthedocs.io/) useful. + +### Entry points + +xcengine sets a custom entry point to run its own runner script, so any commands +provided when running a container from an xcengine image with `docker run` +will be applied as arguments to the xcengine runner. For instance, for an +image tagged `myimage:1`, the `--server` parameter can be used like this: + +`docker run myimage:1 --server` + +This would run the xcengine runner script with the `--server` option, which +starts an xcube server and viewer instance. + +To explore or debug a container image, it's often useful to start a container +with an interactive shell. To do this with an xcengine image, it's not enough +to provide a path to a shell as a command, since this path will just be passed +as a parameter to the xcengine runner script. You need to set the entry point +as well, like this: + +`docker --rm -it --entrypoint /usr/local/bin/_entrypoint.sh myimage:1 bash` + +This resets the entry point to the usual micromamba-docker entry point, which +sets up the Python environment, then runs bash within that environment. + +### The Dockerfile and environment file + +To aid reproducibility, the Dockerfile and environment file used to set up the +container image are both included in the image itself, in the `/tmp` +directory. The rest of the code and configuration for the image is in the +`/home/mambauser` directory. In combination with the publicly available +micromamba base image, each xcengine image thus contains the resources +necessary to reproduce its own build process. + ## Running with cwltool [cwltool](https://www.commonwl.org/user_guide/introduction/quick-start.html) diff --git a/xcengine/core.py b/xcengine/core.py index 26dcca3..1efbf95 100755 --- a/xcengine/core.py +++ b/xcengine/core.py @@ -302,6 +302,7 @@ def _build_image(self) -> docker.models.images.Image: dockerfile = textwrap.dedent( """ FROM mambaorg/micromamba:1.5.10-noble-cuda-12.6.0 + COPY Dockerfile Dockerfile COPY environment.yml environment.yml RUN micromamba install -y -n base -f environment.yml && \ micromamba clean --all --yes