# 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

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

Docker can be used with the same arguments.

## Local Baseline Run

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

```sh
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 are present on the host.

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

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

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

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

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

```sh
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`.