generated from coulomb/repo-seed
148 lines
4.1 KiB
Markdown
148 lines
4.1 KiB
Markdown
# 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`.
|