From 66107382331ca6248ba5d96f0ae5e4fda5fe83a3 Mon Sep 17 00:00:00 2001 From: Pontus Lurcock Date: Thu, 18 Dec 2025 12:54:57 +0100 Subject: [PATCH 1/3] Add docs on debugging container images --- CHANGES.md | 2 +- docs/running-eoaps.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/CHANGES.md b/CHANGES.md index d2dfe6c..f9d3c24 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -3,7 +3,7 @@ * 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) ## Changes in 0.1.1 diff --git a/docs/running-eoaps.md b/docs/running-eoaps.md index e9216b7..3ccd5f0 100644 --- a/docs/running-eoaps.md +++ b/docs/running-eoaps.md @@ -3,6 +3,36 @@ 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 + +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. + +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. + ## Running with cwltool [cwltool](https://www.commonwl.org/user_guide/introduction/quick-start.html) From 2f0949ee5b0c98ddc85bd99289dd494c0bd549f0 Mon Sep 17 00:00:00 2001 From: Pontus Lurcock Date: Thu, 18 Dec 2025 14:30:16 +0100 Subject: [PATCH 2/3] Include Dockerfile in image Addresses #55 --- docs/running-eoaps.md | 13 +++++++++++++ xcengine/core.py | 1 + 2 files changed, 14 insertions(+) diff --git a/docs/running-eoaps.md b/docs/running-eoaps.md index 3ccd5f0..54f6724 100644 --- a/docs/running-eoaps.md +++ b/docs/running-eoaps.md @@ -5,6 +5,8 @@ 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 @@ -12,6 +14,8 @@ 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 @@ -33,6 +37,15 @@ as well, like this: 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 From 287cc5c3e2e3f5b0b471339c352f8eb61f1c2ab3 Mon Sep 17 00:00:00 2001 From: Pontus Lurcock Date: Thu, 18 Dec 2025 14:31:28 +0100 Subject: [PATCH 3/3] Update changelog --- CHANGES.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES.md b/CHANGES.md index f9d3c24..12c2889 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -5,6 +5,7 @@ * `xcetool image run --server` prints server and viewer URLs (#46) * Improve documentation (#54, #55) * Improve type annotations and checks (#68) +* Include Dockerfile in built images (#55) ## Changes in 0.1.1