guide-board/docs/CONTAINER.md

Guide Board Container Baseline

Status: draft Created: 2026-05-07

Purpose

The first container image packages the local CLI contracts, schemas, bundled profiles, and incubating extensions. It is not a certification appliance and it does not include restricted third-party harnesses unless a downstream image or runtime mount provides them.

Image Roles

Use guide-board-core for dependency-light checks:

• extension discovery,
• profile validation,
• run planning,
• sample/no-op assessments,
• extensions whose runners use only the core Python runtime.

Use extension-specific images when a harness needs additional dependencies such as Java, Maven, browser engines, vendor tools, or licensed test suites. Those images should extend guide-board-core or mount the core as a package, but they must keep restricted assets outside the public core image.

Build

podman build -t guide-board-core:local -f Containerfile .

Docker can be used with the same arguments.

Local Baseline Run

mkdir -p runs
podman run --rm \
  -v "$PWD/runs:/runs" \
  guide-board-core:local \
  --root /opt/guide-board run \
  --target /opt/guide-board/profiles/targets/sample-repository.json \
  --assessment /opt/guide-board/profiles/assessments/sample-noop.json \
  --output-dir /runs/sample-noop

The run output remains on the host under runs/sample-noop.

Smoke Check

Run the reproducible smoke check from the repository root:

scripts/container_smoke.sh

The script:

• detects podman or docker,
• builds guide-board-core:smoke,
• mounts a host output directory at /runs,
• runs the bundled sample assessment,
• verifies that the expected run artifacts, report fragments, submission manifest, and generic export manifest are present on the host.

Override the runtime, image name, or output directory when needed:

CONTAINER_RUNTIME=docker \
GUIDE_BOARD_SMOKE_IMAGE=guide-board-core:local \
GUIDE_BOARD_SMOKE_RUNS_DIR=/tmp/guide-board-container-smoke \
scripts/container_smoke.sh

The smoke check uses only bundled sample profiles and the dependency-light core image. Restricted harness material and extension-specific runtime dependencies must stay in extension-specific images or explicit mounts.

External Profiles

Mount project-specific profiles read-only:

podman run --rm \
  -v "$PWD/profiles:/profiles:ro" \
  -v "$PWD/runs:/runs" \
  guide-board-core:local \
  --root /opt/guide-board run \
  --target /profiles/targets/example.json \
  --assessment /profiles/assessments/example.json \
  --output-dir /runs/example

External Extensions

Mount extension repositories separately and pass them with --extension-dir:

podman run --rm \
  -v "$PWD/../open-cmis-tck:/extensions/open-cmis-tck:ro" \
  -v "$PWD/runs:/runs" \
  guide-board-core:local \
  --root /opt/guide-board \
  --extension-dir /extensions/open-cmis-tck \
  extensions list

The external extension root must contain extension.json. The core records external extension paths in the run plan snapshot so evidence remains traceable.

Credentials And Restricted Assets

Credentials and licensed harness material should be mounted explicitly:

/credentials   runtime secrets or references
/assets        licensed or locally provided harness assets
/profiles      target and assessment profiles
/runs          generated outputs

Assessment profiles should declare offline/network expectations. Extension runners should fail as blocked or infrastructure_error when required mounted assets are absent.

CMIS Extension Path

The core image includes the incubating open-cmis-tck extension metadata, preflight runner, command wrapper, and mappings. It does not include the final Apache Chemistry TCK dependency graph. A future CMIS image should add Java/Maven and document how the OpenCMIS TCK artifacts are resolved or mounted.

Service Mode

The current core image can run the local service API through the same entrypoint:

podman run --rm -p 8080:8080 \
  -v "$PWD/runs:/runs" \
  guide-board-core:local \
  --root /opt/guide-board serve --host 0.0.0.0 --port 8080

The service layer adds in-memory job tracking and HTTP transport. Execution semantics remain the CLI/core semantics documented in docs/LOCAL-SERVICE-API.md. Mounted run directories remain discoverable through the retained-run endpoints, for example:

curl -sf "http://127.0.0.1:8080/retained-runs?runs_dir=/runs" | python3 -m json.tool