Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 <name>` lists for sandbox port 3030 (for example `sbx ports hello-lab`).
Then open the host port `sbx ports <name>` 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 |
|---|---|
Expand Down
55 changes: 55 additions & 0 deletions examples/building-images-lab/README.md
Original file line number Diff line number Diff line change
@@ -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:<HOST PORT>/`, 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`.
52 changes: 52 additions & 0 deletions examples/hello-lab/README.md
Original file line number Diff line number Diff line change
@@ -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:<HOST PORT>/`, 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.
68 changes: 68 additions & 0 deletions kit/README.md
Original file line number Diff line number Diff line change
@@ -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 <name>` and open `http://127.0.0.1:<HOST PORT>/`, 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 <name>`, stop with `sbx stop <name>`, remove everything with `sbx rm <name>`.
- 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 `<workspace>/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.
Loading