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:

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:

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-rc9

Open:

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-rc9

Using 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 --help

Measure 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/results

Measure 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/results

Measure 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/results

Docker Compose

Create persistent host directories:

mkdir -p data/config data/images data/results data/database

For 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 --build

When 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 --build

Then 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 -d

Stopping

For an interactive container, Ctrl+C stops the browser process.

For Compose:

docker compose down

Removing a container does not remove bind-mounted host data.

Container security baseline

The RC9 image:

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-rc9

Open 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.