GRIME3 0.1.0 RC9 — Docker Quick Start and Deployment Guide
The RC9 Docker/OCI image provides the same deterministic GRIME3 browser and command-line measurement implementation as the standalone and Conda distributions.
The deterministic RC9 image excludes FFmpeg, the future SDF model,
PyTorch, SAM2 and Qt. It uses the same prepared Linux OpenCV runtime as
the Linux standalone distribution. Its native OpenCV version is 5.0.0;
the prepared Python distribution version is
5.0.0.93+grime3.1. Build and OpenCV provenance are retained
under /opt/grime3/.
Platform scope
The native RC9 validation target is:
linux/amd64
Therefore:
- x86-64 Linux can run the image directly;
- Windows can run the Linux container through Docker Desktop;
- macOS can run it through Docker Desktop;
- Apple Silicon and ARM Linux may use amd64 emulation where supported;
- native ARM64 and multi-architecture images are post-RC9 roadmap work.
The RC9 image is a Linux container image, not a Windows-container image.
Persistent data layout
The container uses:
/data/config
/data/images
/data/results
/data/database
Recommended purposes are:
/data/config— Site Configuration and related configuration;/data/images— source images;/data/results— scientific outputs;/data/database— persistent database material.
Configuration and images can normally be mounted read-only. Results and database storage should be persistent.
Containers are disposable. Scientific data should not exist only inside a container's writable layer.
Build from RC9 source
GRIME3_GIT_COMMIT="$(git rev-parse HEAD)"
GRIME3_GIT_SHORT_COMMIT="$(git rev-parse --short=7 HEAD)"
GRIME3_GIT_TAG="$(git describe --tags --exact-match HEAD)"
GRIME3_GIT_DIRTY=false
GRIME3_BUILD_ID="0.1.0-rc9-${GRIME3_GIT_SHORT_COMMIT}"
GRIME3_BUILD_UTC="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
test "$GRIME3_GIT_TAG" = "grime3-0.1.0-rc9"
test -z "$(git status --porcelain --untracked-files=all)"
docker build \
--build-arg GRIME3_GIT_COMMIT="$GRIME3_GIT_COMMIT" \
--build-arg GRIME3_GIT_SHORT_COMMIT="$GRIME3_GIT_SHORT_COMMIT" \
--build-arg GRIME3_GIT_DIRTY="$GRIME3_GIT_DIRTY" \
--build-arg GRIME3_GIT_TAG="$GRIME3_GIT_TAG" \
--build-arg GRIME3_BUILD_ID="$GRIME3_BUILD_ID" \
--build-arg GRIME3_BUILD_UTC="$GRIME3_BUILD_UTC" \
--build-arg GRIME3_RELEASE_CHANNEL=release-candidate \
--tag grime3:0.1.0-rc9 \
.Official release images must be built from the immutable RC9 source tag.
For a pre-tag validation image, use a clean checkout of the full
reviewed commit, an empty GRIME3_GIT_TAG, a validation
GRIME3_BUILD_ID, and
--build-arg GRIME3_RELEASE_CHANNEL=pretag-validation. Keep
its image name distinct from the official release. The helper rejects a
release tag, dirty source, or inconsistent full/short commit values in
this mode.
Browser operation
docker run --rm \
-p 8000:8000 \
grime3:0.1.0-rc9Open:
http://127.0.0.1:8000/
The container uses --no-open-browser internally because
a container cannot launch the host browser.
Browser operation with persistent data
Linux example:
docker run --rm \
--user "$(id -u):$(id -g)" \
-p 8000:8000 \
--mount type=bind,src="/absolute/site",dst=/data/config \
--mount type=bind,src="/absolute/images",dst=/data/images,readonly \
--mount type=bind,src="/absolute/results",dst=/data/results \
--mount type=bind,src="/absolute/database",dst=/data/database \
grime3:0.1.0-rc9Using the host UID and GID on Linux helps prevent root-owned writable files.
Docker Desktop users should use host paths accepted by their operating system and make those directories available to Docker when required.
CLI help
docker run --rm \
grime3:0.1.0-rc9 \
measure --helpMeasure one image
docker run --rm \
--user "$(id -u):$(id -g)" \
--mount type=bind,src="/absolute/site",dst=/data/config,readonly \
--mount type=bind,src="/absolute/images",dst=/data/images,readonly \
--mount type=bind,src="/absolute/results",dst=/data/results \
grime3:0.1.0-rc9 \
measure image \
--image /data/images/image001.jpg \
--site-config /data/config/site_config.json \
--output-dir /data/resultsMeasure one folder
docker run --rm \
--user "$(id -u):$(id -g)" \
--mount type=bind,src="/absolute/site",dst=/data/config,readonly \
--mount type=bind,src="/absolute/images",dst=/data/images,readonly \
--mount type=bind,src="/absolute/results",dst=/data/results \
grime3:0.1.0-rc9 \
measure folder \
--images /data/images \
--site-config /data/config/site_config.json \
--output-dir /data/resultsMeasure a folder of folders
docker run --rm \
--user "$(id -u):$(id -g)" \
--mount type=bind,src="/absolute/site",dst=/data/config,readonly \
--mount type=bind,src="/absolute/campaign",dst=/data/images,readonly \
--mount type=bind,src="/absolute/results",dst=/data/results \
grime3:0.1.0-rc9 \
measure folders \
--images-root /data/images \
--site-config /data/config/site_config.json \
--output-dir /data/resultsDocker Compose
Create persistent host directories:
mkdir -p data/config data/images data/results data/databaseFor an official RC9 build from the immutable tag, export the complete release identity before invoking Compose:
test "$(git describe --tags --exact-match HEAD)" = "grime3-0.1.0-rc9"
test -z "$(git status --porcelain --untracked-files=all)"
export GRIME3_GIT_COMMIT="$(git rev-parse HEAD)"
export GRIME3_GIT_SHORT_COMMIT="$(git rev-parse --short=7 HEAD)"
export GRIME3_GIT_DIRTY=false
export GRIME3_GIT_TAG="grime3-0.1.0-rc9"
export GRIME3_BUILD_ID="0.1.0-rc9-${GRIME3_GIT_SHORT_COMMIT}"
export GRIME3_BUILD_UTC="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export GRIME3_RELEASE_CHANNEL=release-candidate
export GRIME3_IMAGE="grime3:0.1.0-rc9"On Linux, also use the host UID and GID:
export GRIME3_UID="$(id -u)"
export GRIME3_GID="$(id -g)"Start:
docker compose up --buildWhen release variables are not supplied, compose.yaml
deliberately uses grime3:development together with
development/dirty provenance. It does not silently identify an
unprovenanced build as an RC9 release image.
A different host port can be selected:
export GRIME3_PORT=8080
docker compose up --buildThen open:
http://127.0.0.1:8080/
Site Configuration portability
The same canonical Site Configuration used by standalone or Conda GRIME3 can be mounted into the Docker container.
A host path such as:
/home/user/site/site_config.json
can appear in the container as:
/data/config/site_config.json
The filesystem path is only a storage location. Persistent Site and Configuration UUIDs remain the logical scientific identity.
After moving data or configurations, verify the projected calibration and ROIs on a representative image before starting a large run.
Updating the image
Do not modify a running container to upgrade GRIME3.
Build or obtain the newer image, stop the old container, and launch the new one against deliberately preserved data mounts.
For Compose:
docker compose down
docker compose build --no-cache
docker compose up -dStopping
For an interactive container, Ctrl+C stops the browser process.
For Compose:
docker compose downRemoving a container does not remove bind-mounted host data.
Container security baseline
The RC9 image:
- runs as a non-root numeric user;
- contains the GRIME3 PyInstaller runtime rather than a Python build environment;
- does not contain
apt,dpkg, or a command shell; - excludes Qt, PyTorch, torchvision, torchaudio, and SAM2;
- excludes GNU Readline from the supported runtime;
- carries package and native-runtime license records.
Provenance
The image contains:
/opt/grime3/BUILD_INFO.json
/opt/grime3/THIRD_PARTY_LICENSES/
/opt/grime3/NATIVE_RUNTIME_LICENSES/
/opt/grime3/NATIVE_RUNTIME_MANIFEST.json
Troubleshooting
Port 8000 is already in use
docker run --rm \
-p 8080:8000 \
grime3:0.1.0-rc9Open http://127.0.0.1:8080/.
Results cannot be written
Verify the host results directory exists and is writable. On Linux, use the host UID/GID or correct directory ownership/permissions.
Images cannot be found
Inside the container use container paths such as
/data/images, not the original host pathname.
Docker Desktop cannot mount a directory
Verify that the host path is available to Docker Desktop and file-sharing permissions permit access.
Container exits immediately
docker ps -a
docker logs <container-name-or-id>A completed command-line measurement exits normally after writing outputs.
Future Docker work
Future SDF-capable CPU/GPU Docker images, native ARM64 images, and multi-architecture publishing remain post-RC9 roadmap work.