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 — or open Add Template on an existing lab's detail page, which is the same editor.
2. Choose Paste 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 (or Add Template in the drawer).

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 a 5Gi persistent volume.

workspace_templates:
  - name: default

Persistence

Every workspace gets a persistent volume unless the template opts out. The volume is mounted over the student's whole home directory, so their files, their IDE settings and the extensions they install all come back when the pod is rescheduled onto another node — which happens routinely, on cluster upgrades, node failures and autoscaler consolidation.

A devcontainer workspace is the exception: its volume holds the project folder and the IDE's settings and extensions, but not the rest of the home directory — see the caveats in that section.

disk_size sizes that volume (5Gi by default). storage_class places it; left empty the cluster's default StorageClass is used, which is what you want on an EasyLab-provisioned OVHcloud or Azure cluster.

A git-backed workshop

The most common setup: clone the exercises repo, open a subfolder, install the language extension.

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.

Faster first start

Most of a student's wait happens while the workspace pod starts, not in EasyLab. Two things help:

• Images are pre-pulled for you. Every lab runs a small DaemonSet (easylab-prepull-<lab id>, in the workspace namespace) that pulls each template's images onto every node ahead of time. That covers the IDE image, sidecars, the git-clone helper, and the baked or envbuilder image for devcontainer templates. So the first student on a node, or on a node the autoscaler just added, does not wait on a multi-hundred-megabyte pull. This needs no configuration; see Image pre-pull.
• git_shallow: true for large repos. It clones only the latest commit instead of the full history. The student can still commit, push and pull, but git log, git blame and checking out older commits only see that one commit. Use it when the history is large and the exercises don't need it. It also applies to a devcontainer template that is not baked (ENVBUILDER_GIT_CLONE_DEPTH=1). A baked repo snapshot is always a full clone, because it is taken once and not per student.

workspace_templates:
  - name: big-repo
    git_repo: https://gitlab.com/org/monorepo.git
    git_shallow: true

If students don't need their work to survive a reschedule, ephemeral: true also skips attaching a persistent volume, which on OVHcloud adds tens of seconds to a start. Read the warning under Persistence first.

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.

VS Code settings

workspace_templates:
  - name: focused
    vscode_settings:
      chat.disableAIFeatures: true
      security.workspace.trust.enabled: false
      editor.fontSize: 14
      files.exclude:
        "**/node_modules": true

The settings are written to code-server's user settings file (~/.local/share/code-server/User/settings.json) before the IDE starts. All setting scopes work there, including application-scoped ones such as security.workspace.trust.enabled.

• The file is only written when it does not exist yet. On a persistent workspace that means the first start: a student who changes a setting keeps the change across restarts, and a later edit to vscode_settings does not reach workspaces that already exist.
• The value must be a map. It is validated when the YAML is saved; a key with no name, or a value that is not a mapping, is rejected in the editor.
• Importing a devcontainer fills vscode_settings from its customizations.vscode.settings — see Importing a devcontainer.

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.
• In the lab detail page's Workspaces & Templates section, 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.
• Do not set ephemeral. The volume holding the student's files is also what makes the workspace folder writable by the usual uid-1000 devcontainer users (vscode, node, coder). Opting out of it can leave the folder owned by root, with the student unable to save. Use disk_size to size it instead.
• $HOME is not persisted in devcontainer mode, but the IDE's state is. A plain workspace mounts its volume over the whole home directory; a devcontainer one cannot, because envbuilder replaces the entire root filesystem during the build and a devcontainer image's user home is often not /home/coder at all. Its volume instead holds two things: the project folder, and code-server's data directory (~/.local/share/code-server, linked onto the volume at /ide-state). So a student's files, their IDE settings and the extensions they install survive a restart, while anything else written to the home directory — shell history, dotfiles, tools installed under ~ — does not.
  • This needs the devcontainer's user to be root or in group 1000, as the usual vscode, node and coder users are. For any other user the IDE falls back to keeping its data in the unpersisted home directory.
  • It applies to workspaces created from now on. A devcontainer workspace that already exists keeps the project-only volume it was created with until it is deleted and recreated.

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, choose From a devcontainer in the Templates step — or in the Add Template drawer on an existing lab. 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.

devcontainer:
  enabled: true
  dir: .devcontainer
  use_in_cluster_cache: true

devcontainer:
  enabled: true
  dir: .devcontainer
  use_in_cluster_cache: true
  registry_auth_secret: regcred   # for the private base image

Pre-baking: skipping the build entirely

Everything above describes making the build fast. A lab admin can instead skip it entirely: in the lab detail page's Workspaces & Templates section, a devcontainer template's card has a Bake image button. Baking builds the devcontainer once, pushes the result as an ordinary image, and records it on the lab — every student workspace for that template afterward does a plain image pull instead of running envbuilder at all, so neither the build nor the per-pod layer extraction above happens per student.

This is an action on a lab, not a template YAML key — there is nothing to set on the template itself. An admin triggers it with the button, or lets EasyLab do it with the Bake devcontainer images automatically option of the create-lab wizard and of the Add Template drawer, which bakes a devcontainer template as soon as the lab is ready or the template is added. See Pre-baking a devcontainer template in the admin guide for how to trigger it, what the status badges mean, and the domain requirement when baking to the in-cluster registry (an external cache_repo has no such requirement).

A bake also snapshots the workshop repository (git_repo, at git_branch) into the image, at /opt/easylab/repo. A student's workspace copies it onto their volume on first start instead of cloning, so starting a workspace makes no request to the git host at all — no clone time, and no rate limit to hit when a whole class starts at once. The result is the same checkout a clone would have produced, .git included, owned by the IDE user; a returning student's files are never overwritten. Private repositories are baked too — the clone at bake time uses the template's git_auth_secret, and the token is never written into the image. The in-cluster registry requires authentication for exactly this reason; an external cache_repo should be private if the repository is.

The tradeoff: a bake is a snapshot. It does not track the workshop repository, so a new commit — or a devcontainer.json change — after baking needs an explicit Rebuild. Until then, students keep getting the previously baked content rather than the live one.

A Rebuild always reaches students. Baked images are pushed to a fixed :latest tag, but EasyLab records the image by its digest (…/baked/<lab>/<template>@sha256:…) rather than by that tag, and hands the digest to student pods. That matters because workspace pods pull with imagePullPolicy: IfNotPresent — deliberately, so a burst of students starting at once reuses a node's cached layers instead of all hitting the registry. Under a plain :latest a node that had already cached the pre-rebuild image would have gone on serving it; a digest changes whenever the content does, so the kubelet fetches the new image while an unchanged one still hits the node cache. (If the registry does not report a digest, EasyLab falls back to the tag and logs it — the bake still works, without that guarantee.)

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 — or into a running one through Add Template — 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