Quickstart
Get up and running quickly with Instruqt.
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:

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. 1.
    Open your browser and go to play.instruqt.com.
  2. 2.
    Click Login in the upper right of the Study Room page.
  3. 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. 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. 2.
    Click on your sign-in option in the opened browser and enter your credentials. ↳ The browser shows that you successfully logged in:
    ​
    ​
  3. 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. 1.
    Click Create track on the Creator Studio page. ↳ The Start creating content page opens:
    ​
  2. 2.
    Click Create from template.
    ↳ The Instruqt template page opens
  3. 3.
    Select the Sandbox container template. ↳ The Create a track form template pop-up opens:
    ​
    ​
  4. 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. 1.
    Enter the following command to create a track:
    1
    instruqt track create
    Copied!
  2. 2.
    Enter MyFirstTrack as track tiltle:
    1
    ==> Track title: MyFirstTrack
    Copied!
  3. 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. 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. 1.
    Click Add Challenge. ↳ The New Challenge page opens.
  2. 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. 3.
    Click Save.
    ↳ The Track overview page opens again.
  4. 4.
    Click Edit in the Creating a text file challenge.
  5. 5.
    Click Tabs followed by New Tab.
    ↳ The New tab page opens.
  6. 6.
    In the Title field, enter Shell. And in the Type list, select Terminal.
  7. 7.
    Click Save.
    ↳ You will see a tab with the name Shell in the list with challenge tabs.
  8. 8.
    Click Back. ↳ The Track overview page opens again.
  1. 1.
    Change the current directory:
    1
    cd myfirsttrack
    Copied!
  2. 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. 3.
    Open the myfirsttrack directory in your code editor.
  4. 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. 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. 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. 1.
    Click Edit in the Creating a text file challenge.
  2. 2.
    Click Scripts to open the Lifecycle Scripts page.
  3. 3.
    Under container, click check.
  4. 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. 5.
    Click Save. Followed by Close.
  6. 6.
    Click Back to open the Track overview page again.
  1. 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. 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. 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. 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. 1.
    Click Start track on the Track overview page.
  2. 2.
    Wait until your environment is created and click Start.
  3. 3.
    Solve the first challenge and click Check.
  4. 4.
    Notice that you solved the first challenge.
  5. 5.
    Click Start again and solve the second challenge.
  6. 6.
    Click Check again to see if you solved the second challenge.
  7. 7.
    Click Finish to close the track execution.
  1. 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. 2.
    Click Start track.
  3. 3.
    Wait until your environment is created and click Start.
  4. 4.
    Solve the first challenge and click Check.
  5. 5.
    Notice that you solved the first challenge.
  6. 6.
    Click Start again and solve the second challenge.
  7. 7.
    Click Check again to see if you solved the second challenge.
  8. 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.
​