Quickstart

Learn how to deploy your first Instruqt track.

Background

Tracks are guided learning experiences. There are two main parts to a track:

Challenges for users to complete.
Sandboxes for users to interact with, in challenges.

Every time a learner plays a track, the following occurs:

Instruqt deploys a sandbox.
The first challenge is presented to the leaner.
The learner solves the challenge by interacting with the sandbox, and optionally checks their work.
The subsequent challenge is displayed, or the track finishes.

Watch this introduction to Instruqt to learn more.

Overview

You will build a track that teaches learners how to create files and directories in Linux.

Step 1: Create a track

Create a track with the Instruqt Web UI or CLI:

To use the Instruqt CLI you must install the executable. Instructions can be found here.

Click Create track in the upper-right corner of the Content page.
Select Use template from the dropdown.
Click Select on the Sandbox container template. This template has an Ubuntu container in its sandbox, and an initial challenge created. ↳ This opens a "Create track" dialogue
Input a track title and slug (URL).
Finally, click Create. ↳ This opens the Track dashboard page

A track slug is a unique identifier for your tracks, often used in URLs.

Run the following command to create a track:
```
instruqt track create
```
Enter My First Track as the track title.
When asked to select a build method, input 2 to select From a template.
When asked to select a template, input 2 for the Sandbox container template.

The create command will generate a file structure similar to the following:

Track file structure

my-first-track/
    config.yml                    # sandbox configuration file
    track.yml                     # track configuration file
    01-creating-a-directory/      # first challenge directory
        assignment.md             # challenge config and assignment

Check out this documentation to learn more about the files created in the CLI.

Step 2: Add a challenge

A challenge has a few components:

A title, slug, and assignment.
Tabs with components that you make available to the learner. For example, a terminal.
Scripts that prepare the challenge, check if the learner solved the challenge, etc.

Add a second challenge to the track with the Instruqt Web UI or CLI:

In the Challenges section of the Track dashboard page, click Add new.
Select Assignment from the dropdown. ↳ This opens a new challenge page
Enter Creating a text file and creating-file as the challenge name and URL.
In the Description field, enter Learn how to create a text file.
In the upper-right corner, click Save.
From the top menu bar, click Tabs.
Click Add new tab.
Select the Terminal tab type.
In the Tab name field, enter Shell. In the Select your host list, pick container.
Click Save.

From the top menu bar, click Assignment and enter the following markdown:

Let's create a text file
========================

Use the `echo` command to create the text file named "quickstart":

```
echo "This quickstart rocks" > quickstart
```

To complete this track, click the **Check** button.

Click Save changes.

Change into the directory created for the track:
```
cd my-first-track
```

Enter the following command to add the challenge:

instruqt challenge create --title "Creating a text file"

Open the 02-creating-a-text-file\assignment.md file, replace its contents with the following, then save the file.

---
slug: creating-a-text-file
type: challenge
title: Create a text file
teaser: Learn how to create a text file.
notes:
- type: text
  contents: Please wait while we set up the second challenge
tabs:
- title: Shell
  type: terminal
  hostname: container
difficulty: basic
timelimit: 600
---

Let's create a text file
========================

Use the `echo` command to create the text file named "quickstart":

```
echo "This quickstart rocks" > quickstart
```

To complete this track, click the **Check** button.

Line 1 to 15is the configuration of the challenge in YAML, while line 17 onwards is markdown for the assignment learners will see.

Step 3: Add a check script

You can expand a challenge with a script to check if a learner has solved the challenge. This way, you can support the learner if they need help, or praise then when solving a challenge.

Add a script that checks if the learner created the required text file:

Click the Creating a text file challenge.
Click Scripts to open the Lifecycle Scripts page.
Under container, click check.

Enter the following bash script to check if the learner created the text file:

#!/bin/bash
set -euxo pipefail

echo "Checking if the text file quickstart exists."

if [ -f /root/quickstart ]
then
    echo "The text file quickstart exists"
else
    fail-message "There is no text file named quickstart, did you create it?"
fi

Click Save.
Click the track name in the upper-left to open the Track dashboard page again.

Read the Lifecycle Scripts documentation for more information on the types of scripts you can use in your challenges and tracks.

Open the 02-creating-a-text-file\check-container file in your code editor, replace it's content with this bash script, then save the file.

#!/bin/bash
set -euxo pipefail

echo "Checking if the text file quickstart exists."

if [ -f /root/quickstart ]
then
    echo "The text file quickstart exists"
else
    fail-message "There is no text file named quickstart, did you create it?"
fi

Read the Lifecycle Scripts documentation for more information on the types of scripts you can use in your challenges and tracks.

Step 4: Deploy a track (CLI only)

If you are using the CLI, then run the following command to upload your track to Instruqt:

Run the following command to upload your track:
```
instruqt track push
```

Changes made from the web UI are automatically deployed, so no further action is required.

Step 5: Play a track

You can now play your track. Test the track as if you are a learner:

Click Play track on the Track dashboard page.
Wait until your environment is created and click Start.
Solve the first challenge and click Check.
Click Start again and solve the second challenge.
Click Check again to see if you solved the second challenge.
Click Return to overview to close the track execution.

Enter the following command to play the track:
```
instruqt track open
```
↳ Your default browser opens the Track overview page.
Click Start track.
Wait until your environment is created and click Start.
Solve the first challenge and click Check.
Notice that you solved the first challenge.
Click Start again and solve the second challenge.
Click Check again to see if you solved the second challenge.
Click Finish to close the track execution.

Next steps

We recommend the following articles to continue your learning journey:

PreviousSetting up NextManage tracks

Last updated 7 months ago