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
Make sure you have an Instruqt account. Additionally, if you prefer to work with the CLI, make sure you have:
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.

To start building, you need to log in to Instruqt.
🌐 Web UI
💻 Instruqt CLI
- 1.
- 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 commandinstruqt 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.
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. Select Use template from the dropdown. ↳ The Instruqt templates page opens.
- 2.Select the
Sandbox container
template. ↳ The Create a track from template pop-up opens. - 3.In the Track title field enter My First Track, and in the Track slug field enter my-first-track.
- 4.Finally, click Create.↳ Instruqt creates your first track and shows the Track dashboard 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 scratchFor full flexibility, start with an empty track[2] From a templateTo get started quickly, start from one of our templatesPlease select your method: 2 - 4.Enter 2 for the
Sandbox container
template:==> Choose a template:[1] AWS Cloud AccountLearn how to build tracks with an AWS account[2] Sandbox containerGet started quickly with just one container-based sandbox host.[3] Sandbox virtual machineUse a virtual machine (VM) as a sandbox host[4] Helm chartLearn how to install helm charts with Instruqt.[5] KubernetesLearn how to build Kubernetes-based tracks with this template[6] Multi-node Kubernetes clusterSetup a Kubernetes cluster on multiple sandbox hosts[7] VSCode & TypeScriptEdit and test TypeScript applications in VSCodePlease 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.ymlOK==> 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-trackinstruqt 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.
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
, andassignment
. 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.In the Challenges section, click Add new. ↳ The New challenge pop-up opens.
- 2.In the Name field, enter
Creating a text file
. In the URL field, entercreating-a-text-file
. - 3.In the Description field, enter
Learn how to create a text file
. - 4.Pick the Assignment challenge type.
- 5.Click Save. ↳ The New challenge pop-up closes.
- 6.Click the
Creating a text file
challenge. ↳ The Edit challenge page opens. - 7.Click Tabs, followed by Add new tab. ↳ The New tab pop-up opens.
- 8.Select the Terminal type.
- 9.In the Tab name field, enter
Shell
. And in the Select your host list, pickcontainer
. - 10.Click Save.↳ You will see a tab with the name
Shell
in the list with challenge tabs. - 11.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.
- 12.Click Save changes.
- 13.Click Back to track. ↳ The Track dashboard 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 definitionOK==> Creating challenge filesCreated challenge directory and template:my-first-track└── 02-creating-a-text-file├── assignment.md├── check-container├── cleanup-container├── setup-container└── solve-containerOKThe 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.---slug: creating-a-text-filetype: challengetitle: Creating a text fileteaser: A short description of the challenge.notes:- type: textcontents: Replace this text with your own texttabs:- title: Shelltype: terminalhostname: containerdifficulty: basictimelimit: 600---For example, the
tabs
section sets the available challenge components. In this case aterminal
with the titleShell
. - 5.Replace the content of
assignment.md
with this YAML/Markdown:---slug: create-a-text-filetype: challengetitle: Create a text fileteaser: Learn how to create a text file.notes:- type: textcontents: Please wait while we set up the second challengetabs:- title: Shelltype: terminalhostname: containerdifficulty: basictimelimit: 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.
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 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/bashset -euxo pipefailecho "Checking if the text file quickstart exists."if [ -f /root/quickstart ]thenecho "The text file quickstart exists"elsefail-message "There is no text file named quickstart, did you create it?"fi
- 5.Click Save.
- 6.Click Back to track to open the Track dashboard 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/bashset -euxo pipefailecho "Checking if the text file quickstart exists."if [ -f /root/quickstart ]thenecho "The text file quickstart exists"elsefail-message "There is no text file named quickstart, did you create it?"fiba - 2.Save the file
check-container
.
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 challengesOK==> Checking tabsOK==> Checking scriptsOK==> Checking for leftover *.remote filesOK==> Reading track definitionOK==> Pushing trackOK==> Pushing assetsEverything up-to-dateOK==> Updating local track:OK==> Building track 'tieme/my-first-track' (ID: duyafysgxomy)Track URL: https://play.instruqt.com/ORGANIZATION_NAME/tracks/my-first-trackOK⇨ ORGANIZATION_NAME contains your organization.
Changes made from the web UI are automatically deployed, so no further action is required.
You can now play your track. Test the track as if you are a learner:
🌐 Web UI
💻 Instruqt CLI
- 1.Click Play track on the Track dashboard 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 Return to overview to close the track execution.
- 1.Enter the following command to play the track:instruqt track open↳ You will get this output:==> Reading track definitionOK==> 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.