open-cmis-tck/docs/LOCAL-RUNBOOK.md

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:

/home/worsch/guide-board
/home/worsch/open-cmis-tck

The guide-board core is used from source:

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:

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:

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

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:

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

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:

cd /home/worsch/open-cmis-tck
source .local/toolchains/env.sh

Resolve The TCK Runtime

cd /home/worsch/open-cmis-tck
source .local/toolchains/env.sh
PYTHONPATH=src python3 scripts/bootstrap_opencmis_tck.py --resolve

This resolves:

org.apache.chemistry.opencmis:chemistry-opencmis-test-tck:1.1.0

into the local Maven cache and writes:

.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:

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:

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:

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:

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:

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:

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:

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:

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

export CMIS_TCK_USER='cmis-user'
export CMIS_TCK_PASSWORD='local-secret'

Use a target profile with:

"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.