Create the image for your Learning Center workshop

The workshop environment for the Learning Center is packaged as a container image. This topic describes how you create the Learning Center workshop image.

You can execute the image with remote content pulled down from GitHub or a web server. Alternatively, you can bundle your workshop content, including any extra tools required, in a new container image derived from the workshop environment base image.

Templates for creating a workshop

To get you started with your own workshop content, VMware provides a number of sample workshops. Different templates in Markdown or AsciiDoc are available to use depending on the syntax you use to create the workshop. These templates are available in a zip file called learning-center-workshop-samples.zip on the Broadcom Support Portal. The zip file contains the following projects that you can upload to your own Git repository:

lab-markdown-sample
lab-asciidoc-sample

When creating your own workshops, a suggested convention is to prefix the directory name with the Git repository name where it is hosted. For example, you can make the prefix lab-. This way it stands out as a workshop or lab when you have a number of Git repositories on the same Git hosting service account or organization.

Important
Do not make the name you use for a workshop too long. The DNS host name used for applications deployed from the workshop, when using certain methods of deployment, might exceed the 63 character limit. This is because the workshop deployment name is used as part of the namespace for each workshop session. This in turn is used in the DNS host names generated for the ingress host name. VMware suggests keeping the workshop name, and so your repository name, to 25 characters or less.

Workshop content directory layout

After creating a copy of the sample workshop content, you can see a number of files located in the top-level directory and a number of subdirectories forming a hierarchy. The files in the top-level directory are:

README.md - A file stating what the workshop in your Git repository is about and how to deploy it. Replace the current content provided in the sample workshop with your own.
LICENSE - A license file so people are clear about how they can use your workshop content. Replace this with what license you want to apply to your workshop content.
Dockerfile - Steps to build your workshop into an image ready for deployment. Leave this as is, unless you want to customize it to install additional system packages or tools.
kustomization.yaml - A kustomize resource file for loading the workshop definition. The Learning Center operator must be deployed before using this file.
.dockerignore - List of files to ignore when building the workshop content into an image.
.eduk8signore - List of files to ignore when downloading workshop content into the workshop environment at runtime.

Key subdirectories and the files contained within them are:

workshop - Directory under which your workshop files reside.
workshop/modules.yaml - Configuration file with details of available modules that make up your workshop and data variables for use in content.
workshop/workshop.yaml - Configuration file that gives the name of the workshop, the list of active modules for the workshop, and any overrides for data variables.
workshop/content - Directory under which your workshop content resides, including images to be displayed in the content.
resources - Directory under which Kubernetes custom resources are stored for deploying the workshop using the Learning Center.
resources/workshop.yaml - The custom resources for the Learning Center, which describe your workshop and requirements for deployment.
resources/training-portal.yaml - A sample custom resource for the Learning Center for creating a training portal for the workshop, encompassing the workshop environment and a workshop instance.

A workshop can include other configuration files and directories with other types of content, but this is the minimal set of files to get you started.

Directory for workshop exercises

The number of files and directories can quickly add up at the top level of your repository. The same is true of the home directory for the user when running the workshop environment. To help with this proliferation of files, you can push files required for exercises during the workshop into the exercises subdirectory under the root of the repository.

With an exercises subdirectory, the initial working directory for the embedded terminal when created is set to $HOME/exercises instead of $HOME. If the embedded editor is enabled, the subdirectory is opened as the workspace for the editor. Only directories and files in that subdirectory are visible through the default view of the editor.

However, the exercises directory isn’t set as the home directory of the user. This means if a user inadvertently runs cd with no arguments from the terminal, they go back to the home directory.

To avoid confusion and help a user return to where they must be, VMware recommends that when you instruct users to change directories, provide a full path relative to the home directory. For example, use a path of the form ~/exercises/example-1 rather than example-1 for the cd command when changing directories. By using a full path, users can execute the command and be assured of going to the required location.