Workspace template examples

A lab's workspace templates describe the environments students can request. Each template is one workspace flavor: an image, an optional git repo to clone, resources, and anything extra the workshop needs (a database, a Docker daemon, some VS Code extensions).

This page is a cookbook of complete, copy-pasteable examples. For the field-by-field reference and the wizard form, see Configure workspaces.

Using these examples

1. Go to New Lab and walk through to the Templates step.
2. Set Configuration Mode to YAML.
3. Paste an example below (or save it as a .yaml file and use Upload file).
4. Click Validate — it checks the document without creating anything.
5. Finish the wizard and click Create Lab.

Only name is required, and template names must be unique within a lab. Unknown keys are rejected rather than ignored, so a typo like imagee: fails validation instead of silently shipping a lab without its image.

Key reference

Minimal

The smallest valid document. Students get a code-server workspace on the default image, with no persistent volume.

workspace_templates:
  - name: default

A git-backed workshop

The most common setup: clone the exercises repo, open a subfolder, install the language extension. git_repo provisions a 5Gi volume automatically, so student work survives a pod restart.

workspace_templates:
  - name: go-workshop
    git_repo: https://gitlab.com/yodamad/go-workshop.git
    git_branch: main
    git_folder: exercises
    extensions:
      - golang.go

The repo is cloned only when the volume is empty — a restarting workspace keeps the student's own commits and edits rather than being reset.

Sizing a workspace

workspace_templates:
  - name: heavy
    cpu: "2"
    memory: 4Gi
    disk_size: 20Gi

Several templates in one lab

Students request one workspace per template, so a lab with three templates lets each student run up to three workspaces side by side. They pick from a dropdown on the student portal.

workspace_templates:
  - name: go
    git_repo: https://gitlab.com/yodamad/go-workshop.git
    extensions:
      - golang.go

  - name: node
    git_repo: https://gitlab.com/yodamad/node-workshop.git
    extensions:
      - dbaeumer.vscode-eslint

  - name: scratch
    disk_size: 5Gi

Installing system packages

Startup scripts run as the workspace user, which has passwordless sudo, so packages can be installed at start:

workspace_templates:
  - name: tooling
    startup_script: |
      sudo apt-get update
      sudo apt-get install -y jq make httpie

Startup scripts are best-effort: a failing command is visible in kubectl logs but never blocks the workspace from opening.

Every student pays this cost on every workspace start, so for anything slow or large bake the tools into an image instead and point the template at it:

FROM codercom/code-server:latest
USER root
RUN apt-get update && apt-get install -y golang nodejs && rm -rf /var/lib/apt/lists/*
USER coder

workspace_templates:
  - name: custom
    image: registry.example.com/easylab/go-workshop:1.0

Push it to a registry the lab cluster can pull from. Prebuilt images also start faster than installing the same packages in every student's workspace. If the registry is private, add image_pull_secrets — see Private registries and repositories.

A database sidecar

Sidecars are extra containers in the same pod, reachable from the IDE at localhost:<port>.

workspace_templates:
  - name: api-workshop
    git_repo: https://gitlab.com/yodamad/api-workshop.git
    env:
      DATABASE_URL: postgres://postgres:postgres@localhost:5432/app
    sidecars:
      - name: db
        image: postgres:16
        ports: [5432]
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: app

Each student gets their own database — sidecars live in the student's pod, not in a shared service.

Docker inside a workspace

Managed clusters (OVHcloud, AKS) run containerd, not Docker, so there is no host Docker socket to reuse. Run a Docker-in-Docker sidecar and point the CLI at it:

workspace_templates:
  - name: docker-workshop
    env:
      DOCKER_HOST: tcp://localhost:2375
    startup_script: |
      sudo apt-get update && sudo apt-get install -y docker.io
      until docker info >/dev/null 2>&1; do sleep 2; done
    sidecars:
      - name: docker
        image: docker:dind
        ports: [2375]
        privileged: true
        env:
          DOCKER_TLS_CERTDIR: ""

DOCKER_TLS_CERTDIR: "" disables TLS on the daemon, which is what makes the plain tcp://localhost:2375 connection work. The startup script waits for the daemon so students don't hit "cannot connect" in their first minute.

Mounting config and secrets

Mount a ConfigMap or Secret that already exists in the workspace namespace (workshops by default — set it on the Workspace step):

workspace_templates:
  - name: preconfigured
    mounts:
      - type: configmap
        name: workshop-config
        path: /etc/workshop
      - type: secret
        name: workshop-registry
        path: /home/coder/.docker

Create them before students request workspaces:

kubectl -n workshops create configmap workshop-config --from-file=./config/
kubectl -n workshops create secret generic workshop-registry --from-file=.dockerconfigjson=./config.json

Personal dotfiles

workspace_templates:
  - name: dotfiles
    dotfiles_repo: https://github.com/yodamad/dotfiles

The repo is cloned to ~/.dotfiles and the first executable of install.sh, setup.sh or bootstrap.sh runs. Like startup scripts, this is best-effort.

Everything together

A full-featured template using most of the schema:

workspace_templates:
  - name: full-stack
    image: codercom/enterprise-base:ubuntu
    git_repo: https://gitlab.com/yodamad/workshop.git
    git_branch: main
    git_folder: exercises
    cpu: "2"
    memory: 4Gi
    disk_size: 10Gi
    startup_script: |
      sudo apt-get update && sudo apt-get install -y jq
      make bootstrap
    dotfiles_repo: https://github.com/yodamad/dotfiles
    extensions:
      - golang.go
      - dbaeumer.vscode-eslint
    env:
      DATABASE_URL: postgres://postgres:postgres@localhost:5432/app
    sidecars:
      - name: db
        image: postgres:16
        ports: [5432]
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: app
    mounts:
      - type: configmap
        name: workshop-config
        path: /etc/workshop

Private registries and repositories

A private image or a private workshop repository needs a credential. Credentials are never written in the template: the template names a Kubernetes Secret, and the Secret lives in the lab's cluster. That is what keeps tokens out of the lab's job file and out of the templates export, so a template is always safe to share.

workspace_templates:
  - name: private-workshop
    image: registry.example.com/workshops/base:1
    image_pull_secrets:
      - regcred
    git_repo: https://gitlab.com/org/private-workshop.git
    git_auth_secret: gitcred
    disk_size: 10Gi

Adding a credential

There are two moments to add one, and they behave the same way — the token is written to the lab's cluster and EasyLab keeps no copy:

• In the creation wizard. The Workspace Templates step has a Credentials section. Add a row for each credential your templates reference. Because the cluster does not exist yet, the tokens are held in memory and written the moment provisioning finishes — before the lab reports itself ready.
• On the lab's Workspaces page, once the lab is up. Expand Credentials, add a Container registry or Git repository credential, and paste the token.

Saving over an existing name rotates it. Workspaces already running keep the old token — the kubelet resolved it when the pod started — so a rotation reaches students only as their workspaces are recreated.

Credentials live in the cluster, so destroying a lab destroys them. Recreating a lab prompts you to re-enter the tokens (the names and types are carried over). A retried lab keeps them.

If a template references a credential the cluster does not have — a token lost to a server restart mid-provisioning, a name typo, or one not yet added — the Credentials panel says so, and the workspaces that need it fail until it is added.

If you have kubectl access you can create the same Secrets by hand; the panel lists those too, since what matters is the name your template references:

# Registry — for image_pull_secrets
kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=<user> \
  --docker-password=<token> \
  --namespace=workshops

# Git — for git_auth_secret
kubectl create secret generic gitcred \
  --type=kubernetes.io/basic-auth \
  --from-literal=username=oauth2 \
  --from-literal=password=<token> \
  --namespace=workshops

What students can and cannot do

The clone is authenticated; the student's IDE is not. The token is given to the clone step alone and never to the workspace container, because students have a shell there and the token is yours, not theirs.

So a student's checkout has an ordinary remote with no stored credentials: reading the code works, but an interactive git pull or git push against the private repo will prompt and fail. If a workshop needs students to push, have them authenticate as themselves from inside the workspace.

Devcontainer workshops

When a workshop repository already ships a .devcontainer/devcontainer.json, a template can build from it instead of naming an image. Each student's workspace builds the devcontainer on first start, so a workshop's own Dockerfile and features work as written.

workspace_templates:
  - name: go-workshop
    git_repo: https://gitlab.com/org/workshop.git
    git_branch: main
    cpu: "2"
    memory: 4Gi
    disk_size: 20Gi
    extensions:
      - golang.go
    devcontainer:
      enabled: true
      dir: .devcontainer
      cache_repo: registry.example.com/easylab/cache
      registry_auth_secret: regcred

The template's own ide key applies here too — see the constraints below.

The image the devcontainer builds contains no IDE of its own, so code-server is copied onto a volume the build is told to leave alone, and started from there. That makes the IDE independent of the devcontainer's own base image — but it does impose three constraints:

• The base image must be glibc-based. The bundle ships a dynamically linked Node, which cannot run on Alpine/musl. The failure is misleading: the workspace container exits with no such file or directory even though the binary is plainly there.
• The devcontainer's user needs a writable $HOME. code-server stores its user data and extensions under the home directory of the user the devcontainer runs as. When that is unwritable, extension installs are skipped quietly and the IDE then fails to start — so an unexplained "my extensions are missing" is worth checking here first.
• Set disk_size. It provisions the volume holding the student's files, which is what makes the workspace folder writable by the usual uid-1000 devcontainer users (vscode, node, coder). Without it, the folder can end up owned by root and the student cannot save.

Authentication is the same as outside devcontainer mode: code-server presents a login page taking the workspace password.

workspace_templates:
  - name: go-workshop
    git_repo: https://innersource.example.com/org/workshop.git
    git_branch: master
    git_auth_secret: gitcred
    disk_size: 20Gi
    devcontainer:
      enabled: true
      dir: .devcontainer
      cache_repo: registry.example.com/easylab/cache
      registry_auth_secret: regcred

Devcontainer config from a separate repository

By default devcontainer.json is read from git_repo — the same repo the student's workspace clones. Set devcontainer.config_repo to read it from a different repo instead — for a devcontainer config shared or standardized across several workshops, kept apart from the workshop content it builds. git_repo is still required and is still what the student's workspace clones; config_repo is only cloned to build the devcontainer, into a separate location in the pod. dir (default .devcontainer) then resolves inside config_repo rather than git_repo.

workspace_templates:
  - name: go-workshop
    git_repo: https://gitlab.com/org/go-workshop-exercises.git
    git_branch: main
    disk_size: 20Gi
    devcontainer:
      enabled: true
      config_repo: https://gitlab.com/org/devcontainer-config.git
      config_branch: main
      dir: .devcontainer
      cache_repo: registry.example.com/easylab/cache
      registry_auth_secret: regcred

A private config_repo needs its own config_auth_secret — it is a separate credential from git_auth_secret, because the two repos may live in different projects or organizations. Create it the same way as any other git credential — see Private registries and repositories.

Importing a devcontainer

Rather than writing the block by hand, use Import from devcontainer in the Templates step. It reads a devcontainer.json — by cloning a repo, or from a devcontainer.json / repository .zip you upload — fills the template in, and reports anything in the devcontainer that will not take effect. The result is ordinary YAML: review and edit it before creating the lab.

By default the import clones the workshop repository field to read the devcontainer. Choose Different repository under Devcontainer config to read it from a separate config repo instead, while the workshop repository field stays the content repo the generated template's git_repo is set to — this produces the config_repo block above without hand-editing the YAML.

For a private repository, supply an access token in the import dialog. It authenticates that one clone and is then discarded — it is not saved anywhere and does not become the lab's git_auth_secret. It cannot: at import time the lab's cluster does not exist yet, so there is nowhere to put a Secret. Giving students access to the repo is the separate step described in Private registries and repositories.

What is honoured, and what is not

The build understands the parts that describe the image; EasyLab covers several keys the build ignores; and some keys are honoured by neither.

Reusing a lab's templates

Use Export Templates YAML on the labs list to download an existing lab's workspace-templates-<stack>.yaml, then load it into a new lab with Upload file. Only the templates are exported — credentials are never included.

This makes template documents easy to keep in a git repository and reuse from one workshop edition to the next.

Troubleshooting