Quickstart

This quickstart explains the essentials you need to start building tracks. You can follow the Web UI or the Instruqt CLI route depending on your preference.
After completing this quickstart, you know how to:
Log in to Instruqt
Create a track
Add a challenge to a track
Check challenge execution with a script
Deploy a track
Play a track
Before you begin
Be sure you have an Instruqt account. And if you prefer to work with the command-line interface, you have:
​Set up the Instruqt CLI​
A code editor installed
What you are going to build
You will build an interactive learning track that runs in a sandbox container with an Ubuntu image. The track challenges the learner to create a directory and a text file from the terminal.
Step 1: Log in to Instruqt
To start building, you need to log in to Instruqt.
🌐 Web UI
💻 Instruqt CLI
1.Open your browser and go to play.instruqt.com.
2.Click Login in the upper right of the Study Room page.
3.Enter your Email and Password in the Login window and click Login.
↳ You are logged in now, and the Content page opens.
1.Open a terminal or command prompt on your machine and type the following command
instruqt auth login
↳ The output looks like this:
==> Signing in to instruqt
==> Please open the following address in your browser and sign in with your Instruqt credentials:
==> http://localhost:15777/

↳ And your default browser opens and shows four sign-in options:
​
​
2.Click on your sign-in option in the opened browser and enter your credentials.
↳ The browser shows that you successfully logged in:
​
​
3.Close the opened browser and return to your terminal or command prompt.
↳ The terminal shows that your credentials are stored:
==> Storing credentials
​
==> Setting ORGANIZATION_NAME as your default organization.
    Run instruqt config unset organization to undo.
​
==> Run instruqt track create to create your first track.
    OK
⇨ ORGANIZATION_NAME contains your organization.
Step 2: Create a track
A track is a series of challenges that a learner must solve. Tracks are the centerpiece of Instruqt, and you can create them in the following ways:
🌐 Web UI
💻 Instruqt CLI
1.Click Create track on the Content page.
↳ The Start creating content page opens:
​
2.Click Create from template.
↳ The Instruqt template page opens
3.Select the Sandbox container template.
↳ The Create a track form template pop-up opens:
​
​
4.In the Track title field, enter MyFirstTrack and click Create.
↳ Instruqt creates your first track and shows the Track overview page.
Check the Instruqt CLI tab of this step if you want to learn how to create a track from Instruqt CLI.
1.Enter the following command to create a track:
instruqt track create
2.Enter MyFirstTrack as track tiltle:
==> Track title: MyFirstTrack
3.Enter 2 to select From a template:
==> Start with an empty track or use a template:
​
    [1] From scratch
        For full flexibility, start with an empty track
    [2] From a template
        To get started quickly, start from one of our templates
​
    Please select your method: 2
4.Enter 2 for the Sandbox containertemplate:
==> Choose a template:
​
    [1] AWS Cloud Account
        Learn how to build tracks with an AWS account
    [2] Sandbox container
        Get started quickly with just one container-based sandbox host.
    [3] Sandbox virtual machine
        Use a virtual machine (VM) as a sandbox host
    [4] Helm chart
        Learn how to install helm charts with Instruqt.
    [5] Kubernetes
        Learn how to build Kubernetes-based tracks with this template
    [6] Multi-node Kubernetes cluster
        Setup a Kubernetes cluster on multiple sandbox hosts
    [7] VSCode & TypeScript
        Edit and test TypeScript applications in VSCode
​
    Please select your template: 2
↳ Instruqt CLI creates the track and you will get this output:
    Using the template: Sandbox container
​
==> Creating new track files:
myfirsttrack
├── 01-creating-a-directory
│   ├── assignment.md
│   ├── check-container
│   └── solve-container
├── config.yml
└── track.yml
    OK
==> More templates are available at https://play.instruqt.com/inspiration-library
​
==> To play your track, change into the track directory and push it to Instruqt:
    cd myfirsttrack
    instruqt track push
Created track directory and configuration files
As you can see in the output, a directory with the name myfirsttrack has been created. This directory contains a subdirectory and several configuration files:
myfirsttrack
├── 01-creating-a-directory
│   ├── assignment.md
│   ├── check-container
│   └── solve-container
├── config.yml
└── track.yml
More on the track directory and configuration files
A complete explanation of the created directory and configuration files goes too far here. But check the reference if you want more information right now.
Step 3: Add a challenge to a track
A challenge is a task in a track that the learner has to solve. To enable the learner to do a challenge, you define the following parts for a challenge:
Description with the actual assignment.
Tabs with components that you make available to the learner. For example, a Shell terminal or a text editor.
Scripts with code that checks if the learner solved the challenge.
The track you created in step 2 has a built-in challenge for creating a directory. Now you will add a challenge to create a text file:
🌐 Web UI
💻 Instruqt CLI
1.Click Add Challenge.
↳ The New Challenge page opens.
2.Enter the following information:
Field
Value
Title
Creating a text file
Slug
creating-a-text-file
Teaser
Learn how to create a text file
And in the Editor tab of the Assignment field, enter the following markdown:
Let's create a text file
==============
​
Create a text file with the name `quickstart` to complete this challenge.
​
Use the `cat` command to create the text file:
​
```
cat > quickstart
```
​
Enter the following text in the file:
```
This quickstart rocks.
```
And finally, type **Ctrl-D** to close the text file.
​
To complete this track click the **Check** button.
3.Click Save.
↳ The Track overview page opens again.
4.Click Edit in the Creating a text file challenge.
5.Click Tabs followed by New Tab.
↳ The New tab page opens.
6.In the Title field, enter Shell. And in the Type list, select Terminal.
7.Click Save.
↳ You will see a tab with the name Shell in the list with challenge tabs.
8.Click Back.
↳ The Track overview page opens again.
1.Change the current directory:
cd myfirsttrack
2.Enter the following command to add the challenge:
instruqt challenge create --title "Creating a text file"
↳ You will get this output:
==> Creating challenge
==> Reading track definition
    OK
==> Creating challenge files
    Created challenge directory and template:
myfirsttrack
└── 02-creating-a-text-file
    ├── assignment.md
    ├── check-container
    ├── cleanup-container
    ├── setup-container
    └── solve-container
    OK
The added challenge only has a skeleton. To further define the challenge, follow the next steps.
3.Open the myfirsttrack directory in your code editor.
4.Open the file 02-creating-a-text-file\assignment.md .
This file contains the challenge in a combination of YAML and Markdown. For now, the file only has a YAML part that sets the properties for the challenge:
---
slug: creating-a-text-file
type: challenge
title: Creating a text file
teaser: A short description of the challenge.
notes:
- type: text
  contents: Replace this text with your own text
tabs:
- title: Shell
  type: terminal
  hostname: container
difficulty: basic
timelimit: 600
---
For example, the tabs section sets the available challenge components. In this case a terminal with the title Shell.
**More about the configuration file `assingment.md`**
​
A complete explanation of all elements in `assingment.md` goes too far here. But check the [reference](../reference/software-development-kit-sdk/configuration-files.md#challenge-level) if you want more information right now.
1.Replace the content of assignment.md with this YAML/Markdown:
---
slug: create-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
==============
​
Create a text file with the name `quickstart` to complete this challenge.
​
Use the `cat` command to create the text file:
​
```
cat > quickstart
```
​
Enter the following text in the file:
```
To complete this quickstart
```
And finally, type **Ctrl-D** to close the text file.
​
.. To complete this track click the **Check** button.
Starting at line 17, the second part of the file sets the assignment text in Markdown for the learner.
2.Save the file assignment.md.
Step 4: Check challenge execution with a script
You can expand a challenge with a script to check if the learner has solved the challenge. This way, you can support the learner when struggling. Or praise the learner when solving a challenge.
Add a script that checks if the learner created the required text file:
🌐 Web UI
💻 Instruqt CLI
1.Click Edit in the Creating a text file challenge.
2.Click Scripts to open the Lifecycle Scripts page.
3.Under container, click check.
4.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
5.Click Save. Followed by Close.
6.Click Back to open the Track overview page again.
1.Open the file 02-create-a-text-file\check-container in your code editor and replace the file content with this bash script:
#!/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?"
fiba
2.Save the file check-container.
Step 5: Deploy a track
Your track is ready now to deploy to the learner. Take the following step to do so:
🌐 Web UI
💻 Instruqt CLI
1.Click Build track ⚙️ on the Track overview page.
↳ The Build track ⚙️ button turns gray while showing a spinner. And after a few seconds, you will see a little pop-up showing ✔Track built!
1.Go back to Instruqt CLI—this is your opened terminal or command prompt—and enter the following command:
instruqt track push
↳ Instruct CLI pushes your local files to the web. And after a few seconds, you get this output:
==> Loading track files...
    OK
==> Checking challenges
    OK
==> Checking tabs
    OK
==> Checking scripts
    OK
==> Checking for leftover *.remote files
    OK
==> Reading track definition
    OK
==> Pushing track
    OK
==> Pushing assets
    Everything up-to-date
    OK
==> Updating local track:
    OK
==> Building track 'tieme/myfirsttrack' (ID: duyafysgxomy)
    Track URL: https://play.instruqt.com/ORGANIZATION_NAME/tracks/myfirsttrack
    OK
⇨ ORGANIZATION_NAME contains your organization.
Step 6: Play a track
You can play your track now. Test the track as if you are a learner:
🌐 Web UI
💻 Instruqt CLI
1.Click Start track on the Track overview page.
2.Wait until your environment is created and click Start.
3.Solve the first challenge and click Check.
4.Notice that you solved the first challenge.
5.Click Start again and solve the second challenge.
6.Click Check again to see if you solved the second challenge.
7.Click Finish to close the track execution.
1.Enter the following command to play the track:
instruqt track open
↳ You will get this output:
==> Reading track definition
    OK
==> Opening track URL (https://play.instruqt.com/ORGANIZATION_NAME/tracks/myfirsttrack) in browser
↳ And your default browser opens the Track overview page\
2.Click Start track.
3.Wait until your environment is created and click Start.
4.Solve the first challenge and click Check.
5.Notice that you solved the first challenge.
6.Click Start again and solve the second challenge.
7.Click Check again to see if you solved the second challenge.
8.Click Finish to close the track execution.
Great job! You have built your first track with Instruqt virtual IT lab. And may call yourself a content developer now. But there is more. To go deeper into Instruqt, you can check the How-to guides.
Getting started - Previous
Set up Instruqt
Next - How-to guides
Build tracks
Last modified 1mo ago
Copy link
Edit on GitHub
Outline
Before you begin
What you are going to build
Step 1: Log in to Instruqt
Step 2: Create a track
Step 3: Add a challenge to a track
Step 4: Check challenge execution with a script
Step 5: Deploy a track
Step 6: Play a track