track.yml

The track.yml configuration file

A track guide learners through a series of challenges in a sandbox environment. Learners typically perform their tasks in a web-based shell that runs on a sandbox host. The track configuration file track.yml contains:

  • Track settings

  • Challenges

    • Notes

    • Tabs

This page documents all fields in track.yml

track.yml

field

type

description

type

string

The type of the track. Can either be track or sandbox. Defaults to track.

slug

string

A string that is the ID of the track. The value of the ID should be globally unique.

icon

string

The URL of the icon that is to be shown with the track. The size of the icon should be 48x48 pixels.

title

string

The title of the track.

teaser

string

A short description of the track, which is shown in the track list.

description

string

A full description of the track, which is shown at the track details.

tags

list

A list of strings that represent tags associated with the track.

challenges

list

A list of challenges that belong to the track.

owner

string

The slug of the organization that owns this track.

developers

list

The developers of this track. Developers can preview the track when it is not yet published.

published

bool

Whether the track is published or not. When unpublished, the tracks is only visible to the track developers.

private

bool

Whether the track is visible outside an organization.

maintenance

bool

Whether the track is in maintenance. When true, the track can only be started by track developers. It remains visible to other users, but will show a maintenance banner.

show_timer

bool

Whether to show a timer during the assignment. When true, this timer will show how long the learner has left before the environment expires.

skipping_enabled

bool

True if skipping challenges is enabled for end-users. Defaults to false.

Challenge

Challenges are individual steps which are part of a track. Each challenge focuses on an incremental step a student needs to understand to achieve the learning goal of the track.

field

type

description

type

string

The type of the challenge. Can either be challenge or quiz

slug

string

A unique ID within the scope of the track.

title

string

The title of the challenge.

teaser

string

A short description of the challenge, shown in the challenge list.

notes

[]note

A list of notes that provide the user with context and background information.

assignment

string

A description of the actual challenge the user needs to complete or the challenge question if the challenge type is quiz.

timelimit

int

The time in seconds before a challenge is automatically failed and stopped.

tabs

[]tab

A list of services that are exposed to the user in the browser, where each service has its own tab.

answers

[]string

An array of string that with the possible answers in the challenge

solution

[]int

An array of integers with the indexes of the correct answers. Multiple correct answers are possible.

difficulty

string

One of basic, intermediate, advanced, expert

Note

field

type

description

type

string

The type of the note. Can be any of the following: text, image or video.

contents

string

Only usable with type=text. The contents of the note

url

string

Only usable with type=image or type=video. The url link of the image or url of the video

Tabs

A learner interacts with the sandbox environment through a tab. Different tab types allow for different kind of interactions.‌

Tab: Terminal

This will expose a terminal window to the end user configured for the specific host. If you have multiple hosts, you need to create a separate terminal for each host.‌

Field

Type

Description

type

string

"terminal"

title

string

The title of the tab (will be used in the Instruqt UI)

hostname

string

The name of the machine used in this tab. Must match the name of the container or virtual machine as described in your config.yml

Tab: Visual code editor

This will expose a basic code editor where the end-user can modify files on the filesystem of a specific host.‌

Field

Type

Description

type

string

code

title

string

The title of the tab (will be used in the Instruqt UI)

hostname

string

The name of the machine used in this tab. Must match the name of the container or virtual machine as described in your config.yml

path

string

The filesystem path on the host that should be used in the editor

Tab: ​Service

This will expose a service running on one of the sandbox hosts. For example, a web server running a service on port 80.

Field

Type

Description

type

string

"service"

title

string

The title of the tab (will be used in the Instruqt UI)

hostname

string

The name of the machine used in this tab. Must match the name of the container or virtual machine as described in your environment configuration (config.yml)

port

int

The port used to connect to the service running on the host. In case of a container, the port must be exposed in the environment configuration (config.yml).

path

string

The path of the service. This will be appended to the constructed URL.

new_window

boolean

Whether to open the tab in a new window. Useful for when the service doesn't allow being run in an iframe.

If your service uses HTTPS with (self-signed) TLS certificates, you have to use a port that ends with 443 (e.g. 8443). That will tell our proxy to use HTTPS instead of HTTP for communication with your service.

See Sandbox Networking for more details.

Tab: Website

This will expose an external website to the end user (in an iframe). You could use this to add a tab containing your documentation.‌

Field

Type

Description

type

string

"website"

title

string

The title of the tab (will be used in the Instruqt UI)

url

string

The url of the website opened in this browser. Must be a https:// address

new_window

boolean

Whether to open the tab in a new window. Useful for when the website doesn't allow being run in an iframe.

Tab: ‌External

An external tab opens a URL in a new browser tab/window. This is similar to tabs of type website, but useful for websites that cannot be included in an iframe.

Field

Type

Description

type

string

"external"

title

string

The title of the tab (will be used in the Instruqt UI)

url

string

The url of the website opened in an external tab of the browser.

Full example of track.yml:

slug: first-lab
type: track
title: First lab
teaser: A short description of the track.
description: |-
A long description of the track.
You can use any GitHub flavoured markdown.
icon: https://storage.googleapis.com/instruqt-frontend/img/tracks/default.png
tags: []
owner: example-org
developers:
private: false
published: false
challenges:
- slug: first-challenge
type: challenge
title: First challenge
teaser: A short description of the challenge.
assignment: |-
This is your assignment for this challenge.
You can use any GitHub flavoured markdown.
notes:
- type: text
contents: Notes show while the challenge is loading.
tabs:
- title: Shell
type: terminal
hostname: shell
timelimit: 600