Challenges
This page describes challenges, which provide the interaction with learners.
A challenge is an interactive step in a track and consists of instructional or background content in the form of notes and of hands-on interactive content. Each challenge focuses on an incremental step a learner needs to understand to achieve the learning goal of the track.
Some challenge examples are:
- Create a directory in a terminal
- Edit a TypeScript file in VS Code
- Deploy NGINX within Kubernetes
Building challenges
A challenge can contain the following resources:
- Tabs with software and service, which learners need to solve the challenge. Think of a tab as a view on the sandbox, so learners can interact with the sandbox. You can have the following tab types:
- Service
- Terminal
- Code Editor
- Website
- Notes that give instructions for the challenge or provide background information in the form of:
- Text
- Images
- Video
- Scripts that give learners the context or starting position they need and check the learner's solution including providing feedback. You can define automatically executed scripts for:
- Setting up a challenge
- Checking a challenge
- Automatically solving a challenge
- Cleaning up a challenge
🌐 Web UI
💻 Instruqt CLI
In the Web UI, a challenge appears within a track:

In Instruqt CLI, a challenge appears as a subdirectory (lines 2 to 7) within a track:
sandboxcontainer
├── 01-creating-a-directory
│ ├── assignment.md
│ ├── check-container
│ ├── cleanup-container
│ ├── setup-container
│ └── solve-container
├── config.yml
└── track.yml
Prefix numbering
Every challenge subdirectory gets a consecutive prefix number.
01
, 02
, and so on.You specify a challenge by setting the challenge properties. For example, the
teaser
property lets you specify a short description of the challenge. You can set the challenge properties through the Web UI or Instruqt CLI.For Web UI, you will find the properties as fields on the Challenge details page. For Instruqt CLI, you will find the properties in the configuration file assignment.md as in this example:
YAML/Markdown
---
slug: creating-a-directory
id: 49x8munieydf
type: challenge
title: Creating a directory
teaser: Learn how to create directory
notes:
- type: text
contents: Please wait while we set up the first challenge
tabs:
- title: Shell
type: terminal
hostname: container
difficulty: basic
timelimit: 600
---
🤖 Let's start
==============
Create a directory with the name `instruqt` to complete this challenge.
Use the `mkdir` command to create the directory:
```
mkdir instruqt
```
To complete this track click the **Check** button.
For the assignment's markdown Instruqt provides support for two custom features:
- Sections:This is a section==============Create a directory with the name `instruqt` to complete this challenge.Collapsible accordion.
- Copyable code blocks:```jscopy me!``````js,nocopydon't copy me!```Two code blocks one with copy enabled (default) the other has copying disabled.
The following tables show the challenge properties grouped by tab/section:
🌐 Web UI field list
💻 Instruqt CLI property list
Field | Description | Type | Required |
---|---|---|---|
Title | The title of the challenge. | string | Required |
Type | The type of the challenge.
Can either be Challenge or Quiz | string | Required |
Slug | An URL-friendly identifier of a challenge.
You can only use the same slug once in a single track. | string | Required |
Assignment | Challenge: a description of the challenge.
Quiz: the question. | markdown | Optional |
Teaser | A short description of the challenge, which is shown in the challenge list. | string | Optional |
Timelimit | 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.
If you set a time limit at the track details level, challenge times are ignored. | integer | Optional |
You will get these extra fields when you select challenge type Quiz:
Field | Description | Type | Required |
---|---|---|---|
Answer | A possible quiz answer | string | At least one answer required |
Correct answer | Multiple correct answers are possible. | boolean | At least one correct answer required |
Notes provide the learner with context and background information.
Note: Text
Field | Description | Type | Required |
---|---|---|---|
Type | Text | string | Required |
Contents new | This property sets the content of the note. | string | Required |
Note: Image/video
Field | Description | Type | Required |
---|---|---|---|
Type | Image or Video | string | Required |
URL | The url link of the image or url of the video. | string | Required |
Tabs provide services that are exposed to the learner in the browser.
Tab: Service
Field | Description | Type | Required |
---|---|---|---|
Title | This property sets the tab title. And each service has its own tab. | string | Required |
Type | Service | string | Required |
Host | This property sets the tab hostname. | string | Required |
Path | The filesystem path on the host that should be used in the editor | string | Optional |
Port | The port that is 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) | string | Required |
Open in new window | Whether to open the tab in a new window.
Useful for when the service doesn't allow being run in an iframe. | boolean | Optional |
Tab: Terminal
Field | Description | Type | Required |
---|---|---|---|
Title | This property sets the tab title. And each service has its own tab. | string | Required |
Type | Terminal | string | Required |
Host | This property sets the tab hostname. | string | Required |
Working directory | This property sets the working directory of the terminal. It defaults to $HOME . | string | Optional |
Custom Command | This property sets a command to run upon opening the terminal. Further commands cannot be run. | string | Optional |
Tab: Code Editor
Field | Description | Type | Required |
---|---|---|---|
Title | This property sets the tab title. And each service has its own tab. | string | Required |
Type | Code Editor | string | Required |
Host | This property sets the tab hostname. | string | Required |
Path | The filesystem path on the host that should be used in the editor | string | Optional |
Tab: Website
Field | Description | Type | Required |
---|---|---|---|
Title | This property sets the tab title. And each service has its own tab. | string | Required |
Type | Website | string | Required |
URL | 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. | string | Required |
Open in new window | Whether to open the tab in a new window.
Useful for when the service doesn't allow being run in an iframe. | boolean | Optional |
Property | Description | Type | Required |
---|---|---|---|
title | The title of the challenge. | string | Required |
type | The type of the challenge. challenge or quiz | string | Required |
slug | An URL-friendly identifier of a challenge.
You can only use the same slug once in a single track. | string | Required |
Markdown section | Challenge: a description of the challenge.
Quiz: the question. | markdown | Optional |
teaser | A short description of the challenge, which is shown in the challenge list. | string | Optional |
id | Server-generated (do not edit) | string | Required |
timelimit | 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.
If you set a time limit at the track details level, challenge times are ignored. | integer | Optional |
difficulty | This field will be deprecated in a future release and is not displayed to users. | string | Optional |
Example
assignment.md
YAML/Markdown
slug: creating-a-directory
id: 49x8munieydf
type: challenge
title: Creating a directory
teaser: Learn how to create directory
difficulty: basic
timelimit: 600
---
🤖 Let's start
==============
Create a directory with the name `instruqt` to complete this challenge.
Use the `mkdir` command to create the directory:
```
mkdir instruqt
```
To complete this track click the **Check** button.
You will also need the following properties when you select challenge type
quiz
:Property | Description | Type | Required |
---|---|---|---|
answers: [] | An array of strings that with the possible answers in the challenge | []string | Required |
solution: [] | An array of integers with the indexes of the correct answers. Multiple correct answers are possible. | []integer | Required |
Notes provide the learner with context and background information.
Main property:
notes:
Sub properties per note type:
Note: Text
Property | Description | Type | Required |
---|---|---|---|
type | text | string | Required |
contents | This property sets the content of the note. | string | Required |
Example
assignment.md
YAML/Markdown
notes:
- type: text
contents: Please wait while we set up the first challenge
Note: Image/video
Property | Description | Type | Required |
---|---|---|---|
type | image or video | string | Required |
url | The url link of the image or url of the video. | string | Required |
Example
assignment.md
YAML/Markdown
notes:
- type: video
url: https://www.youtube.com/embed/MLqEgjXFSaw
Notes provide the learner with context and background information.
Main property:
tabs:
Sub properties per tab type:
Tab: Service
Property | Description | Type | Required |
---|---|---|---|
title | This property sets the tab title. And each service has its own tab. | string | Required |
type | service | string | Required |
hostname | This property sets the tab hostname. | string | Required |
path | The filesystem path on the host that should be used in the editor | string | Optional |
port | The port that is 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) | string | Required |
new_window | Whether to open the tab in a new window.
Useful for when the service doesn't allow being run in an iframe. | boolean | Optional |
Example
assignment.md
YAML/Markdown
tabs:
- title: GCP Console
type: service
hostname: cloud-client
path: /
port: 80
Tab: Terminal
Property | Description | Type | Required |
---|---|---|---|
title | This property sets the tab title. And each service has its own tab. | string | Required |
type | terminal | string | Required |
hostname | This property sets the tab hostname. | string | Required |
workdir | This property sets the working directory of the terminal. It defaults to $HOME . | string | Optional |
cmd | This property sets a command to run upon opening the terminal. Further commands cannot be run. | string | Optional |
Example
assignment.md
YAML/Markdown
tabs:
- title: Cloud CLI
type: terminal
hostname: cloud-client
Tab: Code
Property | Description | Type | Required |
---|---|---|---|
title | This property sets the tab title. And each service has its own tab. | string | Required |
type | code | string | Required |
hostname | This property sets the tab hostname. | string | Required |
path | The filesystem path on the host that should be used in the editor | string | Optional |
Example
assignment.md
YAML/Markdown
tabs:
- title: Nano
type: code
hostname: container
path: /
Tab: Website
Property | Description | Type | Required |
---|---|---|---|
title | This property sets the tab title. And each service has its own tab. | string | Required |
type | website | string | Required |
url | 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. | string | Required |
new_window | Whether to open the tab in a new window.
Useful for when the service doesn't allow being run in an iframe. | boolean | Optional |
Example
assignment.md
YAML/Markdown
tabs:
- title: Instruqt
type: website
url: https://www.instruqt.com
new_window: true
Tab: External
Property | Description | Type | Required |
---|---|---|---|
title | This property sets the tab title. And each service has its own tab. | string | Required |
type | external | string | Required |
url | 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. | string | Required |
Example
assignment.md
YAML/Markdown
tabs:
- title: Instruqt
type: external
url: https://www.instruqt.com
Last modified 22d ago