Legacy format (version 2)
Instruqt tracks can use one of two types of challenge configuration formats. This document explains the older, legacy configuration format.
We recommend using the new standard improved format. To upgrade your configuration to this new format, check the upgrade section.
In order for the CLI to read a configuration in the legacy format, the config.yml file needs to either contain a version: "2" top-level entry or not contain a version entry at all.
The challenges are listed in the track.yml configuration file under the challenges top-level entry.
This page documents all fields of the challenges list entries.
field
type
description
type
string
The type of the challenge. Can either be challenge or quiz
slug
string
An URL-friendly identifier of a challenge. You can't use the same slug twice in a single track.
id
string
Server-generated (do not edit)
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
Time limit in seconds. Challenge time limits are not enforced but the track time limit is.
The track time limit is the sum of all challenge time limits in a track.
If the track time limit is reached, the track is automatically stopped and marked as failed.
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
This field will be deprecated in a future release and is not displayed to users. Valid values include: basic, intermediate, advanced, expert

Note

A note is the slide Instruqt shows while a challenge is loading. You can add more than one note to create multiple slides.
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 sandbox hosts 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 a sandbox host. One of the containers or virtual machines in config.yml

Tab: 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 a sandbox host. One of the containers or virtual machines in config.yml
path
string
The filesystem path on the host that should be used in the editor

Tab: ​Service

This will expose a HTTP or HTTPS service, running on one of the sandbox hosts, in a tab using an iframe. Traffic is forwarded from clients through the Instruqt web proxy.
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 a sandbox host. One of the containers or virtual machines in config.yml
port
int
The port used to connect to the service running on the host.
  • If the sandbox host is a container, the port must be exposed in config.yml
  • If the service uses HTTPS, the port must end with 443 (for example: 8443)
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 web service uses HTTPS with (self-signed) TLS certificates, you have to use a port that ends with 443 (e.g. 8443). The Instruqt web proxy uses that to decide to use HTTPS instead of HTTP when forwarding traffic to the sandbox host.
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.

Full example of track.yml

1
slug: first-lab
2
type: track
3
title: First lab
4
teaser: A short description of the track.
5
description: |-
6
A long description of the track.
7
8
You can use any GitHub flavoured markdown.
9
icon: https://storage.googleapis.com/instruqt-frontend/img/tracks/default.png
10
tags: []
11
owner: example-org
12
developers:
14
private: false
15
published: false
16
challenges:
17
- slug: first-challenge
18
type: challenge
19
title: First challenge
20
teaser: A short description of the challenge.
21
assignment: |-
22
This is your assignment for this challenge.
23
24
You can use any GitHub flavoured markdown.
25
notes:
26
- type: text
27
contents: Notes show while the challenge is loading.
28
tabs:
29
- title: Shell
30
type: terminal
31
hostname: shell
32
timelimit: 600
Copied!

Upgrading to version 3

Instruqt CLI tool will use the standard format for all newly created or freshly pulled tracks.
However, pulling updates for an existing local copy of a track would preserve its format - it needs to be upgraded manually.
To upgrade a local copy of a track configured in the legacy format, run the following command:
1
instruqt track upgrade
Copied!
Last modified 1mo ago