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 Creator Studio page opens.
1.Open a terminal or command prompt on your machine and type the following command
1
instruqt auth login
Copied!
↳ The output looks like this:
1
==> Signing in to instruqt
2
==> Please open the following address in your browser and sign in with your Instruqt credentials:
3
==> http://localhost:15777/
Copied!

↳ 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:
1
==> Storing credentials
2
​
3
==> Setting ORGANIZATION_NAME as your default organization.
4
    Run instruqt config unset organization to undo.
5
​
6
==> Run instruqt track create to create your first track.
7
    OK
Copied!
⇨ 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 Creator Studio 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:
1
instruqt track create
Copied!
2.Enter MyFirstTrack as track tiltle:
1
==> Track title: MyFirstTrack
Copied!
3.Enter 2 to select From a template:
1
==> Start with an empty track or use a template:
2
​
3
    [1] From scratch
4
        For full flexibility, start with an empty track
5
    [2] From a template
6
        To get started quickly, start from one of our templates
7
​
8
    Please select your method: 2
Copied!
4.Enter 2 for the Sandbox containertemplate:
1
==> Choose a template:
2
​
3
    [1] AWS Cloud Account
4
        Learn how to build tracks with an AWS account
5
    [2] Sandbox container
6
        Get started quickly with just one container-based sandbox host.
7
    [3] Sandbox virtual machine
8
        Use a virtual machine (VM) as a sandbox host
9
    [4] Helm chart
10
        Learn how to install helm charts with Instruqt.
11
    [5] Kubernetes
12
        Learn how to build Kubernetes-based tracks with this template
13
    [6] Multi-node Kubernetes cluster
14
        Setup a Kubernetes cluster on multiple sandbox hosts
15
    [7] VSCode & TypeScript
16
        Edit and test TypeScript applications in VSCode
17
​
18
    Please select your template: 2
Copied!
↳ Instruqt CLI creates the track and you will get this output:
1
    Using the template: Sandbox container
2
​
3
==> Creating new track files:
4
myfirsttrack
5
├── 01-creating-a-directory
6
│   ├── assignment.md
7
│   ├── check-container
8
│   └── solve-container
9
├── config.yml
10
└── track.yml
11
    OK
12
==> More templates are available at https://play.instruqt.com/templates
13
​
14
==> To play your track, change into the track directory and push it to Instruqt:
15
    cd myfirsttrack
16
    instruqt track push
Copied!
​
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:
1
myfirsttrack
2
├── 01-creating-a-directory
3
│   ├── assignment.md
4
│   ├── check-container
5
│   └── solve-container
6
├── config.yml
7
└── track.yml
Copied!
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:
1
Let's create a text file
2
==============
3
​
4
Create a text file with the name `quickstart` to complete this challenge.
5
​
6
Use the `cat` command to create the text file:
7
​
8
```
9
cat > quickstart
10
```
11
​
12
Enter the following text in the file:
13
```
14
This quickstart rocks.
15
```
16
And finally, type **Ctrl-D** to close the text file.
17
​
18
To complete this track click the **Check** button.
Copied!
​
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:
1
cd myfirsttrack
Copied!
2.Enter the following command to add the challenge:
1
instruqt challenge create --title "Creating a text file"
Copied!
 ↳ You will get this output:
1
==> Creating challenge
2
==> Reading track definition
3
    OK
4
==> Creating challenge files
5
    Created challenge directory and template:
6
myfirsttrack
7
└── 02-creating-a-text-file
8
    ├── assignment.md
9
    ├── check-container
10
    ├── cleanup-container
11
    ├── setup-container
12
    └── solve-container
13
    OK
Copied!
​
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:
1
---
2
slug: creating-a-text-file
3
type: challenge
4
title: Creating a text file
5
teaser: A short description of the challenge.
6
notes:
7
- type: text
8
  contents: Replace this text with your own text
9
tabs:
10
- title: Shell
11
  type: terminal
12
  hostname: container
13
difficulty: basic
14
timelimit: 600
15
---
Copied!
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 if you want more information right now.
​
5.Replace the content of  assignment.md with this YAML/Markdown:
1
---
2
slug: create-a-text-file
3
type: challenge
4
title: Create a text file
5
teaser: Learn how to create a text file.
6
notes:
7
- type: text
8
  contents: Please wait while we set up the second challenge
9
tabs:
10
- title: Shell
11
  type: terminal
12
  hostname: container
13
difficulty: basic
14
timelimit: 600
15
---
16
​
17
Let's create a text file
18
==============
19
​
20
Create a text file with the name `quickstart` to complete this challenge.
21
​
22
Use the `cat` command to create the text file:
23
​
24
```
25
cat > quickstart
26
```
27
​
28
Enter the following text in the file:
29
```
30
To complete this quickstart
31
```
32
And finally, type **Ctrl-D** to close the text file.
33
​
34
.. To complete this track click the **Check** button.
Copied!
​
Starting at line 17, the second part of the file sets the assignment text in Markdown for the learner.
6.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:
1
#!/bin/bash
2
set -euxo pipefail
3
​
4
echo "Checking if the text file quickstart exists."
5
​
6
if [ -f /root/quickstart ]
7
then
8
    echo "The text file quickstart exists"
9
else
10
    fail-message "There is no text file named quickstart, did you create it?"
11
fi
Copied!
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:
1
#!/bin/bash
2
set -euxo pipefail
3
​
4
echo "Checking if the text file quickstart exists."
5
​
6
if [ -f /root/quickstart ]
7
then
8
    echo "The text file quickstart exists"
9
else
10
    fail-message "There is no text file named quickstart, did you create it?"
11
fiba
Copied!
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:
1
instruqt track push
Copied!
↳ Instruct CLI pushes your local files to the web. And after a few seconds, you get this output:
1
==> Loading track files...
2
    OK
3
==> Checking challenges
4
    OK
5
==> Checking tabs
6
    OK
7
==> Checking scripts
8
    OK
9
==> Checking for leftover *.remote files
10
    OK
11
==> Reading track definition
12
    OK
13
==> Pushing track
14
    OK
15
==> Pushing assets
16
    Everything up-to-date
17
    OK
18
==> Updating local track:
19
    OK
20
==> Building track 'tieme/myfirsttrack' (ID: duyafysgxomy)
21
    Track URL: https://play.instruqt.com/ORGANIZATION_NAME/tracks/myfirsttrack
22
    OK
Copied!
⇨ 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:
1
instruqt track open
Copied!
↳ You will get this output:
1
==> Reading track definition
2
    OK
3
==> Opening track URL (https://play.instruqt.com/ORGANIZATION_NAME/tracks/myfirsttrack) in browser
Copied!
↳ 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.
​