# GRIME3 0.1.0 RC8.4 — Docker Quick Start and Deployment Guide

The RC8.4 Docker/OCI image provides the same deterministic GRIME3 browser and
command-line measurement implementation as the standalone and Conda
distributions.

The deterministic RC8.4 image does not contain the future SDF model, PyTorch,
SAM2, or Qt.

## Platform scope

The native RC8.4 validation target is:

```text
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-RC8.4 roadmap work.

The RC8.4 image is a Linux container image, not a Windows-container image.

## Persistent data layout

The container uses:

```text
/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 RC8.4 source

```bash
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-rc8.4-${GRIME3_GIT_SHORT_COMMIT}"
GRIME3_BUILD_UTC="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

test "$GRIME3_GIT_TAG" = "grime3-0.1.0-rc8.4"
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" \
  --tag grime3:0.1.0-rc8.4 \
  .
```

Official release images must be built from the immutable RC8.4 source tag.

## Browser operation

```bash
docker run --rm \
  -p 8000:8000 \
  grime3:0.1.0-rc8.4
```

Open:

```text
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:

```bash
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-rc8.4
```

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

```bash
docker run --rm \
  grime3:0.1.0-rc8.4 \
  measure --help
```

## Measure one image

```bash
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-rc8.4 \
  measure image \
    --image /data/images/image001.jpg \
    --site-config /data/config/site_config.json \
    --output-dir /data/results
```

## Measure one folder

```bash
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-rc8.4 \
  measure folder \
    --images /data/images \
    --site-config /data/config/site_config.json \
    --output-dir /data/results
```

## Measure a folder of folders

```bash
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-rc8.4 \
  measure folders \
    --images-root /data/images \
    --site-config /data/config/site_config.json \
    --output-dir /data/results
```

## Docker Compose

Create persistent host directories:

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

For an official RC8.4 build from the immutable tag, export the
complete release identity before invoking Compose:

```bash
test "$(git describe --tags --exact-match HEAD)" = "grime3-0.1.0-rc8.4"
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-rc8.4"
export GRIME3_BUILD_ID="0.1.0-rc8.4-${GRIME3_GIT_SHORT_COMMIT}"
export GRIME3_BUILD_UTC="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export GRIME3_IMAGE="grime3:0.1.0-rc8.4"
```

On Linux, also use the host UID and GID:

```bash
export GRIME3_UID="$(id -u)"
export GRIME3_GID="$(id -g)"
```

Start:

```bash
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 RC8.4 release image.

A different host port can be selected:

```bash
export GRIME3_PORT=8080
docker compose up --build
```

Then open:

```text
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:

```text
/home/user/site/site_config.json
```

can appear in the container as:

```text
/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:

```bash
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:

```bash
docker compose down
```

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

## Container security baseline

The RC8.4 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:

```text
/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

```bash
docker run --rm \
  -p 8080:8000 \
  grime3:0.1.0-rc8.4
```

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

```bash
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-RC8.4 roadmap work.