generated from coulomb/repo-seed
280 lines
7.6 KiB
Markdown
280 lines
7.6 KiB
Markdown
# Local OpenCMIS TCK Runbook
|
|
|
|
Status: draft
|
|
Created: 2026-05-08
|
|
|
|
## Purpose
|
|
|
|
This runbook is the workstation path from a clean checkout to the first local
|
|
OpenCMIS TCK run through guide-board.
|
|
|
|
The local path has two stages:
|
|
|
|
1. Prove the guide-board/OpenCMIS adapter wiring with the dry-run profile.
|
|
2. Install Java/Maven, resolve the OpenCMIS TCK runtime, and run the real
|
|
ConsoleRunner profile.
|
|
|
|
## Prerequisites
|
|
|
|
The extension and guide-board repositories should be siblings:
|
|
|
|
```text
|
|
/home/worsch/guide-board
|
|
/home/worsch/open-cmis-tck
|
|
```
|
|
|
|
The guide-board core is used from source:
|
|
|
|
```sh
|
|
cd /home/worsch/guide-board
|
|
PYTHONPATH=src python3 -m guide_board --extension-dir ../open-cmis-tck extensions validate
|
|
```
|
|
|
|
## Dry-Run Adapter Check
|
|
|
|
The dry-run profile verifies profile resolution, CMIS preflight, wrapper
|
|
invocation, ConsoleRunner adapter argument expansion, session file generation,
|
|
artifact references, mapping, and report creation. It does not require Java or
|
|
Maven.
|
|
|
|
Start or point to a CMIS Browser Binding endpoint, then run:
|
|
|
|
```sh
|
|
cd /home/worsch/guide-board
|
|
PYTHONPATH=src python3 -m guide_board \
|
|
--extension-dir ../open-cmis-tck \
|
|
run \
|
|
--target ../open-cmis-tck/profiles/targets/kontextual-cmis-compat.json \
|
|
--assessment ../open-cmis-tck/profiles/assessments/cmis-browser-local-dry-run.json \
|
|
--output-dir /tmp/open-cmis-tck-dry-run
|
|
```
|
|
|
|
Expected dry-run artifacts:
|
|
|
|
```text
|
|
/tmp/open-cmis-tck-dry-run/reports/report.md
|
|
/tmp/open-cmis-tck-dry-run/reports/assessment-package.json
|
|
/tmp/open-cmis-tck-dry-run/normalized/evidence.json
|
|
/tmp/open-cmis-tck-dry-run/artifacts/open-cmis-tck/tck/repository-type/session.properties.redacted
|
|
/tmp/open-cmis-tck-dry-run/artifacts/open-cmis-tck/tck/repository-type/groups.txt
|
|
```
|
|
|
|
If preflight fails, fix the target profile or endpoint before continuing.
|
|
|
|
Generate a maturity scorecard from the dry-run output:
|
|
|
|
```sh
|
|
cd /home/worsch/open-cmis-tck
|
|
PYTHONPATH=src python3 scripts/cmis_scorecard.py \
|
|
--run-dir /tmp/open-cmis-tck-dry-run
|
|
```
|
|
|
|
## Install Java And Maven
|
|
|
|
The current WSL environment does not expose system `java` and `mvn` on `PATH`.
|
|
Either install them as system packages:
|
|
|
|
```sh
|
|
sudo apt-get update
|
|
sudo apt-get install -y openjdk-17-jdk maven
|
|
```
|
|
|
|
Use a managed local Java/Maven installation instead if preferred. The bootstrap
|
|
only requires `java` and `mvn` on `PATH`.
|
|
|
|
Or use the repo-local toolchain under `.local/`:
|
|
|
|
```sh
|
|
cd /home/worsch/open-cmis-tck
|
|
python3 scripts/install_local_toolchain.py
|
|
source .local/toolchains/env.sh
|
|
PYTHONPATH=src python3 scripts/bootstrap_opencmis_tck.py --resolve
|
|
```
|
|
|
|
The local installer downloads a Linux x64 Temurin JDK 17 archive and Apache
|
|
Maven 3.9.11, extracts them under `.local/toolchains`, verifies Maven's SHA-512
|
|
checksum, writes `.local/toolchains/env.sh`, and leaves the downloaded binaries
|
|
outside version control.
|
|
|
|
This workspace has already been bootstrapped with the repo-local path. In a new
|
|
shell, source the environment file before running live TCK commands:
|
|
|
|
```sh
|
|
cd /home/worsch/open-cmis-tck
|
|
source .local/toolchains/env.sh
|
|
```
|
|
|
|
## Resolve The TCK Runtime
|
|
|
|
```sh
|
|
cd /home/worsch/open-cmis-tck
|
|
source .local/toolchains/env.sh
|
|
PYTHONPATH=src python3 scripts/bootstrap_opencmis_tck.py --resolve
|
|
```
|
|
|
|
This resolves:
|
|
|
|
```text
|
|
org.apache.chemistry.opencmis:chemistry-opencmis-test-tck:1.1.0
|
|
```
|
|
|
|
into the local Maven cache and writes:
|
|
|
|
```text
|
|
.local/opencmis-tck/runtime-summary.json
|
|
```
|
|
|
|
The `.local/` directory is ignored and must not be committed.
|
|
|
|
## Real TCK Run
|
|
|
|
For a controlled local pilot target, start the Apache Chemistry OpenCMIS
|
|
in-memory server:
|
|
|
|
```sh
|
|
cd /home/worsch/open-cmis-tck
|
|
source .local/toolchains/env.sh
|
|
export OPENCMIS_INMEMORY_USER=dummyuser
|
|
export OPENCMIS_INMEMORY_PASSWORD=dummysecret
|
|
python3 scripts/opencmis_inmemory_server.py start
|
|
```
|
|
|
|
Then run the in-memory pilot profile:
|
|
|
|
```sh
|
|
cd /home/worsch/guide-board
|
|
source /home/worsch/open-cmis-tck/.local/toolchains/env.sh
|
|
export OPENCMIS_INMEMORY_USER=dummyuser
|
|
export OPENCMIS_INMEMORY_PASSWORD=dummysecret
|
|
PYTHONPATH=src python3 -m guide_board \
|
|
--extension-dir ../open-cmis-tck \
|
|
run \
|
|
--target ../open-cmis-tck/profiles/targets/opencmis-inmemory-local.json \
|
|
--assessment ../open-cmis-tck/profiles/assessments/cmis-browser-inmemory-pilot.json \
|
|
--output-dir ../open-cmis-tck/.local/runs/opencmis-inmemory-pilot
|
|
```
|
|
|
|
Stop the local pilot server after the run:
|
|
|
|
```sh
|
|
cd /home/worsch/open-cmis-tck
|
|
python3 scripts/opencmis_inmemory_server.py stop
|
|
```
|
|
|
|
The in-memory target is a test infrastructure pilot only. It proves the local
|
|
TCK path before running against the actual CMIS-capable system.
|
|
|
|
After bootstrap reports `ready`, run the baseline assessment:
|
|
|
|
```sh
|
|
cd /home/worsch/guide-board
|
|
source /home/worsch/open-cmis-tck/.local/toolchains/env.sh
|
|
PYTHONPATH=src python3 -m guide_board \
|
|
--extension-dir ../open-cmis-tck \
|
|
run \
|
|
--target ../open-cmis-tck/profiles/targets/kontextual-cmis-compat.json \
|
|
--assessment ../open-cmis-tck/profiles/assessments/cmis-browser-baseline.json \
|
|
--output-dir /tmp/open-cmis-tck-live
|
|
```
|
|
|
|
The baseline currently selects:
|
|
|
|
- `repository-type`
|
|
- `object-content`
|
|
|
|
Expand selected check groups only after the repository/type run produces useful
|
|
output.
|
|
|
|
Then generate the maturity scorecard:
|
|
|
|
```sh
|
|
cd /home/worsch/open-cmis-tck
|
|
PYTHONPATH=src python3 scripts/cmis_scorecard.py \
|
|
--run-dir /tmp/open-cmis-tck-live
|
|
```
|
|
|
|
Generate the log review after the scorecard:
|
|
|
|
```sh
|
|
PYTHONPATH=src python3 scripts/opencmis_log_review.py \
|
|
--run-dir /tmp/open-cmis-tck-live
|
|
```
|
|
|
|
The review classifies warnings, hard errors, stderr, skipped cases, and closed
|
|
warnings when a previous run is supplied. The default warning policy accepts the
|
|
OpenCMIS HTTP transport warning only for local/test loopback profiles.
|
|
|
|
For important product assessments, archive the run before `/tmp` cleanup:
|
|
|
|
```sh
|
|
PYTHONPATH=src python3 scripts/archive_assessment_run.py \
|
|
--run-dir /tmp/open-cmis-tck-live \
|
|
--archive-root .local/runs/archive
|
|
```
|
|
|
|
The archive writes `.local/runs/archive/<target>/<run-id>/archive-manifest.json`
|
|
with SHA-256 hashes for every copied file.
|
|
|
|
Review the real TCK evidence before expanding the scope:
|
|
|
|
```text
|
|
/tmp/open-cmis-tck-live/normalized/evidence.json
|
|
/tmp/open-cmis-tck-live/artifacts/open-cmis-tck/tck/<check-group>/console-runner-stdout.txt
|
|
/tmp/open-cmis-tck-live/artifacts/open-cmis-tck/tck/<check-group>/normalized-runner-result.json
|
|
/tmp/open-cmis-tck-live/reports/opencmis-log-review.md
|
|
```
|
|
|
|
The normalizer preserves native OpenCMIS statuses (`OK`, `WARNING`, `FAILURE`,
|
|
`SKIPPED`, `UNEXPECTED_EXCEPTION`, and `INFO`) as case-level facts while mapping
|
|
the overall check group to guide-board's result vocabulary.
|
|
|
|
## Authenticated Targets
|
|
|
|
For environment credentials:
|
|
|
|
```sh
|
|
export CMIS_TCK_USER='cmis-user'
|
|
export CMIS_TCK_PASSWORD='local-secret'
|
|
```
|
|
|
|
Use a target profile with:
|
|
|
|
```json
|
|
"credentials_ref": "env:CMIS_TCK_USER,CMIS_TCK_PASSWORD"
|
|
```
|
|
|
|
The adapter uses a private session file during execution and retains only a
|
|
redacted session file as an artifact.
|
|
|
|
## Troubleshooting
|
|
|
|
`java is not available on PATH`:
|
|
|
|
Install a JDK or expose an existing JDK to WSL.
|
|
|
|
`maven is not available on PATH`:
|
|
|
|
Install Maven or expose an existing Maven executable to WSL.
|
|
|
|
Maven dependency resolution fails:
|
|
|
|
Check network access to Maven Central or rerun with a populated Maven cache.
|
|
|
|
Preflight returns `infrastructure_error`:
|
|
|
|
Check endpoint URL, server process, firewall, credentials, and timeout.
|
|
|
|
Repository ID mismatch:
|
|
|
|
Use the repository IDs reported by preflight and update
|
|
`runtime_policy.opencmis_tck.repository_id`.
|
|
|
|
TCK command times out:
|
|
|
|
Increase `runtime_policy.timeout_seconds` or narrow selected check groups.
|
|
|
|
Formal boundary:
|
|
|
|
These runs generate preparation evidence only. They do not issue CMIS
|
|
certification.
|