You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-**Interface** - provides the split-screen interface that renders the Labspace instructions and VS Code
67
-
-**VS Code Server** - extends the [coder/code-server](https://github.com/coder/code-server) project to provide VS Code in a browser, pre-configured with tooling to support a Docker-focused lab environment
68
-
-**Configurator** - clones the repo and puts it into a volume that is then shared with the VS Code server.
69
-
-**[Docker Socket Proxy](https://github.com/mikesir87/docker-socket-proxy)** - wraps the Docker Socket to put various protections/remappings in place. Specifically:
70
-
- Docker commands will only return the items created by this environment (newly created items are mutated with a label and object responses filter on that label)
71
-
- Mounts in new containers are only allowed from within the project
72
-
- Mount source paths are remapped to the volume the files are found in (even if using relative paths)
73
-
- Requests to start a new container with the Docker socket will be remapped to use the proxied socket. This ensures Testcontainers config also uses the remapping, etc.
74
-
-**VS Code extension** - a custom VS Code extension that provides additional support and functionality in the system, including:
75
-
- Support the "Run" button from the interface to send commands to run in the terminal
76
-
- Host port republisher - watches for containers that are publishing ports and sets up socat proxies to enable direct communication using localhost inside the environment
77
-
78
-
### Content architecture
79
-
80
-
The _content_ for a Labspace is sourced from a git repository.
81
-
82
-
At the root of the repository is a `labspace.yaml` that defines the Labspace. The following is an example:
83
-
84
-
```yaml
85
-
title: Sample Labspace
86
-
description: >
87
-
This Labspace is an example and this description would appear in the header under the title.
88
-
89
-
sections:
90
-
# - title: The name/title of the section. This will appear in the dropdowns and used to generate an "id" of the section (for navigation, etc.)
91
-
# contentPath: The path to the Markdown file, relative to the root of the repository
92
-
- title: Section number one
93
-
contentPath: ./path/to/section-one.md
94
-
- title: The second section
95
-
contentPath: ./section-two.md
96
-
```
97
-
98
-
The markdown files support all GitHub-flavored Markdown. Any `bash`, `sh`, or `console` code blocks will automatically be given a "Run" button to easily run the command in the VS Code editor.
99
24
100
25
## Development
101
26
102
-
"Development"largely depends on what type of development you are trying to do - work on the Labspace infrastructure or writing Labspace content.
103
-
104
-
### Labspace infra development
105
-
106
27
To work on the Labspace infrastructure, you can utilize the `compose.yaml` file. Make sure to enable Compose Watch mode with the `--watch` flag.
107
28
108
29
```console
@@ -111,27 +32,6 @@ docker compose up --watch --build
111
32
112
33
After it starts, open the interface at http://localhost:5173.
113
34
114
-
### Labspace content development
115
-
116
-
If you want to make a Labspace, follow these steps:
117
-
118
-
1. Create a repo or folder that will store your Labspace
119
-
120
-
2. Create a `labspace.yaml` that defines the Labspace. See the example at [`./sample-content-repo/labspace.yaml`](./sample-content-repo/labspace.yaml).
121
-
122
-
3. Start a Labspace in "dev mode". This will mount the content, rather than fetch it, and configure the interface to poll for content changes.
123
-
124
-
```console
125
-
# On Mac
126
-
CONTENT_PATH=$PWD docker compose -f oci://dockersamples/labspace-content-dev up
127
-
128
-
# On Windows with PowerShell
129
-
$Env:CONTENT_PATH = (Get-Location).Path; docker compose -f oci://dockersamples/labspace-content-dev up
130
-
```
131
-
4. Open http://localhost:3030 to open the interface
132
-
133
-
5. Write your content as you wish! You should see the changes reflected in the interface shortly after saving any file changes.
-**Interface** - provides the split-screen interface that renders the Labspace instructions and VS Code
33
+
-**VS Code Server** - extends the [coder/code-server](https://github.com/coder/code-server) project to provide VS Code in a browser, pre-configured with tooling to support a Docker-focused lab environment
34
+
-**Configurator** - clones the repo and puts it into a volume that is then shared with the VS Code server.
35
+
-**[Docker Socket Proxy](https://github.com/mikesir87/docker-socket-proxy)** - wraps the Docker Socket to put various protections/remappings in place. Specifically:
36
+
- Docker commands will only return the items created by this environment (newly created items are mutated with a label and object responses filter on that label)
37
+
- Mounts in new containers are only allowed from within the project
38
+
- Mount source paths are remapped to the volume the files are found in (even if using relative paths)
39
+
- Requests to start a new container with the Docker socket will be remapped to use the proxied socket. This ensures Testcontainers config also uses the remapping, etc.
40
+
-**VS Code extension** - a custom VS Code extension that provides additional support and functionality in the system, including:
41
+
- Support the "Run" button from the interface to send commands to run in the terminal
42
+
- Host port republisher - watches for containers that are publishing ports and sets up socat proxies to enable direct communication using localhost inside the environment
43
+
44
+
### Content architecture
45
+
46
+
The _content_ for a Labspace is sourced from a git repository.
47
+
48
+
At the root of the repository is a `labspace.yaml` that defines the Labspace. The following is an example:
49
+
50
+
```yaml
51
+
title: Sample Labspace
52
+
description: >
53
+
This Labspace is an example and this description would appear in the header under the title.
54
+
55
+
sections:
56
+
# - title: The name/title of the section. This will appear in the dropdowns and used to generate an "id" of the section (for navigation, etc.)
57
+
# contentPath: The path to the Markdown file, relative to the root of the repository
58
+
- title: Section number one
59
+
contentPath: ./path/to/section-one.md
60
+
- title: The second section
61
+
contentPath: ./section-two.md
62
+
```
63
+
64
+
The markdown files support all GitHub-flavored Markdown. Any `bash`, `sh`, or `console` code blocks will automatically be given a "Run" button to easily run the command in the VS Code editor.
This document is intended to capture various best practices as they are discovered.
4
+
5
+
6
+
7
+
## Naming and organization conventions
8
+
9
+
### Name your repos with a `labspace-` prefix
10
+
11
+
To help with discovery and making it clear that the repo is for a Labspace, name the repo with a `labspace-*` prefix.
12
+
13
+
This applies to your code repo (whether on GitHub or elsewhere) and your published Labspace Compose file.
14
+
15
+
### Use the `.labspace` directory
16
+
17
+
In your content repo, consider placing your writeups in the `.labspace` directory to keep things organized and to reduce the clutter that might exist with lots of files/directories in the project directory.
18
+
19
+
Note: We may consider excluding the `.labspace` directory from the File Explorer in VS Code, further reducing the clutter.
20
+
21
+
22
+
23
+
## Authoring practices
24
+
25
+
### 📍 Have a clear goal in mind for your Labspace and stick to it
26
+
27
+
With Labspaces, it's easy to have one Labspace cover a lot of topics. But, it's also really easy to create lots of Labspaces.
28
+
29
+
Recognizing that many users benefit from short hands-on experiences, it's preferred to keep your Labspace focused. Don't cover too many topics.
30
+
31
+
Answer this question - **what are the one or two things a user should come away from this experience?** Then stick to that goal.
32
+
33
+
34
+
### 🎉 Make it fun!
35
+
36
+
Ensure your participants have fun during your Labspace. Feel free to use a fun story or sample application. Use creative emojis!
37
+
38
+
39
+
### 💪 Empower the student, not yourself
40
+
41
+
While Labspaces may be offered in group settings, they are completed individually. While you, the author, may be guiding them, they are doing it on their own. Therefore, empower them!
42
+
43
+
Avoid the usage of first-person plural terms, such as "we", "us", "let's", "our".
44
+
45
+
-**Instead of...** Now that we have a Dockerfile, we are ready to build our first container image!
46
+
-**Consider...** Now that you have a Dockerfile, you are ready to build your first container image!
47
+
48
+
49
+
50
+
### 🔐 Package everything directly into the Labspace
51
+
52
+
Labspaces should be able to run completely independently of the user's local machine. Users should only need a container runtime installed.
53
+
54
+
There should be no bind mounts from the host or other interaction with the host machine. While there are various protections in place, they can also be removed through various configuration overrides. Don't do this as it reduces the amount of trust students may have in your content.
There are a variety of reasons you may need to adjust the defaults in a Labspace. Ideas might include:
4
+
5
+
- Using a different image/environment for the workspace
6
+
- Specifying different ports for the workspace to expose
7
+
- Adding additional environment variables for the workspace
8
+
- Adding models to the Labspace
9
+
10
+
> [!IMPORTANT]
11
+
> Since all of the configuration is defined using Compose, it is important to understand how [Compose files are merged](https://docs.docker.com/reference/compose-file/merge/), including options to replace and reset values.
12
+
13
+
14
+
15
+
## Important note
16
+
17
+
Beyond the project clone URL, **only the workspace service should be modified.** Adjustments to any other services may impact the Labspace's environment and configuration, potentially causing issues or unreliability.
18
+
19
+
20
+
21
+
## Configuration examples
22
+
23
+
The following examples are configurations of the `.labspace/compose.override.yaml` file used to publish the Labspace.
24
+
25
+
### Required configuration
26
+
27
+
The only required configuration is to specify the source of the Labspace content:
The default values for the Labspaces can be seen in the Compose files at the root of the repo:
66
+
67
+
- [`compose.run.yaml`](../compose.run.yaml) - this Compose file is the "main" Compose file when launching a Labspace - `oci://dockersamples/labspace`
68
+
- [`compose.content-dev.yaml`](../compose.content-dev.yaml) - this Compose file is the one used for content development - `oci://dockersamples/labspace-content-dev`
69
+
70
+
To access the defaults, swap in the desired OCI artifact into the `docker compose config` command below:
To override the workspace image, simply specify a new image for the `workspace` service.
87
+
88
+
This project currently provides the following images:
89
+
90
+
- `dockersamples/labspace-workspace-node`- [Docker Hub](https://hub.docker.com/r/dockersamples/labspace-workspace-node) | [Dockerfile](../components/workspace/node/Dockerfile) - a Node-based environment
91
+
- `dockersamples/labspace-workspace-java`- [Docker Hub](https://hub.docker.com/r/dockersamples/labspace-workspace-java) | [Dockerfile](../components/workspace/java/Dockerfile) - a Java-based environment with a JDK and Maven
92
+
93
+
If you need to create your own environment, it is recommended to begin with the `dockersamples/labspace-workspace-base` image. This image includes the Docker tooling, extensions, and default VS Code configuration.
94
+
95
+
```yaml
96
+
services:
97
+
workspace:
98
+
image: my-custom-image
99
+
```
100
+
101
+
102
+
### Overriding the workspace ports
103
+
104
+
Note that you only need to change ports when you want to run an app _from inside_ the workspace container. Any launched containers (either through Compose or directly in the CLI) don't also need to be exposed on the workspace container.
105
+
106
+
Scenarios:
107
+
108
+
- A Labspace that instructs users to run `npm run dev` that runs a Node app on port 3000
109
+
- In this example, port 3000 would need to be exposed by the workspace container to allow the browser to open the app
110
+
- A Labspace that instructs users to run a Spring Boot app that runs on port 8080
111
+
- The workspace would need to publish port 8080 to be accessible by the browser
112
+
- A Labspace that instructs users to start a nginx container and publish port 80
113
+
- This would _not_ require any port changes on the workspace, as the nginx container is publishing its own port
114
+
115
+
```yaml
116
+
services:
117
+
workspace:
118
+
ports: !override
119
+
- "6274:6274" # MCP Inspector users will launch from inside the Labspace
0 commit comments