From 411ac963bdb606b19143e02a68d295b830cca334 Mon Sep 17 00:00:00 2001 From: Mathieu Benoit Date: Tue, 17 Nov 2026 23:36:15 -0500 Subject: [PATCH 1/2] Add a Docker Sandboxes content kit as a second way to run the lab Package labspace/ and project/ as a Sandbox Kit that runs with the Labspace kit from mathieu-benoit/labsbxes (sbx run shell --kit ... --kit ...). The kit also ships the Docker Scout CLI plugin (missing from the sbx shell agent), publishes the app port 5001, and allows the egress the lab needs (Docker login, dhi.io, Scout, ghcr.io, PyPI). A workflow publishes it to ghcr.io///kit; the README documents the option. Co-Authored-By: Claude Opus 5.5 --- .dockerignore | 7 ++ .github/workflows/publish-kit.yaml | 159 +++++++++++++++++++++++++++++ README.md | 36 +++++++ dhi-launch.dockerfile | 15 +++ dhi-launch.yaml | 66 ++++++++++++ 5 files changed, 283 insertions(+) create mode 100644 .dockerignore create mode 100644 .github/workflows/publish-kit.yaml create mode 100644 dhi-launch.dockerfile create mode 100644 dhi-launch.yaml diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..f777e06 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,7 @@ +# Keep the build context of the sandbox kit (dhi-launch.yaml) to the lab's content. +# The dinner image is built from project/, which has its own context. +* +!labspace +!project +!dhi-launch.yaml +!dhi-launch.dockerfile diff --git a/.github/workflows/publish-kit.yaml b/.github/workflows/publish-kit.yaml new file mode 100644 index 0000000..5221309 --- /dev/null +++ b/.github/workflows/publish-kit.yaml @@ -0,0 +1,159 @@ +name: publish-kit + +# Builds this lab's Docker Sandboxes content kit (dhi-launch.yaml) and publishes +# it to ghcr.io///kit. It runs with the Labspace kit from +# https://github.com/mathieu-benoit/labsbxes (see the README). +# +# pull request nothing pushed: built to a local OCI layout, checked with kit-tck +# push of a v* tag : and :latest (an existing version is skipped) +# manual run on main :edge and :sha- (elsewhere: build only) + +on: + pull_request: + paths: + - "labspace/**" + - "project/**" + - "dhi-launch.yaml" + - "dhi-launch.dockerfile" + - ".dockerignore" + - ".github/workflows/publish-kit.yaml" + push: + tags: ["v*"] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: publish-kit-${{ github.ref }} + cancel-in-progress: false + +env: + REGISTRY: ghcr.io + DESCRIPTOR: dhi-launch.yaml + # kit-tck, the Sandbox Kit specification's conformance checker. Pinned, and + # verified against the release's checksums.txt before it runs. + KIT_TCK_VERSION: 3.0.0-m.12 + +jobs: + kit: + runs-on: ubuntu-latest + permissions: + contents: read + packages: write # push to ghcr.io///kit + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + + - name: Resolve image name and tags + id: meta + env: + EVENT: ${{ github.event_name }} + REF: ${{ github.ref }} + run: | + set -euo pipefail + + # The descriptor is the version authority (top-level `version:` only). + version="$(sed -n 's/^version:[[:space:]]*"\{0,1\}\([^"[:space:]#]*\).*/\1/p' "$DESCRIPTOR" | head -n 1)" + if [ -z "$version" ]; then + echo "::error file=$DESCRIPTOR::no top-level version: found" + exit 1 + fi + + image="${REGISTRY}/${GITHUB_REPOSITORY,,}/kit" + publish=false + tags="${image}:ci-build" + primary="${image}:ci-build" + if [ "$EVENT" != "pull_request" ]; then + if [[ "$REF" == refs/tags/v* ]]; then + if [ "${REF#refs/tags/v}" != "$version" ]; then + echo "::error::Release tag ${REF#refs/tags/} does not match version ${version} in ${DESCRIPTOR}." + exit 1 + fi + publish=true + tags="${image}:${version},${image}:latest" + primary="${image}:${version}" + elif [ "$REF" = "refs/heads/main" ]; then + publish=true + tags="${image}:edge,${image}:sha-${GITHUB_SHA::7}" + primary="${image}:edge" + fi + fi + + { + echo "version=$version" + echo "publish=$publish" + echo "tags=$tags" + echo "primary=$primary" + } >> "$GITHUB_OUTPUT" + + - uses: docker/setup-qemu-action@v4 + with: + platforms: arm64 + + # The docker-container driver keeps the manifest annotations that carry + # the kit descriptor. + - uses: docker/setup-buildx-action@v4 + + - name: Log in to ghcr.io + if: steps.meta.outputs.publish == 'true' + uses: docker/login-action@v4 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Skip a version that is already published + id: exists + if: steps.meta.outputs.publish == 'true' && startsWith(github.ref, 'refs/tags/v') + env: + PRIMARY: ${{ steps.meta.outputs.primary }} + run: | + if docker buildx imagetools inspect "$PRIMARY" > /dev/null 2>&1; then + echo "skip=true" >> "$GITHUB_OUTPUT" + echo "::notice::$PRIMARY already exists; not republishing. Bump version: in $DESCRIPTOR to release a new one." + else + echo "skip=false" >> "$GITHUB_OUTPUT" + fi + + # The `# syntax=docker/sandbox-kit:3` line of the descriptor makes BuildKit + # run the Kit frontend, which validates the descriptor and attaches it. + - name: Build${{ steps.meta.outputs.publish == 'true' && ' and push' || '' }} + if: steps.exists.outputs.skip != 'true' + uses: docker/build-push-action@v7 + with: + context: . + file: ${{ env.DESCRIPTOR }} + platforms: linux/amd64,linux/arm64 + provenance: mode=min + sbom: false + push: ${{ steps.meta.outputs.publish == 'true' }} + tags: ${{ steps.meta.outputs.tags }} + outputs: ${{ steps.meta.outputs.publish != 'true' && format('type=oci,dest={0}/kit-layout,tar=false', runner.temp) || '' }} + + - name: Install kit-tck + if: steps.exists.outputs.skip != 'true' + run: | + set -euo pipefail + base="https://github.com/docker/sandbox-kit-spec/releases/download/v${KIT_TCK_VERSION}" + archive="kit-tck_${KIT_TCK_VERSION}_linux_amd64.tar.gz" + mkdir -p "$RUNNER_TEMP/kit-tck" + cd "$RUNNER_TEMP/kit-tck" + curl -fsSL -O "$base/$archive" + curl -fsSL -O "$base/checksums.txt" + grep " ${archive}\$" checksums.txt | sha256sum -c - + tar -xzf "$archive" + echo "$RUNNER_TEMP/kit-tck" >> "$GITHUB_PATH" + + - name: Validate the kit with kit-tck + if: steps.exists.outputs.skip != 'true' + env: + PUBLISH: ${{ steps.meta.outputs.publish }} + PRIMARY: ${{ steps.meta.outputs.primary }} + run: | + if [ "$PUBLISH" = "true" ]; then + kit-tck validate "$PRIMARY" + else + kit-tck validate --layout "$RUNNER_TEMP/kit-layout" ci-build + fi diff --git a/README.md b/README.md index 88d2372..d4fa194 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,42 @@ docker compose -f oci://ghcr.io/mathieu-benoit/labspace-dhi-launch:latest up And then open the labspace in your web browser: http://localhost:3030. +## Run this Labspace in a Docker Sandbox (option 2) + +You can also run this lab with [`sbx`](https://docs.docker.com/ai/sandboxes/) instead of Docker Compose. Everything (instructions, VS Code, and a private Docker engine for the lab) runs in a single microVM, and `sbx rm` removes everything the lab created. This option uses two [Sandbox Kits](https://github.com/docker/sandbox-kit-spec): + +- the **Labspace kit** from [mathieu-benoit/labsbxes](https://github.com/mathieu-benoit/labsbxes), which runs the interface and the IDE; +- the **content kit** of this repository ([dhi-launch.yaml](dhi-launch.yaml) and [dhi-launch.dockerfile](dhi-launch.dockerfile)), which carries `labspace/` and `project/`, the Docker Scout CLI plugin, the app port (`5001`) and the network access the lab needs (Docker login, `dhi.io`, Docker Scout, `ghcr.io`, PyPI). + +By default `sbx` only installs kits from `docker.io/` and `dhi.io/`, so first allow the GHCR namespace: + +```bash +sbx settings set kit.allowedSources '["docker.io/","dhi.io/","ghcr.io/mathieu-benoit/"]' +``` + +Then, from an empty folder (`sbx run` mounts the current folder as the workspace): + +```bash +sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.4 --kit ghcr.io/mathieu-benoit/dhi-launch/kit:0.1.0 -p 8085:8085 -p 5001:5001 --name dhi-launch -d +``` + +Then open the interface on the host port that `sbx ports dhi-launch` lists for sandbox port `3030` (add `-p 3030:3030` to the command to always use http://localhost:3030). + +- `-p 8085:8085` is required: the interface embeds the IDE at `http://localhost:8085`. +- `-p 5001:5001` is for the lab's "App" tab (`http://localhost:5001`). +- The `docker login` commands of the lab run inside the sandbox; they store credentials in the sandbox, not on your machine. +- Stop the lab with `sbx stop dhi-launch`, restart it with `sbx run --name dhi-launch -d`, delete it with `sbx rm dhi-launch`. + +From a clone of this repository, you can run the local version of the content kit instead of the published one: + +```bash +sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.4 --kit . -p 8085:8085 -p 5001:5001 --name dhi-launch -d +``` + +Run from the clone, the workspace's own `labspace/` wins over the kit's copy, and `project/` is the folder on your machine, so your edits land in the clone. Add `--kit-arg devMode=true` to see markdown edits live. + +The content kit is published by [.github/workflows/publish-kit.yaml](.github/workflows/publish-kit.yaml): push a `v` tag matching `version:` in [dhi-launch.yaml](dhi-launch.yaml) (for example `git tag v0.1.0 && git push origin v0.1.0`) to publish `ghcr.io/mathieu-benoit/dhi-launch/kit:`, or run the workflow manually on `main` to publish `:edge`. New GHCR packages can start out private: make the package public after the first publish. + ## Contribute to this Labspace After you cloned this GitHub repository, you can run this Labspace locally by running these commands: diff --git a/dhi-launch.dockerfile b/dhi-launch.dockerfile new file mode 100644 index 0000000..7725710 --- /dev/null +++ b/dhi-launch.dockerfile @@ -0,0 +1,15 @@ +# syntax=docker/dockerfile:1.7 +# +# Content overlay: the lab's two folders, landing where the Labspace kit looks +# for them, plus the Docker Scout CLI plugin the lab uses (`docker scout +# compare`), which the sandbox's `shell` agent doesn't ship. No base image: +# the result is `FROM scratch`, so it composes onto whatever the workload is. + +# The plugin is a single static binary, published for linux/amd64 and +# linux/arm64. Bump the tag to update it. +FROM docker/scout-cli:1.29.0 AS scout + +FROM scratch +COPY --from=scout --chmod=755 /docker-scout /usr/local/lib/docker/cli-plugins/docker-scout +COPY labspace /opt/labspace/content/labspace +COPY project /opt/labspace/content/project diff --git a/dhi-launch.yaml b/dhi-launch.yaml new file mode 100644 index 0000000..876276c --- /dev/null +++ b/dhi-launch.yaml @@ -0,0 +1,66 @@ +# syntax=docker/sandbox-kit:3 +# +# The "Hardened Images Launch" lab as a content kit for Docker Sandboxes. It +# carries the lab's labspace/ and project/ folders (and the network access the +# lab needs); everything that runs them comes from the Labspace kit published +# by https://github.com/mathieu-benoit/labsbxes. +# +# sbx run shell \ +# --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.4 \ +# --kit ./ \ +# -p 8085:8085 -p 5001:5001 --name dhi-launch +schemaVersion: "3" +kind: mixin + +displayName: Hardened Images Launch (content) +description: >- + The "Hardened Images Launch" lab: pull and run Docker Hardened Images, do a + multi-stage build with them, scan with Docker Scout and use them with Compose, + to be run by the Labspace kit. + +version: "0.1.0" + +# Becomes the org.opencontainers.image.source annotation, which is what links +# a published GHCR package to this repository. +sourceUrl: https://github.com/mathieu-benoit/dhi-launch + +# The Labspace kit provides `labspace`. Composing this kit without it fails at +# resolution instead of producing a sandbox with files and nothing to show them. +requires: ["labspace >= 0.1.0"] + +# One lab per sandbox: a second content kit provides the same name, and the +# runtime refuses the composition. +provides: ["labspace-content@0.1.0"] + +capabilities: + # The lab runs the dinner app with `docker compose up` (web: 5001:5000) and + # opens it in the "App" tab at http://localhost:5001. sbx picks the host port + # (sbx ports ); -p 5001:5001 pins it for the tab. + - type: com.docker.sandbox/port@1 + config: + name: dinner-app + container: 5001 + transport: tcp + + # The Labspace kit only allows Docker Hub pulls and Open VSX. This lab also + # logs in to Docker, pulls hardened images, the pre-built dinner:initial image + # from GHCR, installs Python packages during `docker build`, and calls Docker + # Scout. + - type: com.docker.sandbox/network-policy@1 + config: + runtime: + allow: + # `docker login` (device code flow) and Docker Hub APIs. + - login.docker.com + - hub.docker.com + - index.docker.io + # Docker Hardened Images registry (when the registry prefix is dhi.io/). + - dhi.io + # Docker Scout (`docker scout compare`). + - api.scout.docker.com + # The pre-built ghcr.io/mathieu-benoit/dinner:initial image. + - ghcr.io + - pkg-containers.githubusercontent.com + # `pip install -r requirements.txt` in the Dockerfile. + - pypi.org + - files.pythonhosted.org From 53885752a5a325a974d38642521235c92699cb8e Mon Sep 17 00:00:00 2001 From: Mathieu Benoit Date: Tue, 17 Nov 2026 23:43:24 -0500 Subject: [PATCH 2/2] Publish the kit on push to main as labsbx-dhi-launch Trigger the publish on pushes to main instead of v* tags, and publish to ghcr.io//labsbx-dhi-launch. :latest and :sha- follow main; : is added the first time that version is published and never overwritten. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/publish-kit.yaml | 75 +++++++++++++++--------------- README.md | 4 +- 2 files changed, 39 insertions(+), 40 deletions(-) diff --git a/.github/workflows/publish-kit.yaml b/.github/workflows/publish-kit.yaml index 5221309..3ecbe9d 100644 --- a/.github/workflows/publish-kit.yaml +++ b/.github/workflows/publish-kit.yaml @@ -1,12 +1,14 @@ name: publish-kit # Builds this lab's Docker Sandboxes content kit (dhi-launch.yaml) and publishes -# it to ghcr.io///kit. It runs with the Labspace kit from +# it to ghcr.io//labsbx-dhi-launch. It runs with the Labspace kit from # https://github.com/mathieu-benoit/labsbxes (see the README). # -# pull request nothing pushed: built to a local OCI layout, checked with kit-tck -# push of a v* tag : and :latest (an existing version is skipped) -# manual run on main :edge and :sha- (elsewhere: build only) +# pull request nothing pushed: built to a local OCI layout, checked with kit-tck +# push to main / manual run :latest and :sha-, plus : +# on main the first time that version is published (a published version +# is never overwritten: bump version: to release a new one) +# manual run elsewhere build only on: pull_request: @@ -18,7 +20,8 @@ on: - ".dockerignore" - ".github/workflows/publish-kit.yaml" push: - tags: ["v*"] + branches: + - main workflow_dispatch: permissions: @@ -40,7 +43,7 @@ jobs: runs-on: ubuntu-latest permissions: contents: read - packages: write # push to ghcr.io///kit + packages: write # push to ghcr.io//labsbx-dhi-launch steps: - uses: actions/checkout@v7 with: @@ -61,31 +64,16 @@ jobs: exit 1 fi - image="${REGISTRY}/${GITHUB_REPOSITORY,,}/kit" + image="${REGISTRY}/${GITHUB_REPOSITORY_OWNER,,}/labsbx-dhi-launch" publish=false - tags="${image}:ci-build" - primary="${image}:ci-build" - if [ "$EVENT" != "pull_request" ]; then - if [[ "$REF" == refs/tags/v* ]]; then - if [ "${REF#refs/tags/v}" != "$version" ]; then - echo "::error::Release tag ${REF#refs/tags/} does not match version ${version} in ${DESCRIPTOR}." - exit 1 - fi - publish=true - tags="${image}:${version},${image}:latest" - primary="${image}:${version}" - elif [ "$REF" = "refs/heads/main" ]; then - publish=true - tags="${image}:edge,${image}:sha-${GITHUB_SHA::7}" - primary="${image}:edge" - fi + if [ "$EVENT" != "pull_request" ] && [ "$REF" = "refs/heads/main" ]; then + publish=true fi { + echo "image=$image" echo "version=$version" echo "publish=$publish" - echo "tags=$tags" - echo "primary=$primary" } >> "$GITHUB_OUTPUT" - uses: docker/setup-qemu-action@v4 @@ -104,23 +92,36 @@ jobs: username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - - name: Skip a version that is already published - id: exists - if: steps.meta.outputs.publish == 'true' && startsWith(github.ref, 'refs/tags/v') + # :latest and :sha- move with main; : is immutable, so it + # is only added the first time that version is published. + - name: Resolve tags + id: tags env: - PRIMARY: ${{ steps.meta.outputs.primary }} + PUBLISH: ${{ steps.meta.outputs.publish }} + IMAGE: ${{ steps.meta.outputs.image }} + VERSION: ${{ steps.meta.outputs.version }} run: | - if docker buildx imagetools inspect "$PRIMARY" > /dev/null 2>&1; then - echo "skip=true" >> "$GITHUB_OUTPUT" - echo "::notice::$PRIMARY already exists; not republishing. Bump version: in $DESCRIPTOR to release a new one." + set -euo pipefail + if [ "$PUBLISH" != "true" ]; then + tags="${IMAGE}:ci-build" + primary="${IMAGE}:ci-build" else - echo "skip=false" >> "$GITHUB_OUTPUT" + tags="${IMAGE}:latest,${IMAGE}:sha-${GITHUB_SHA::7}" + primary="${IMAGE}:sha-${GITHUB_SHA::7}" + if docker buildx imagetools inspect "${IMAGE}:${VERSION}" > /dev/null 2>&1; then + echo "::notice::${IMAGE}:${VERSION} already exists; publishing :latest and :sha-${GITHUB_SHA::7} only. Bump version: in $DESCRIPTOR to release a new version." + else + tags="${IMAGE}:${VERSION},${tags}" + fi fi + { + echo "tags=$tags" + echo "primary=$primary" + } >> "$GITHUB_OUTPUT" # The `# syntax=docker/sandbox-kit:3` line of the descriptor makes BuildKit # run the Kit frontend, which validates the descriptor and attaches it. - name: Build${{ steps.meta.outputs.publish == 'true' && ' and push' || '' }} - if: steps.exists.outputs.skip != 'true' uses: docker/build-push-action@v7 with: context: . @@ -129,11 +130,10 @@ jobs: provenance: mode=min sbom: false push: ${{ steps.meta.outputs.publish == 'true' }} - tags: ${{ steps.meta.outputs.tags }} + tags: ${{ steps.tags.outputs.tags }} outputs: ${{ steps.meta.outputs.publish != 'true' && format('type=oci,dest={0}/kit-layout,tar=false', runner.temp) || '' }} - name: Install kit-tck - if: steps.exists.outputs.skip != 'true' run: | set -euo pipefail base="https://github.com/docker/sandbox-kit-spec/releases/download/v${KIT_TCK_VERSION}" @@ -147,10 +147,9 @@ jobs: echo "$RUNNER_TEMP/kit-tck" >> "$GITHUB_PATH" - name: Validate the kit with kit-tck - if: steps.exists.outputs.skip != 'true' env: PUBLISH: ${{ steps.meta.outputs.publish }} - PRIMARY: ${{ steps.meta.outputs.primary }} + PRIMARY: ${{ steps.tags.outputs.primary }} run: | if [ "$PUBLISH" = "true" ]; then kit-tck validate "$PRIMARY" diff --git a/README.md b/README.md index d4fa194..c4b9e6d 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ sbx settings set kit.allowedSources '["docker.io/","dhi.io/","ghcr.io/mathieu-be Then, from an empty folder (`sbx run` mounts the current folder as the workspace): ```bash -sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.4 --kit ghcr.io/mathieu-benoit/dhi-launch/kit:0.1.0 -p 8085:8085 -p 5001:5001 --name dhi-launch -d +sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.4 --kit ghcr.io/mathieu-benoit/labsbx-dhi-launch:0.1.0 -p 8085:8085 -p 5001:5001 --name dhi-launch -d ``` Then open the interface on the host port that `sbx ports dhi-launch` lists for sandbox port `3030` (add `-p 3030:3030` to the command to always use http://localhost:3030). @@ -54,7 +54,7 @@ sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.4 --kit . -p 80 Run from the clone, the workspace's own `labspace/` wins over the kit's copy, and `project/` is the folder on your machine, so your edits land in the clone. Add `--kit-arg devMode=true` to see markdown edits live. -The content kit is published by [.github/workflows/publish-kit.yaml](.github/workflows/publish-kit.yaml): push a `v` tag matching `version:` in [dhi-launch.yaml](dhi-launch.yaml) (for example `git tag v0.1.0 && git push origin v0.1.0`) to publish `ghcr.io/mathieu-benoit/dhi-launch/kit:`, or run the workflow manually on `main` to publish `:edge`. New GHCR packages can start out private: make the package public after the first publish. +The content kit is published by [.github/workflows/publish-kit.yaml](.github/workflows/publish-kit.yaml) on every push to `main`, as `ghcr.io/mathieu-benoit/labsbx-dhi-launch`: `:latest` and `:sha-` follow `main`, and `:` (from `version:` in [dhi-launch.yaml](dhi-launch.yaml)) is published the first time that version reaches `main` and never overwritten, so bump `version:` to release a new one. Pull requests only build and validate the kit. New GHCR packages can start out private: make the package public after the first publish. ## Contribute to this Labspace