Instruqt Docs
PlatformGithub
Search
⌃K
Links

Challenges

This page describes challenges, which provide the interaction with learners.

What is a challenge?

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.
See the overview for where a challenge fits into the Instruqt environment.
Some challenge examples are:
  • Create a directory in a terminal
  • Edit a TypeScript file in VS Code
  • Deploy NGINX within Kubernetes
Building challenges
As a content developer, you can build challenges with the Web UI or the Instruqt CLI.

Challenge resources

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

Appearance

🌐 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
Every challenge has its own subdirectory. In this case, 01-creating-a-directory. In this directory, you will find, among other things, the assingment.md file. This file contains the challenge specification in a combination of YAML and Markdown.
Prefix numbering
Every challenge subdirectory gets a consecutive prefix number. 01, 02, and so on.

Challenge properties

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:
    ```js
    copy me!
    ```
    ​
    ```js,nocopy
    don'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

Description

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

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

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

Description

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

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

Tabs

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
Previous
Assignment display settings
Next - Concepts
Sandboxes
Last modified 22d ago