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..3ecbe9d --- /dev/null +++ b/.github/workflows/publish-kit.yaml @@ -0,0 +1,158 @@ +name: publish-kit + +# Builds this lab's Docker Sandboxes content kit (dhi-launch.yaml) and publishes +# 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 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: + paths: + - "labspace/**" + - "project/**" + - "dhi-launch.yaml" + - "dhi-launch.dockerfile" + - ".dockerignore" + - ".github/workflows/publish-kit.yaml" + push: + branches: + - main + 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//labsbx-dhi-launch + 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_OWNER,,}/labsbx-dhi-launch" + publish=false + if [ "$EVENT" != "pull_request" ] && [ "$REF" = "refs/heads/main" ]; then + publish=true + fi + + { + echo "image=$image" + echo "version=$version" + echo "publish=$publish" + } >> "$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 }} + + # :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: + PUBLISH: ${{ steps.meta.outputs.publish }} + IMAGE: ${{ steps.meta.outputs.image }} + VERSION: ${{ steps.meta.outputs.version }} + run: | + set -euo pipefail + if [ "$PUBLISH" != "true" ]; then + tags="${IMAGE}:ci-build" + primary="${IMAGE}:ci-build" + else + 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' || '' }} + 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.tags.outputs.tags }} + outputs: ${{ steps.meta.outputs.publish != 'true' && format('type=oci,dest={0}/kit-layout,tar=false', runner.temp) || '' }} + + - name: Install kit-tck + 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 + env: + PUBLISH: ${{ steps.meta.outputs.publish }} + PRIMARY: ${{ steps.tags.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..c4b9e6d 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/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). + +- `-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) 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 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