Quickstart

Get up and running quickly with Instruqt.
This guide explains the essentials you need to start building tracks. You can use the Web UI or the Instruqt CLI depending on your preference.
After completing this guide, you will 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
Make sure you have an Instruqt account. Additionally, if you prefer to work with the CLI, make sure 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.Log using your Email and Password or with a third-party app (Google, GitHub, Twitter).
↳ 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/
↳ This opens a browser tab. Login via email, Google, GitHub, or Twitter. 
2.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 with the Instruqt Web UI or CLI:
🌐 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 My First Track, and in the Track slug field enter my-first-track. 
5.Finally, click Create.
↳ Instruqt creates your first track and shows the Track overview page.
A track slug is a unique identifier for your tracks, often used in URLs.
1.Enter the following command to create a track:
instruqt track create
2.Enter My First Track as track title:
==> Track title: My First Track
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 directory along with several files. You will get this output:
    Using the template: Sandbox container
​
==> Creating new track files:
my-first-track
├── 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 my-first-track
    instruqt track push
​
Track directory and configuration files
A complete explanation of the created directory and configuration files it out of the scope of this page. Check out this documentation for more information.
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 must define the following parts of a challenge:
A title, slug, and assignment.
Tabs with components that you make available to the learner. For example, a Shell terminal or a text editor.
Scripts with code that prepare the challenge, check if the learner solved the challenge, etc.
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.In the Title field enter Creating a text file. In the Slug field enter creating-a-text-file.
3.In the Editor tab of the Assignment field 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.
4.In the Teaser field enter Learn how to create a text file.
5.Click Save.
↳ The Track overview page opens again.
6.Click Edit in the Creating a text file challenge.
7.Click Tabs followed by New Tab.
↳ The New tab page opens.
8.In the Title field, enter Shell. And in the Type list, select Terminal.
9.Click Save.
↳ You will see a tab with the name Shell in the list with challenge tabs.
10.Click Back.
↳ The Track overview page opens again.
1.Change the current directory:
cd my-first-track
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:
my-first-track
└── 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 my-first-track 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.
5.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
========================
​
Use the `echo` command to create the text file named "quickstart":
​
```
echo "This quickstart rocks" > quickstart
```
​
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.
6.Save the assignment.md file.
Step 4: Check challenge execution with a 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:
🌐 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.
Check out the Lifecycle Scripts documentation for more information on the types of scripts you can use in your challenges and tracks.
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 (CLI ONLY)
If you are using the CLI, then run the following command to upload your track to Instruqt:
💻 Instruqt CLI
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/my-first-track' (ID: duyafysgxomy)
    Track URL: https://play.instruqt.com/ORGANIZATION_NAME/tracks/my-first-track
    OK
⇨ ORGANIZATION_NAME contains your organization.
Changes made from the web UI are automatically deployed, so no further action is required. 
Step 6: Play a track
You can now play your track. 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
↳ 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 and are officially a content developer! But wait, theres more. To go deeper into Instruqt, check the How-to guides.
Getting started - Previous
Set up Instruqt
Next - How-to guides
Build tracks
Last modified 2mo ago