From c2910aa0f1eb04aea02f1027f3007ee3f315c1d3 Mon Sep 17 00:00:00 2001 From: Mathieu Benoit Date: Wed, 18 Nov 2026 12:12:09 -0500 Subject: [PATCH 1/2] Add a README per kit, and list the kits at the top of the root README GHCR shows the linked repository's README on every package page, so the root README now opens with a Kits table that points to each kit's own README. kit/README.md, examples/hello-lab/README.md and examples/building-images-lab/README.md each give the kit's run command, the ports to pin and what it contains. Co-Authored-By: Claude Opus 5.5 --- README.md | 14 ++++++ examples/building-images-lab/README.md | 54 ++++++++++++++++++++ examples/hello-lab/README.md | 51 +++++++++++++++++++ kit/README.md | 68 ++++++++++++++++++++++++++ 4 files changed, 187 insertions(+) create mode 100644 examples/building-images-lab/README.md create mode 100644 examples/hello-lab/README.md create mode 100644 kit/README.md diff --git a/README.md b/README.md index 495c41e..42cac6c 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,20 @@ Run a [Labspace](https://github.com/dockersamples/labspace-infra) (instructions on the left, VS Code on the right, Docker available to the learner) with `sbx run` instead of a six-container `docker compose up`. See [docs/architecture.md](docs/architecture.md) for diagrams of both setups. +## Kits + +This repository publishes three kits to GitHub Container Registry. Each has its own README with its run command and the ports to pin: + +| Kit | Package | README | +|---|---|---| +| Labspace runtime: the interface, VS Code and a private Docker engine | `ghcr.io/mathieu-benoit/labsbxes/labspace` | [kit/README.md](kit/README.md) | +| Hello Labspace: a minimal lab (content kit) | `ghcr.io/mathieu-benoit/labsbxes/hello-lab` | [examples/hello-lab/README.md](examples/hello-lab/README.md) | +| Building Container Images: Best Practices (content kit) | `ghcr.io/mathieu-benoit/labsbxes/building-images-lab` | [examples/building-images-lab/README.md](examples/building-images-lab/README.md) | + +A content kit always runs with the Labspace kit. Commands for all three are in [Published kits](#published-kits-github-actions). + +## Run from source + The infrastructure is a single [Sandbox Kit](https://github.com/docker/sandbox-kit-spec) (v3 mixin) that layers onto the built-in `shell` agent. ```bash diff --git a/examples/building-images-lab/README.md b/examples/building-images-lab/README.md new file mode 100644 index 0000000..1d01957 --- /dev/null +++ b/examples/building-images-lab/README.md @@ -0,0 +1,54 @@ +# Building Container Images: Best Practices + +`ghcr.io/mathieu-benoit/labsbxes/building-images-lab` + +The [labspace-building-images](https://github.com/dockersamples/labspace-building-images) lab from dockersamples, packaged as a content kit for the [Labspace kit](../../kit). The learner takes a small Python web app (the Quote App) and turns a basic Dockerfile into a production-grade image: layer caching, multi-stage builds, non-root users, base images and build secrets, all on the sandbox's own Docker engine. + +The kit only carries the lab's content (`labspace/` and `project/`), so it always runs together with the Labspace kit. + +## Run it + +Allow the registry namespace once (by default `sbx` only installs kits from `docker.io/` and `dhi.io/`): + +```bash +sbx settings set kit.allowedSources '["docker.io/","dhi.io/","ghcr.io/mathieu-benoit/"]' +``` + +Start from a dedicated, empty folder, never from your home directory: the folder you start in is mounted into the sandbox. + +```bash +mkdir -p ~/sbx-lab && cd ~/sbx-lab +``` + +```bash +sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.4 --kit ghcr.io/mathieu-benoit/labsbxes/building-images-lab:0.1.4 -p 8085:8085 -p 5050:5050 --name building-images-lab +``` + +Then run `sbx ports building-images-lab` and open `http://127.0.0.1:/`, with the host port listed for sandbox port 3030. + +| Pin | Why | +|---|---| +| `-p 8085:8085` | Required: the interface embeds the IDE at `http://localhost:8085` | +| `-p 5050:5050` | For the lab's Quote App tab at `http://localhost:5050` | + +Your edits in the IDE stay in the sandbox and survive `sbx stop` and `sbx run --name building-images-lab`, but not `sbx rm building-images-lab`. + +## What's inside + +| Section | | +|---|---| +| Welcome & Your First Build | Build and run the Quote App | +| Understanding Image Layers | Read an image's layer history, and why cleaning up in a later layer doesn't shrink it | +| Dockerfile Best Practices | Copy dependencies before source for caching, add a `.dockerignore`, run as a non-root user | +| Multi-Stage Builds | Shrink the image, make tests gate the build, keep dev tools out | +| Choosing a Base Image | Docker Hardened Images, dev vs runtime variants, and tags | +| Build Secrets | Why build arguments leak secrets, and build secrets instead | +| Wrap-up | The final multi-stage Dockerfile and a best-practices checklist | + +## Source + +- [labspace/](labspace) and [project/](project): copied as they are from [dockersamples/labspace-building-images](https://github.com/dockersamples/labspace-building-images) +- [building-images-lab.yaml](building-images-lab.yaml): the descriptor, a mixin that `requires` the Labspace kit, `provides` `labspace-content` and declares port 5050 +- [building-images-lab.dockerfile](building-images-lab.dockerfile): copies the two folders to `/opt/labspace/content` + +From a clone of the repository, run it from source with `sbx run shell --kit ./kit --kit ./examples/building-images-lab -p 8085:8085 -p 5050:5050 --name building-images-lab`. diff --git a/examples/hello-lab/README.md b/examples/hello-lab/README.md new file mode 100644 index 0000000..db6147a --- /dev/null +++ b/examples/hello-lab/README.md @@ -0,0 +1,51 @@ +# Hello Labspace + +`ghcr.io/mathieu-benoit/labsbxes/hello-lab` + +A minimal lab, packaged as a content kit for the [Labspace kit](../../kit). It shows the two things a Labspace on Docker Sandboxes gives the learner: instructions with **Run** buttons that type into the IDE terminal, and a private Docker engine inside the sandbox, with an nginx container opened in a tab. + +The kit only carries the lab's content (`labspace/` and `project/`), so it always runs together with the Labspace kit. + +## Run it + +Allow the registry namespace once (by default `sbx` only installs kits from `docker.io/` and `dhi.io/`): + +```bash +sbx settings set kit.allowedSources '["docker.io/","dhi.io/","ghcr.io/mathieu-benoit/"]' +``` + +Start from a dedicated, empty folder, never from your home directory: the folder you start in is mounted into the sandbox. + +```bash +mkdir -p ~/sbx-lab && cd ~/sbx-lab +``` + +```bash +sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.4 --kit ghcr.io/mathieu-benoit/labsbxes/hello-lab:0.1.4 -p 8085:8085 -p 3000:3000 --name hello-lab +``` + +Then run `sbx ports hello-lab` and open `http://127.0.0.1:/`, with the host port listed for sandbox port 3030. + +| Pin | Why | +|---|---| +| `-p 8085:8085` | Required: the interface embeds the IDE at `http://localhost:8085` | +| `-p 3000:3000` | For the lab's tab link to `http://localhost:3000` (the nginx container) | + +Your edits in the IDE stay in the sandbox and survive `sbx stop` and `sbx run --name hello-lab`, but not `sbx rm hello-lab`. + +## What's inside + +| Section | | +|---|---| +| Welcome | The instructions and the IDE are two processes in the same microVM | +| Docker inside the sandbox | The sandbox's own engine, bind mounts, and a published port opened in a tab | + +## Source + +This folder is both a content repo and a content kit: + +- [labspace/](labspace) and [project/](project): the lab, in the labspace-infra layout +- [hello-lab.yaml](hello-lab.yaml): the descriptor, a mixin that `requires` the Labspace kit, `provides` `labspace-content` and declares port 3000 +- [hello-lab.dockerfile](hello-lab.dockerfile): copies the two folders to `/opt/labspace/content` + +From a clone of the repository, run it from source with `sbx run shell --kit ./kit --kit ./examples/hello-lab -p 8085:8085 -p 3000:3000 --name hello-lab`. See the [repository README](../../README.md) to package your own lab the same way. diff --git a/kit/README.md b/kit/README.md new file mode 100644 index 0000000..aa5a26b --- /dev/null +++ b/kit/README.md @@ -0,0 +1,68 @@ +# Labspace kit + +`ghcr.io/mathieu-benoit/labsbxes/labspace` + +A [Sandbox Kit](https://github.com/docker/sandbox-kit-spec) (v3 mixin) that runs a [Labspace](https://github.com/dockersamples/labspace-infra) inside a Docker Sandbox: the instructions on the left, VS Code (code-server) on the right, and a private Docker engine for the learner. It layers onto the built-in `shell` agent and replaces the labspace-infra Compose stack. + +The kit carries the runtime, not a lab. The lab comes from one of these, first match wins: + +1. a folder mounted as the workspace that has `labspace/labspace.yaml` (authoring, demos) +2. a content kit composed with it, such as [hello-lab](../examples/hello-lab) or [building-images-lab](../examples/building-images-lab) +3. neither: a built-in getting-started lab that explains how to add one + +## Run it + +Allow the registry namespace once (by default `sbx` only installs kits from `docker.io/` and `dhi.io/`): + +```bash +sbx settings set kit.allowedSources '["docker.io/","dhi.io/","ghcr.io/mathieu-benoit/"]' +``` + +Start from a dedicated, empty folder, never from your home directory: the folder you start in is mounted into the sandbox. + +```bash +mkdir -p ~/sbx-lab && cd ~/sbx-lab +``` + +The built-in getting-started lab: + +```bash +sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.4 -p 8085:8085 --name labspace +``` + +With a lab packaged as a content kit: + +```bash +sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.4 --kit ghcr.io/mathieu-benoit/labsbxes/hello-lab:0.1.4 -p 8085:8085 -p 3000:3000 --name hello-lab +``` + +Then run `sbx ports ` and open `http://127.0.0.1:/`, with the host port listed for sandbox port 3030. + +- Re-attach with `sbx run --name `, stop with `sbx stop `, remove everything with `sbx rm `. +- Add `-d` to start detached. The kit declares `long-running@1`, so the lab keeps running either way. + +## Ports + +The kit publishes these sandbox ports at create, each on a host port `sbx` picks. Pin a host port with `-p` only where something expects a fixed `localhost` address. + +| Sandbox port | What | Pin it? | +|---|---|---| +| 3030 | Labspace interface | Optional: `-p 3030:3030` to always open `http://localhost:3030` | +| 8085 | code-server (VS Code) | **Required**: `-p 8085:8085`, the interface embeds the IDE at `http://localhost:8085` | +| `appPort` (3000) | An app the learner runs | Only if the lab links to it at a fixed `localhost` port | + +## Options + +| Kit arg | Default | What it does | +|---|---|---| +| `appPort` | `3000` | Extra port to publish for the learner's app: `--kit-arg appPort=8080` | +| `devMode` | `false` | Content authoring: `true` reads `/labspace` live, so editing a markdown file on the host and reloading the page shows the change | +| `codeServerVersion` | `4.140.0` | code-server release built into the kit (build time) | + +## Source + +- [labspace.yaml](labspace.yaml): the descriptor (capabilities, ports, network policy, lifecycle hooks) +- [labspace.dockerfile](labspace.dockerfile): builds the overlay +- [files/](files): the startup scripts and the built-in lab + +See the [repository README](../README.md) for how a boot goes, how to package a lab as a kit, and how the kits are published. From e7e779d5ebc4ee25314197744615ed822d51d941 Mon Sep 17 00:00:00 2001 From: Mathieu Benoit Date: Wed, 18 Nov 2026 12:36:03 -0500 Subject: [PATCH 2/2] Document -p 3030:3030 as the fixed-port alternative for the interface Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- examples/building-images-lab/README.md | 3 ++- examples/hello-lab/README.md | 3 ++- kit/README.md | 2 +- 4 files changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 42cac6c..5bc2530 100644 --- a/README.md +++ b/README.md @@ -167,7 +167,7 @@ sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.4 --kit ghcr.io sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.4 --kit ghcr.io/mathieu-benoit/labsbxes/building-images-lab:0.1.4 -p 8085:8085 -p 5050:5050 --name building-images-lab ``` -Then open the host port `sbx ports ` lists for sandbox port 3030 (for example `sbx ports hello-lab`). +Then open the host port `sbx ports ` lists for sandbox port 3030 (for example `sbx ports hello-lab`). That host port is picked by `sbx` and changes at every start; add `-p 3030:3030` to any of these commands to open the interface at http://localhost:3030 instead. | Event | What it does | |---|---| diff --git a/examples/building-images-lab/README.md b/examples/building-images-lab/README.md index 1d01957..f4ac9a2 100644 --- a/examples/building-images-lab/README.md +++ b/examples/building-images-lab/README.md @@ -24,12 +24,13 @@ mkdir -p ~/sbx-lab && cd ~/sbx-lab sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.4 --kit ghcr.io/mathieu-benoit/labsbxes/building-images-lab:0.1.4 -p 8085:8085 -p 5050:5050 --name building-images-lab ``` -Then run `sbx ports building-images-lab` and open `http://127.0.0.1:/`, with the host port listed for sandbox port 3030. +Then run `sbx ports building-images-lab` and open `http://127.0.0.1:/`, with the host port listed for sandbox port 3030. By default that host port is picked by `sbx` and changes at every start. To skip that lookup, add `-p 3030:3030` to the command: the interface is then always at http://localhost:3030 (if that host port is free). | Pin | Why | |---|---| | `-p 8085:8085` | Required: the interface embeds the IDE at `http://localhost:8085` | | `-p 5050:5050` | For the lab's Quote App tab at `http://localhost:5050` | +| `-p 3030:3030` | Optional: open the interface at `http://localhost:3030` instead of looking up its host port with `sbx ports` | Your edits in the IDE stay in the sandbox and survive `sbx stop` and `sbx run --name building-images-lab`, but not `sbx rm building-images-lab`. diff --git a/examples/hello-lab/README.md b/examples/hello-lab/README.md index db6147a..59e71f3 100644 --- a/examples/hello-lab/README.md +++ b/examples/hello-lab/README.md @@ -24,12 +24,13 @@ mkdir -p ~/sbx-lab && cd ~/sbx-lab sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.4 --kit ghcr.io/mathieu-benoit/labsbxes/hello-lab:0.1.4 -p 8085:8085 -p 3000:3000 --name hello-lab ``` -Then run `sbx ports hello-lab` and open `http://127.0.0.1:/`, with the host port listed for sandbox port 3030. +Then run `sbx ports hello-lab` and open `http://127.0.0.1:/`, with the host port listed for sandbox port 3030. By default that host port is picked by `sbx` and changes at every start. To skip that lookup, add `-p 3030:3030` to the command: the interface is then always at http://localhost:3030 (if that host port is free). | Pin | Why | |---|---| | `-p 8085:8085` | Required: the interface embeds the IDE at `http://localhost:8085` | | `-p 3000:3000` | For the lab's tab link to `http://localhost:3000` (the nginx container) | +| `-p 3030:3030` | Optional: open the interface at `http://localhost:3030` instead of looking up its host port with `sbx ports` | Your edits in the IDE stay in the sandbox and survive `sbx stop` and `sbx run --name hello-lab`, but not `sbx rm hello-lab`. diff --git a/kit/README.md b/kit/README.md index aa5a26b..c7c7147 100644 --- a/kit/README.md +++ b/kit/README.md @@ -36,7 +36,7 @@ With a lab packaged as a content kit: sbx run shell --kit ghcr.io/mathieu-benoit/labsbxes/labspace:0.1.4 --kit ghcr.io/mathieu-benoit/labsbxes/hello-lab:0.1.4 -p 8085:8085 -p 3000:3000 --name hello-lab ``` -Then run `sbx ports ` and open `http://127.0.0.1:/`, with the host port listed for sandbox port 3030. +Then run `sbx ports ` and open `http://127.0.0.1:/`, with the host port listed for sandbox port 3030. By default that host port is picked by `sbx` and changes at every start. To skip that lookup, add `-p 3030:3030` to the command: the interface is then always at http://localhost:3030 (if that host port is free). - Re-attach with `sbx run --name `, stop with `sbx stop `, remove everything with `sbx rm `. - Add `-d` to start detached. The kit declares `long-running@1`, so the lab keeps running either way.