From d61bc078fdd24d75cbdeff42865e97fe6f137b26 Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 7 May 2026 20:27:03 +0200 Subject: [PATCH] State hub update and Containerization --- .dockerignore | 18 ++++ Containerfile | 23 +++++ README.md | 4 + docs/ARCHITECTURE-BLUEPRINT.md | 4 + docs/CONTAINER.md | 98 +++++++++++++++++++ .../GUIDE-BOARD-WP-0001-bootstrapping.md | 12 ++- 6 files changed, 158 insertions(+), 1 deletion(-) create mode 100644 .dockerignore create mode 100644 Containerfile create mode 100644 docs/CONTAINER.md diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..e36c94f --- /dev/null +++ b/.dockerignore @@ -0,0 +1,18 @@ +.git +.pytest_cache +.ruff_cache +.mypy_cache +__pycache__ +*.pyc +*.pyo +*.pyd +.venv +venv +env +build +dist +*.egg-info +runs +reports +downloads +tmp diff --git a/Containerfile b/Containerfile new file mode 100644 index 0000000..3bc351a --- /dev/null +++ b/Containerfile @@ -0,0 +1,23 @@ +FROM python:3.12-slim + +LABEL org.opencontainers.image.title="guide-board-core" +LABEL org.opencontainers.image.description="Guide Board certification and compliance preparation CLI core." + +ENV PYTHONUNBUFFERED=1 + +WORKDIR /opt/guide-board + +COPY pyproject.toml README.md LICENSE ./ +COPY src ./src +COPY docs ./docs +COPY extensions ./extensions +COPY profiles ./profiles +COPY INTENT.md ./ + +RUN python -m pip install --no-cache-dir --upgrade pip \ + && python -m pip install --no-cache-dir . + +VOLUME ["/runs", "/profiles", "/credentials", "/assets"] + +ENTRYPOINT ["guide-board"] +CMD ["--help"] diff --git a/README.md b/README.md index 1db4b3f..c8f353f 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,9 @@ PYTHONPATH=src python3 -m guide_board runs gate PYTHONPATH=src python3 -m unittest discover -s tests ``` +The same CLI contracts are packaged by the container baseline. See +[docs/CONTAINER.md](docs/CONTAINER.md). + The `sample-noop` extension exercises the guide-board contracts without invoking an external harness. `open-cmis-tck` is the first real seed extension. @@ -35,6 +38,7 @@ See: - [INTENT.md](INTENT.md) - [docs/ARCHITECTURE-BLUEPRINT.md](docs/ARCHITECTURE-BLUEPRINT.md) +- [docs/CONTAINER.md](docs/CONTAINER.md) - [docs/EXTENSION-SDK.md](docs/EXTENSION-SDK.md) - [extensions/CANDIDATES.md](extensions/CANDIDATES.md) - [extensions/open-cmis-tck/INTENT.md](extensions/open-cmis-tck/INTENT.md) diff --git a/docs/ARCHITECTURE-BLUEPRINT.md b/docs/ARCHITECTURE-BLUEPRINT.md index cb8b209..0817caf 100644 --- a/docs/ARCHITECTURE-BLUEPRINT.md +++ b/docs/ARCHITECTURE-BLUEPRINT.md @@ -726,6 +726,10 @@ Recommended container model: - Restricted tools are mounted from licensed local paths. - Network access is declared per extension and per assessment profile. +The baseline `Containerfile` packages the local CLI, schemas, sample profiles, +and incubating extensions. See `docs/CONTAINER.md` for mount contracts and the +extension-specific image path. + Optional service model: - service lists extensions and profiles, diff --git a/docs/CONTAINER.md b/docs/CONTAINER.md new file mode 100644 index 0000000..d9851ca --- /dev/null +++ b/docs/CONTAINER.md @@ -0,0 +1,98 @@ +# 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`. + +## 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 +``` + +## 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 Path + +A service image should call the same CLI contracts used here: + +- validate profiles, +- build run plans, +- execute runs, +- read run metadata, evidence, reports, retention summaries, trends, and gates. + +The service layer may add job tracking and HTTP transport, but it should not +create separate execution semantics. diff --git a/workplans/GUIDE-BOARD-WP-0001-bootstrapping.md b/workplans/GUIDE-BOARD-WP-0001-bootstrapping.md index e6f88fd..f4c0823 100644 --- a/workplans/GUIDE-BOARD-WP-0001-bootstrapping.md +++ b/workplans/GUIDE-BOARD-WP-0001-bootstrapping.md @@ -248,7 +248,7 @@ Progress: ```task id: GUIDE-BOARD-WP-0001-T008 -status: todo +status: done priority: medium state_hub_task_id: "21e5c1e0-b02e-408d-a657-1771750e9b30" ``` @@ -261,6 +261,16 @@ Acceptance: - Restricted or license-gated harnesses are represented as mounted external assets, not redistributed guide-board content. +Progress: + +- Added a dependency-light `guide-board-core` `Containerfile`. +- Added `.dockerignore` to keep local run outputs and development artifacts out + of the image build context. +- Added `docs/CONTAINER.md` with mount contracts for profiles, credentials, + runs, and restricted harness assets. +- Documented the extension-specific image path for CMIS Java/Maven/OpenCMIS TCK + dependencies. + ## D1.10 - Optional Local Service API ```task