Challenges
The following describes the most current configuration format, v3. We still support the legacy format.
Challenges are individual steps which are part of a track. Each challenge focuses on an incremental step a learner needs to understand to achieve the goal of the track.
The challenge configuration consists of:
  • Assignment: The text with instructions for the learner.
  • Notes: The slides Instruqt shows to the learner before they start the challenge. These may include text, images, or video.
  • Tabs: The tabs let the learner interact with the sandbox hosts, including a terminal, a code editor, or an embedded website.
  • Setup and cleanup scripts: (Optional) Scripts that run on the sandbox host(s) before and after the learner performs the challenge.
  • Check and solve scripts: (Optional) Scripts that run on the sandbox host(s) when the learner presses check or skip.
You can configure the assignment, notes, and tabs in a special markdown file with an embedded configuration YAML file (using front matter).

Location

Challenge configuration resides in a directory located at the root of a track directory. Challenge directory names consist of a two-digit challenge index, a hyphen, and then a challenge slug.
The challenge numbering starts with 01.
For example, the directory name for the challenge with a slug create-a-file at index 3 becomes 03-create-a-file.

Assignment

Each assignment.md file starts with a front matter block containing the configuration of the challenge, i.e., title, slug, notes, and tabs. The markdown of the challenge description follows it.
The following documents all fields in the assignment.md front matter.
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.
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

Assignment: Sections

Assignments can be divided into collapsible sections, which improve readability for learners. You may want to use sections if your assignment text is naturally divided into multiple steps or your assignment text is very long.
Sections are declared as part of the assignment body text. To declare a section, use the h1 setext header underline:
1
Some Section
2
============
3
4
### You can still use standard headings within a section
5
6
This content will be rendered in a section.
Copied!
If an assignment uses sections but does not start with one, a default Introduction section is used for all content declared before the first section.
Example of an assignment with multiple sections:
1
---
2
slug: my-challenge
3
type: challenge
4
title: My Challenge
5
tabs:
6
- title: Shell
7
type: terminal
8
hostname: container
9
difficulty: basic
10
timelimit: 600
11
---
12
13
Introduction
14
============
15
16
The `Introduction` section can be used to describe the assignment in detail before the learner starts the challenge.
17
18
Challenge
19
=========
20
21
Describe the actual "challenge" the learner needs to complete
22
Copied!
Will result in the assignment sidebar rendering as shown below
Introduction with challenge sections

Notes

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 kinds 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. Self-signed SSL certificates are OK. If you use ${_SANDBOX_ID} in a url, it will be replaced with the sandbox ID.
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.
Warning about running complex web applications in a website tab:
If your website uses JavaScript redirects you must set new_window to true.The website tab is only able to support standard HTTP 301 or 302 codes for URL redirects.
We recommend running complex web applications with the new_window setting to avoid unexpected issues that can result from being behind the Instruqt proxy.

Full example of assignment.md

1
---
2
slug: first-challenge
3
type: challenge
4
title: First challenge
5
teaser: A short description of the challenge.
6
notes:
7
- type: text
8
contents: Notes show while the challenge is loading.
9
tabs:
10
- title: Shell
11
type: terminal
12
hostname: shell
13
timelimit: 600
14
---
15
# A Large Header
16
Put your own markdown here. Any valid Github-flavored markdown can be used.
17
18
You may also use basic HTML and CSS tags to format text and images.
Copied!
Last modified 4d ago