Skip to content

Commit c2d33ae

Browse files
mikesir87mikesir87
authored
Merge pull request #24614 from mikesir87/add-new-labs
Create new guides for several new labspaces
2 parents 63b48df + 8ebaa8e commit c2d33ae

17 files changed

+649
-94
lines changed

‎.agents/skills/create-lab-guide/SKILL.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
name: create-lab-guide
3+
description: >
4+
Create a guide page for a Labspace. This includes writing the markdown content for the guide,
5+
structuring it according to Docker docs conventions, and ensuring it provides clear instructions
6+
and information about the Labspace. Includes learning about the lab itself, extracting out its
7+
learning objectives, and combining all of that into a well-structured guide markdown file.
8+
---
9+
10+
# Create Lab Guide
11+
12+
You are creating a new guide page for a labspace. The guide should be structured according to Docker docs conventions,
13+
with clear sections, learning objectives, and instructions for users to get the most out of the lab.
14+
15+
## Inputs
16+
17+
The user provides one or more guides to migrate. Resolve these from the inventory below:
18+
19+
- **REPO_NAME**: GitHub repo in the `dockersamples` org (e.g. `labspace-ai-fundamentals`)
20+
21+
## Step 1: Clone the labspace repo
22+
23+
Clone the guide repo to a temporary directory. This gives you all source files locally — no HTTP calls needed.
24+
25+
```bash
26+
git clone --depth 1 https://github.com/dockersamples/{REPO_NAME}.git <tmpdir>/{REPO_NAME}
27+
```
28+
29+
Where `<tmpdir>` is a temporary directory on your system (e.g. the output of `mktemp -d`).
30+
31+
## Step 2: Learn and extract key information about the lab
32+
33+
The repo structure is:
34+
35+
- `<tmpdir>/{REPO_NAME}/README.md` — the main README for the lab
36+
- `<tmpdir>/{REPO_NAME}/labspace/labspace.yaml` — a YAML document outlining details of the lab, including the sections/modules and the path to their content
37+
- `<tmpdir>/{REPO_NAME}/labspace/*.md` — the content for each section/module (only reference the files specified in `labspace.yaml`)
38+
- `<tmpdir>/{REPO_NAME}/.github/workflows/` — the GHA workflow that publishes the labspace. It includes the repo URL for the published Compose file, which will be useful for the "launch" command
39+
- `<tmpdir>/{REPO_NAME}/compose.override.yaml` - lab-specific Compose customizations
40+
41+
1. Read `README.md` to understand the purpose of the lab.
42+
2. Read the `labspace/labspace.yaml` to understand the structure of the lab and its sections/modules.
43+
3. Read the `labspace/*.md` files to extract the learning objectives, instructions, and any code snippets.
44+
4. Extract a short description that can be used for the `description` and `summary` fields in the guide markdown.
45+
5. Determine if a model will be pulled when starting the lab by looking at the `compose.override.yaml` file and looking for the any top-level `model` specifications.
46+
47+
48+
## Step 2: Write the guide markdown
49+
50+
The markdown file must be located in the `guides/` directory and have a filename of `lab-{GUIDE_ID}.md`.
51+
52+
Sample markdown structure, including frontmatter and content:
53+
54+
```markdown
55+
---
56+
title: "Lab: { Short title }"
57+
linkTitle: "Lab: { Short title }"
58+
description: |
59+
A short description of the lab for SEO and social sharing.
60+
summary: |
61+
A short summary of the lab for the guides listing page. 2-3 lines.
62+
keywords: AI, Docker, Model Runner, agentic apps, lab, labspace
63+
aliases: # Include if the lab is an AI-related lab
64+
- /labs/docker-for-ai/{REPO_NAME_WITHOUT_LABSPACE_PREFIX}/
65+
params:
66+
tags: [ai, labs]
67+
time: 20 minutes
68+
resource_links:
69+
- title: A resource link pointing to relevant documentation or code
70+
url: /ai/model-runner/
71+
- title: Labspace repository
72+
url: https://github.com/dockersamples/{REPO_NAME}
73+
---
74+
75+
Short explanation of the lab and what it covers.
76+
77+
## Launch the lab
78+
79+
{{< labspace-launch image="dockersamples/{REPO_NAME}" >}}
80+
81+
## What you'll learn
82+
83+
By the end of this Labspace, you will have completed the following:
84+
85+
- Objective #1
86+
- Objective #2
87+
- Objective #3
88+
- Objective #4
89+
90+
## Modules
91+
92+
| # | Module | Description |
93+
|---|--------|-------------|
94+
| 1 | Module #1 | Description of module #1 |
95+
| 2 | Module #2 | Description of module #2 |
96+
| 3 | Module #3 | Description of module #3 |
97+
| 4 | Module #4 | Description of module #4 |
98+
| 5 | Module #5 | Description of module #5 |
99+
| 6 | Module #6 | Description of module #6 |
100+
```
101+
102+
Important notes:
103+
104+
- The learning objectives should be based on the content of the labspace as a whole.
105+
- The modules should be based on the sections/modules outlined in `labspace.yaml`.
106+
- All lab guides _must_ have a tag of `labs`
107+
- If the lab is AI-related, it should also have a tag of `ai` and aliases for `/labs/docker-for-ai/{REPO_NAME}/`
108+
- If the lab pulls a model, add a `model-download: true` parameter to the `labspace-launch` shortcode to show a warning about model downloads.
109+
110+
111+
## Step 3: Apply Docker docs style rules
112+
113+
These are mandatory (from STYLE.md and AGENTS.md):
114+
115+
- **No "we"**: "We are going to create" → "Create" or "Start by creating"
116+
- **No "let us" / "let's"**: → imperative voice or "You can..."
117+
- **No hedge words**: remove "simply", "easily", "just", "seamlessly"
118+
- **No meta-commentary**: remove "it's worth noting", "it's important to understand"
119+
- **No "allows you to" / "enables you to"**: → "lets you" or rephrase
120+
- **No "click"**: → "select"
121+
- **No bold for emphasis or product names**: only bold UI elements
122+
- **No time-relative language**: remove "currently", "new", "recently", "now"
123+
- **No exclamations**: remove "Voila!!!" etc.
124+
- Use `console` language hint for interactive shell blocks with `$` prompts
125+
- Use contractions: "it's", "you're", "don't"
126+

‎_vale/config/vocabularies/Docker/accept.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ g?libc
9696
GeoNetwork
9797
GGUF
9898
Git
99+
Gitea
99100
GitHub
100101
GitHub Actions
101102
Google

‎content/guides/lab-agentic-apps.md‎

Lines changed: 4 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,10 @@ Get up and running with building agentic applications using Compose, Docker
2626
Model Runner, and the Docker MCP Gateway. This hands-on lab takes you from
2727
understanding AI models to building complete agentic applications.
2828

29+
## Launch the lab
30+
31+
{{< labspace-launch image="dockersamples/labspace-agentic-apps-with-docker" model-download="true" >}}
32+
2933
## What you'll learn
3034

3135
This lab covers three core areas of agentic application development:
@@ -51,27 +55,3 @@ file, and configuring your app to use those models and tools
5155
| 5 | The Docker MCP Gateway | Set up and configure the MCP Gateway |
5256
| 6 | Putting It All Together | Build a complete agentic application |
5357
| 7 | Conclusion | Summary and next steps |
54-
55-
## Prerequisites
56-
57-
- Install the latest version of Docker Desktop
58-
- Enable **Docker Model Runner** by going into Settings in Docker Desktop, choosing AI, then selecting Docker Model Runner
59-
- Pull the Gemma 3 model before launching by running this command:
60-
61-
```console
62-
$ docker model pull ai/gemma3
63-
```
64-
65-
## Launch the lab
66-
67-
Start the labspace:
68-
69-
```console
70-
$ docker compose -f oci://dockersamples/labspace-agentic-apps-with-docker up -d
71-
```
72-
73-
Then open your browser to [http://localhost:3030](http://localhost:3030).
74-
75-
> [!NOTE]
76-
>
77-
> It may take a little while to start due to the AI model download.

‎content/guides/lab-ai-fundamentals.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: "Lab: AI Fundamentals for Developers"
3+
linkTitle: "Lab: AI Fundamentals"
4+
description: |
5+
Learn the core concepts of AI development — models, prompt engineering, tool
6+
calling, and RAG — through hands-on exercises in a live environment.
7+
summary: |
8+
Hands-on lab: Learn the four core pillars of AI application development.
9+
Work with the Chat Completions API, prompt engineering, tool calling, and RAG
10+
through interactive exercises.
11+
keywords: AI, Docker, Model Runner, prompt engineering, RAG, tool calling, lab, labspace
12+
aliases:
13+
- /labs/docker-for-ai/ai-fundamentals/
14+
params:
15+
tags: [ai, labs]
16+
time: 45 minutes
17+
resource_links:
18+
- title: Docker Model Runner docs
19+
url: /ai/model-runner/
20+
- title: Labspace repository
21+
url: https://github.com/dockersamples/labspace-ai-fundamentals
22+
---
23+
24+
Get hands-on with the four core pillars of AI application development: models,
25+
prompt engineering, tool calling, and RAG. This lab runs entirely on your
26+
machine using Docker Model Runner — no API key or cloud account required.
27+
28+
## Launch the lab
29+
30+
{{< labspace-launch image="dockersamples/labspace-ai-fundamentals" model-download="true" >}}
31+
32+
## What you'll learn
33+
34+
By the end of this Labspace, you will have completed the following:
35+
36+
- Understand the Chat Completions API and how to structure messages for a model
37+
- Use prompt engineering techniques including system prompts, few-shot examples, and structured output
38+
- Implement tool calling and the agentic loop in code
39+
- Build a RAG pipeline that grounds model responses in your own data
40+
41+
## Modules
42+
43+
| # | Module | Description |
44+
| --- | ------------------------------------ | ----------------------------------------------------------------- |
45+
| 1 | Welcome & Setup | Introduction to the lab and verifying your environment |
46+
| 2 | Talking to Models | Chat Completions API, message roles, and stateless model behavior |
47+
| 3 | Prompt Engineering | System prompts, few-shot examples, and structured output |
48+
| 4 | Tool Calling | Tool definitions, the agentic loop, and executing tools in code |
49+
| 5 | Retrieval Augmented Generation (RAG) | Retrieve, augment, and generate with your own knowledge base |
50+
| 6 | Wrap-up | Summary of concepts and next steps |

‎content/guides/lab-attestation-basics.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: "Lab: Container Image Attestations"
3+
linkTitle: "Lab: Container Image Attestations"
4+
description: |
5+
Learn to attach SBOMs, build provenance, image signatures, and VEX
6+
statements to container images for a verifiable software supply chain.
7+
summary: |
8+
Hands-on lab: Add supply chain metadata to a container image. Generate
9+
SBOMs and SLSA provenance with BuildKit, sign images with Cosign, and
10+
attach OpenVEX statements to declare vulnerability exploitability status.
11+
keywords: Docker, supply chain, SBOM, provenance, SLSA, Cosign, VEX, attestations, security, lab, labspace
12+
params:
13+
tags: [labs]
14+
time: 45 minutes
15+
resource_links:
16+
- title: Build attestations
17+
url: /build/metadata/attestations/
18+
- title: SBOM attestations
19+
url: /build/metadata/attestations/sbom/
20+
- title: Provenance attestations
21+
url: /build/metadata/attestations/slsa-provenance/
22+
- title: Labspace repository
23+
url: https://github.com/dockersamples/labspace-attestation-basics
24+
---
25+
26+
Prove where your container images came from and that they haven't been
27+
tampered with. This lab walks through generating SBOMs and SLSA build
28+
provenance with BuildKit, signing images with Cosign, and writing VEX
29+
statements to declare which CVEs affect your image — the techniques used
30+
to meet supply chain security requirements like NIST SSDF and EO 14028.
31+
32+
## Launch the lab
33+
34+
{{< labspace-launch image="dockersamples/labspace-attestation-basics" >}}
35+
36+
## What you'll learn
37+
38+
By the end of this Labspace, you will have completed the following:
39+
40+
- Generate and inspect an SPDX SBOM attached to a container image with `--sbom=true`
41+
- Generate SLSA build provenance with `--provenance=mode=max` and understand how multi-stage builds are fully recorded
42+
- Install Cosign and use key-based signing to sign and verify a container image
43+
- Write an OpenVEX statement to declare CVE exploitability status and attach it as a signed attestation
44+
- Understand how SBOMs, provenance, signatures, and VEX complement each other in a complete supply chain story
45+
46+
## Modules
47+
48+
| # | Module | Description |
49+
| --- | --------------------------------- | ------------------------------------------------------------------------------------ |
50+
| 1 | Introduction | Overview of supply chain attestations and the sample Go app |
51+
| 2 | Software Bill of Materials (SBOM) | Build with `--sbom=true`, inspect SPDX contents, and understand scanner integration |
52+
| 3 | Build Provenance | Generate SLSA provenance and explore how multi-stage builds are recorded |
53+
| 4 | Signing Images with Cosign | Generate a key pair, sign the image, verify the signature, and learn keyless signing |
54+
| 5 | VEX Statements | Scan for CVEs, write an OpenVEX document, and attach it as a signed attestation |
55+
| 6 | Bringing It All Together | Run the complete build-sign-attest workflow and see the full supply chain picture |
56+
| 7 | Recap | Summary of skills and next steps for policy enforcement and higher SLSA levels |

‎content/guides/lab-building-images.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: "Lab: Building Container Images"
3+
linkTitle: "Lab: Building Container Images"
4+
description: |
5+
Learn to build production-grade container images using Dockerfile best
6+
practices — layer caching, multi-stage builds, non-root users, base image
7+
selection, and secure build-time secret handling.
8+
summary: |
9+
Hands-on lab: Transform a basic Dockerfile into a production-ready image.
10+
Master layer caching, multi-stage builds, .dockerignore, non-root users,
11+
base image selection, and build secrets.
12+
keywords: Docker, Dockerfile, images, multi-stage builds, layer caching, build secrets, lab, labspace
13+
params:
14+
tags: [labs]
15+
time: 45 minutes
16+
resource_links:
17+
- title: Dockerfile reference
18+
url: /reference/dockerfile/
19+
- title: Multi-stage builds
20+
url: /build/building/multi-stage/
21+
- title: Build secrets
22+
url: /build/building/secrets/
23+
- title: Labspace repository
24+
url: https://github.com/dockersamples/labspace-building-images
25+
---
26+
27+
Take a working but naïve Dockerfile and progressively improve it into a
28+
production-grade image. Each section introduces one technique, applied to
29+
a real Python Flask app, so you can see the impact directly.
30+
31+
## Launch the lab
32+
33+
{{< labspace-launch image="dockersamples/labspace-building-images" >}}
34+
35+
## What you'll learn
36+
37+
By the end of this Labspace, you will have completed the following:
38+
39+
- Read an image's layer history and understand the layer cleanup pitfall
40+
- Restructure a Dockerfile for fast, cache-efficient incremental builds
41+
- Write a `.dockerignore` file and run containers as a non-root user
42+
- Use multi-stage builds to run tests as a build gate and dramatically reduce image size
43+
- Choose the right base image for production, including Docker Hardened Images
44+
- Inject secrets safely at build time using `--mount=type=secret`
45+
46+
## Modules
47+
48+
| # | Module | Description |
49+
| --- | -------------------------- | ---------------------------------------------------------------------- |
50+
| 1 | Welcome & Your First Build | Explore the sample app and build the initial image |
51+
| 2 | Understanding Image Layers | Inspect layers with `docker history` and see the layer cleanup pitfall |
52+
| 3 | Dockerfile Best Practices | Fix cache ordering, add `.dockerignore`, and switch to a non-root user |
53+
| 4 | Multi-Stage Builds | Run tests as a build gate and use a slim base for the production stage |
54+
| 5 | Choosing a Base Image | Compare slim, Alpine, and Docker Hardened Images |
55+
| 6 | Build Secrets | Show why `ARG` leaks secrets and use `--mount=type=secret` safely |
56+
| 7 | Wrap-up | Review the complete best-practices checklist and next steps |

‎content/guides/lab-compose-quickstart.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: "Lab: Docker Compose Quickstart"
3+
linkTitle: "Lab: Docker Compose Quickstart"
4+
description: |
5+
Build a multi-container Flask and Redis application from scratch using Docker
6+
Compose. Learn health checks, watch mode, named volumes, and multi-file
7+
configurations.
8+
summary: |
9+
Hands-on lab: Define and run a multi-container app with Docker Compose.
10+
Progress from a bare compose.yaml through health checks, live development
11+
with watch mode, data persistence, and modular Compose file composition.
12+
keywords: Docker, Compose, multi-container, Flask, Redis, watch mode, volumes, lab, labspace
13+
params:
14+
tags: [labs]
15+
time: 45 minutes
16+
resource_links:
17+
- title: Docker Compose docs
18+
url: /compose/
19+
- title: Compose watch mode
20+
url: /compose/how-tos/file-watch/
21+
- title: Labspace repository
22+
url: https://github.com/dockersamples/labspace-compose-quickstart
23+
---
24+
25+
Build a Python Flask and Redis hit-counter app using Docker Compose, starting
26+
from a bare `compose.yaml` and progressively adding production-quality
27+
features at each step.
28+
29+
## Launch the lab
30+
31+
{{< labspace-launch image="dockersamples/labspace-compose-quickstart" >}}
32+
33+
## What you'll learn
34+
35+
By the end of this Labspace, you will have completed the following:
36+
37+
- Define a multi-service application in a `compose.yaml` file and manage it with Compose commands
38+
- Control service startup order using health checks and `depends_on` conditions
39+
- Iterate on code without manual rebuilds using Compose watch mode
40+
- Persist data across container restarts with named volumes
41+
- Modularize a stack across multiple files using the `include` directive
42+
- Use `config`, `logs`, and `exec` to inspect and debug a running stack
43+
44+
## Modules
45+
46+
| # | Module | Description |
47+
| --- | -------------------------------- | --------------------------------------------------------------------- |
48+
| 1 | Introduction | Tour the starter app and verify the environment |
49+
| 2 | Defining Services | Write the first `compose.yaml` and bring up the Flask and Redis stack |
50+
| 3 | Health Checks & Startup Order | Add a Redis healthcheck and `depends_on` to eliminate race conditions |
51+
| 4 | Live Development with Watch Mode | Configure watch mode to sync code changes without manual rebuilds |
52+
| 5 | Persistence & Debugging | Add a named volume so Redis data survives `docker compose down` |
53+
| 6 | Using Multiple Compose Files | Extract Redis into `infra.yaml` and compose files with `include` |
54+
| 7 | Additional Commands | Use `config`, `logs -f`, and `exec` to inspect the running stack |
55+
| 8 | Recap | Review what was built and explore next steps |

0 commit comments

Comments
 (0)