# Quickstart

## Background

Tracks are guided learning experiences. There are two main parts to a track: 

* [Challenges](/tracks/challenges.md) for users to complete.
* [Sandboxes](/sandboxes/overview.md) for users to interact with, in challenges.

Every time a learner plays a track, the following occurs:

1. Instruqt deploys a sandbox.
2. The first challenge is presented to the leaner. 
3. The learner solves the challenge by interacting with the sandbox, and optionally checks their work.
4. The subsequent challenge is displayed, or the track finishes.

{% hint style="info" %}
[Watch this introduction to Instruqt to learn more.](https://www.youtube.com/watch?v=eDj4cpst0tA)
{% endhint %}

## Overview

You will build a track that teaches learners how to create files and directories in Linux. 

<figure><img src="/files/ykYQLV5rGIwbiwwOIVei" alt=""><figcaption><p>Check scripts between challenges wil validate work</p></figcaption></figure>

### Step 1: Create a track

Create a track with the Instruqt Web UI or CLI:

{% hint style="info" %}
To use the Instruqt CLI you must install the executable. Instructions can be found [here](https://docs.instruqt.com/getting-started/set-up-instruqt#step-3-set-up-your-chosen-tool).
{% endhint %}

{% tabs %}
{% tab title="🌐 Web UI" %}

1. Click **Create track** in the upper-right corner of the *Content page*.&#x20;
2. Select **Use template** from the dropdown.
3. Click **Select** on the `Sandbox container` template. This template has an Ubuntu container in its sandbox, and an initial challenge created.\
   ↳ This opens a "Create track" dialogue&#x20;
4. Input a track title and slug (URL).&#x20;
5. Finally, click **Create**.\
   ↳ This opens the T*rack dashboard* page

{% hint style="info" %}
A **track slug** is a unique identifier for your tracks, often used in URLs.
{% endhint %}
{% endtab %}

{% tab title="💻 Instruqt CLI" %}

1. Run the following command to create a track:

   ```bash
   instruqt track create
   ```
2. Enter `My First Track` as the track title.
3. When asked to select a build method, input **`2`** to select *From a template*.
4. When asked to select a template, input **`2`** for the *Sandbox container* template.

The `create` command will generate a file structure similar to the following:

{% code title="Track file structure" %}

```markdown
my-first-track/
    config.yml                    # sandbox configuration file
    track.yml                     # track configuration file
    01-creating-a-directory/      # first challenge directory
        assignment.md             # challenge config and assignment
```

{% endcode %}

{% hint style="info" %}
Check out [this documentation](/reference/cli/configuration-files.md) to learn more about the files created in the CLI.
{% endhint %}
{% endtab %}
{% endtabs %}

### Step 2: Add a challenge

A challenge has a few components:

* A `title`, `slug`, and `assignment`.
* `Tabs` with components that you make available to the learner. For example, a terminal.
* `Scripts` that prepare the challenge, check if the learner solved the challenge, etc.

Add a second challenge to the track with the Instruqt Web UI or CLI:

{% tabs %}
{% tab title="🌐 Web UI" %}

1. In the **Challenges** section of the *Track dashboard* page, click **Add new**.
2. Select **Assignment** from the dropdown.\
   ↳ This opens a new challenge page
3. Enter `Creating a text file` and `creating-file` as the challenge name and URL.
4. In the **Description** field, enter `Learn how to create a text file`.
5. In the upper-right corner, click **Save.**
6. From the top menu bar, click **Tabs.**
7. Click **Add new tab**.
8. Select the **Terminal** tab type.
9. In the **Tab name** field, enter `Shell`. In the **Select your host** list, pick `container`.
10. Click **Save**.
11. From the top menu bar, click **Assignment** and enter the following markdown:

    ````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**.
    {% endtab %}

{% tab title="💻 Instruqt CLI" %}

1. Change into the directory created for the track:

   ```
   cd my-first-track
   ```
2. Enter the following command to add the challenge:

   ```
   instruqt challenge create --title "Creating a text file"
   ```
3. Open the  `02-creating-a-text-file\assignment.md` file, replace its contents with the following, then save the file.

   <pre class="language-markdown" data-line-numbers><code class="lang-markdown">---
   slug: creating-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.
   </code></pre>

{% hint style="info" %}
Line `1` to `15`is the configuration of the challenge in YAML, while line `17` onwards is markdown for the assignment learners will see.
{% endhint %}
{% endtab %}
{% endtabs %}

### Step 3: Add a check 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:

{% tabs %}
{% tab title="🌐 Web UI" %}

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:

   ```bash
   #!/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**.
6. Click the track name in the upper-left to open the *Track dashboard page* again.

{% hint style="info" %}
Read the [Lifecycle Scripts documentation](/sandboxes/lifecycle-scripts.md) for more information on the types of scripts you can use in your challenges and tracks.
{% endhint %}
{% endtab %}

{% tab title="💻 Instruqt CLI" %}

1. Open the `02-creating-a-text-file\check-container` file in your code editor, replace it's content with this bash script, then save the file.

   ```bash
   #!/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
   ```

{% hint style="info" %}
Read the [Lifecycle Scripts documentation](/sandboxes/lifecycle-scripts.md) for more information on the types of scripts you can use in your challenges and tracks.
{% endhint %}
{% endtab %}
{% endtabs %}

### Step 4: Deploy a track (CLI only)

If you are using the CLI, then run the following command to upload your track to Instruqt:

{% tabs %}
{% tab title="💻 Instruqt CLI" %}

1. Run the following command to upload your track:

   ```
   instruqt track push
   ```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Changes made from the web UI are automatically deployed, so no further action is required.&#x20;
{% endhint %}

### Step 5: Play a track

You can now play your track. Test the track as if you are a learner:

{% tabs %}
{% tab title="🌐 Web UI" %}

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. Click **Start** again and solve the second challenge.
5. Click **Check** again to see if you solved the second challenge.
6. Click **Return to overview** to close the track execution.
   {% endtab %}

{% tab title="💻 Instruqt CLI" %}

1. Enter the following command to play the track:

   ```
   instruqt track open
   ```

   ↳ 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.
   {% endtab %}
   {% endtabs %}

## Next steps

We recommend the following articles to continue your learning journey:

* [Challenge tabs](/tracks/challenges/challenge-tabs.md)
* [Sandbox hosts](/sandboxes/hosts.md)
* [Cloud accounts](/sandboxes/cloud-accounts.md)
* [Lifecycle scripts](/sandboxes/lifecycle-scripts.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.instruqt.com/getting-started/quickstart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.