diff --git a/README.md b/README.md index 495c41e..5bc2530 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 @@ -153,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 new file mode 100644 index 0000000..f4ac9a2 --- /dev/null +++ b/examples/building-images-lab/README.md @@ -0,0 +1,55 @@ +# 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. 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`. + +## 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..59e71f3 --- /dev/null +++ b/examples/hello-lab/README.md @@ -0,0 +1,52 @@ +# 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. 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`. + +## 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..c7c7147 --- /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. 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. + +## 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.