Merge pull request #70 from xcube-dev/pont-55-dockerfile-image

Put the Dockerfile in the generated image

Author: pont-us

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
 

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)

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