### Instruqt Hot Start FAQ: Track vs. Challenge Scripts

Source: https://docs.instruqt.com/sandboxes/manage/hot-start

Addresses common questions regarding setup script execution in Instruqt's Hot Start. It clarifies when challenge setup scripts run and how to optimize performance by placing configuration in track setup scripts.

```APIDOC
InstruqtHotStartFAQ:
  questions:
    - title: "Why are my tracks taking awhile to load, even with hot start?"
      answer: "Instruqt pre-provisions sandboxes and runs track-level setup scripts. The initial challenge's setup script runs only when a user clicks 'Launch'. If the challenge setup script is time-consuming (e.g., 3 minutes), users will wait. To mitigate this, move as much configuration as possible to the initial Track setup script and keep the initial challenge setup script minimal."
      mitigation:
        - "Place most configuration in the initial Track setup script."
        - "Keep the initial challenge setup script as simple as possible."
      notes:
        - "User-related environment variables (e.g., `INSTRUQT_USER_ID`) may be empty in track setup scripts during hot start. Leverage challenge setup scripts if these variables are required."
    - title: "How far in advance should I create my scheduled hot start pools?"
      answer: "Generally, schedule hot start pools at least an hour ahead of when needed. For very complex or long-running setup scripts, consider adding more time."
    - title: "Why is my hot start pool filling so slowly?"
      answer: "Instruqt provisions pools incrementally. A small batch is provisioned first, and concurrency increases if successful. Errors detected will reduce concurrent provisioning to prevent large-scale failures."
```

--------------------------------

### Bash Setup Script Example

Source: https://docs.instruqt.com/sandboxes/lifecycle-scripts/add-a-script-to-check-challenge-execution

Example of a Bash setup script to create an empty file and a pre-filled file. These files are then available within the challenge environment.

```Bash
#!/bin/bash 
set -euxo pipefail

# create an empty file called challenge.txt
echo > challenge.txt

# create a pre-filled file called readme.md
echo " # How to create a challenge setup script  " > readme.md
```

--------------------------------

### Example Setup Script: Install Nginx and Clone Repo

Source: https://docs.instruqt.com/sandboxes/lifecycle-scripts/add-software-and-packages-to-a-track

An example bash script for track setup that updates package lists, installs Nginx, and clones a git repository. It uses 'set -euxo pipefail' for robust error handling.

```bash
#!/bin/bash
set -euxo pipefail

apt update
apt install nginx -y

git clone https://github.com/my-web-repo
```

--------------------------------

### Instruqt Challenge Setup Script (setup-host)

Source: https://docs.instruqt.com/reference/cli/configuration-files

A bash script executed after an Instruqt track stops. This example demonstrates basic script setup with error handling and execution flow control.

```bash
#!/bin/bash
set -euxo pipefail

```

--------------------------------

### Install Instruqt CLI with WinGet (Windows)

Source: https://docs.instruqt.com/getting-started/set-up-instruqt

Installs the Instruqt CLI on Windows using the WinGet package manager. It includes commands to install the CLI and verify the installation.

```powershell
winget install instruqt
instruqt
```

--------------------------------

### Instruqt Salesforce Integration Setup Steps

Source: https://docs.instruqt.com/settings/integrations/salesforce

This outlines the essential steps for establishing a secure and functional integration between Instruqt and Salesforce. It covers creating a dedicated integration user, managing permissions via permission sets, authorizing the connection with appropriate OAuth scopes, and subsequently reducing permissions to maintain security best practices.

```APIDOC
Instruqt-Salesforce Integration Setup:

1.  **Create Integration User:**
    *   Create a dedicated Salesforce Integration User with minimal API-only access.

2.  **Create Permission Set:**
    *   Create a Permission Set with temporary broader permissions to facilitate the initial installation and configuration.

3.  **Connect and Authorize:**
    *   In the Instruqt platform, navigate to the integration settings.
    *   Connect to Salesforce and authorize the integration using the correct OAuth scopes.

4.  **Reduce Permissions:**
    *   Post-installation, reduce the Permission Set's access to the minimum required for the integration to function, enhancing security and data protection.

5.  **Configure Data Visualization:**
    *   Implement the steps described for displaying Instruqt data in Salesforce (e.g., Dynamic Related Lists on Leads and Contacts).
```

--------------------------------

### Install Instruqt CLI Manually (Linux)

Source: https://docs.instruqt.com/getting-started/set-up-instruqt

Manually installs the Instruqt CLI on Linux by downloading the latest release, extracting the binary, and placing it in the system's PATH. Includes steps to make the binary executable.

```shell
curl -L https://github.com/instruqt/cli/releases/latest/download/instruqt-linux.zip -o instruqt.zip
unzip instruqt.zip
sudo cp instruqt /usr/local/bin
sudo chmod +x /usr/local/bin/instruqt
instruqt
```

--------------------------------

### Salesforce Integration User Setup

Source: https://docs.instruqt.com/settings/integrations/salesforce

Steps to create a dedicated integration user in Salesforce for Instruqt. This user account will perform all integration interactions, requiring specific license and profile settings for security and functionality.

```Salesforce
1. Navigate to Setup → Users → New User
2. Fill in the following details:
   * Name: Instruqt Integration
   * User License: Salesforce Integration
   * Profile: Minimum Access - API Only Integrations
3. Under Permission Set License Assignments, add:
   * Salesforce API Integration
```

--------------------------------

### Install Instruqt CLI with Homebrew (macOS)

Source: https://docs.instruqt.com/getting-started/set-up-instruqt

Installs the Instruqt CLI on macOS using the Homebrew package manager. It includes commands to install the CLI and verify the installation.

```shell
brew install instruqt/tap/instruqt
instruqt
```

--------------------------------

### Create Instruqt Track with CLI

Source: https://docs.instruqt.com/getting-started/quickstart

Demonstrates how to create a new Instruqt track using the command-line interface, including selecting a template and the resulting file structure.

```bash
instruqt track create
```

```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
```

--------------------------------

### Bash Script Example: Log User and Challenge Info

Source: https://docs.instruqt.com/sandboxes/lifecycle-scripts/scripting-overview

This Bash script demonstrates how to access and utilize Instruqt-provided environment variables, specifically INSTRUQT_USER_NAME and INSTRUQT_CHALLENGE_ID, to log contextual information during a challenge setup. It shows a practical use case for these parameters in script execution.

```Bash
#!/bin/bash
echo $INSTRUQT_USER_NAME started challenge $INSTRUQT_CHALLENGE_ID
```

--------------------------------

### Install Instruqt CLI Manually (Windows)

Source: https://docs.instruqt.com/getting-started/set-up-instruqt

Manually installs the Instruqt CLI on Windows by downloading the latest release, extracting the zip file, and updating the system's PATH environment variable. Requires PowerShell.

```powershell
mkdir scripts
cd scripts
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$($pwd.Path)", "User")
Invoke-WebRequest -Uri https://github.com/instruqt/cli/releases/latest/download/instruqt-windows.zip -OutFile "instruqt.zip"
Expand-Archive instruqt.zip -d .
rm instruqt.zip
# Close and re-open PowerShell window
instruqt
```

--------------------------------

### Check File Creation Script (Bash)

Source: https://docs.instruqt.com/getting-started/quickstart

Bash script to verify if a specific file ('quickstart') exists in the container's filesystem. It uses `set -euxo pipefail` for robust error handling and `fail-message` for learner feedback.

```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
```

--------------------------------

### Instruqt CLI Basic Command Structure

Source: https://docs.instruqt.com/reference/cli/commands

Demonstrates the fundamental structure of Instruqt CLI commands, which typically start with the 'instruqt' directive followed by a command, optional subcommand, and flags. It shows examples of commands with and without subcommands.

```Shell
instruqt challenge create --title "Create a Kubernetes cluster"
instruqt version
```

--------------------------------

### Instruqt Tab Switching

Source: https://docs.instruqt.com/tracks/challenges/using-markdown-editor

Guides users to specific tabs within an interactive lab environment using Markdown links or buttons. The target syntax is `tab-{index}`, where the index starts from zero.

```markdown
If you want to know more, you can use this [link](tab-1) or this [button label="button" variant="success"](tab-1) to switch to our documentation tab.

When you're done, you can get back to the terminal using this [button label="back button" background="#6c5ce7" ](tab-0)
```

--------------------------------

### Deploy Instruqt Track via CLI

Source: https://docs.instruqt.com/getting-started/quickstart

Command to upload a local Instruqt track to the Instruqt platform. This action is only available when using the CLI for track management.

```bash
instruqt track push
```

--------------------------------

### Install Instruqt CLI Manually (macOS)

Source: https://docs.instruqt.com/getting-started/set-up-instruqt

Manually installs the Instruqt CLI on macOS by downloading the latest release, extracting the binary, and placing it in the system's PATH. Supports both Apple Silicon and Intel architectures.

```shell
# Download for Apple Silicon
curl -L https://github.com/instruqt/cli/releases/latest/download/instruqt-darwin-arm64.zip -o instruqt.zip

# Download for Intel
# curl -L https://github.com/instruqt/cli/releases/latest/download/instruqt-darwin-amd64.zip -o instruqt.zip

unzip instruqt.zip
sudo cp instruqt /usr/local/bin
sudo chmod +x /usr/local/bin/instruqt
instruqt
```

--------------------------------

### Cleanup Host Script Example

Source: https://docs.instruqt.com/reference/cli/configuration-files

An example of a cleanup script for a host. This script demonstrates making an HTTP POST request to an API endpoint to delete a resource, likely as part of a sandbox cleanup process.

```bash
#!/bin/bash
set -euxo pipefail

curl -X POST https://my-api.com/delete/resource/X
```

--------------------------------

### Bash Solve Script Example

Source: https://docs.instruqt.com/sandboxes/lifecycle-scripts/add-a-script-to-check-challenge-execution

Example of a Bash solve script to create a directory named 'instruqt'. This script is used for automating challenge completion or when testing a track.

```Bash
#!/bin/bash
set -euxo pipefail

mkdir -p /root/instruqt
```

--------------------------------

### Instruqt Setup Script Exit Codes

Source: https://docs.instruqt.com/sandboxes/manage/hot-start

Setup scripts in Instruqt are used to prepare sandbox environments. A successful script execution, indicated by an exit code of zero, signals that the instance is ready. Non-zero exit codes signify failure, triggering instance termination and reprovisioning.

```shell
echo "Setup script completed successfully"
exit 0
```

```shell
echo "Setup script encountered an error"
exit 1
```

--------------------------------

### Checkout Git Branch

Source: https://docs.instruqt.com/tracks/challenges/using-markdown-editor

Shows how to switch to a different branch in a Git repository, typically used for managing different lines of development.

```bash
git checkout master
```

--------------------------------

### Play Track with Instruqt CLI

Source: https://docs.instruqt.com/getting-started/quickstart

Opens the track in the default browser using the Instruqt CLI. This command initiates the track playback process, allowing users to interact with challenges via their web browser.

```instruqt
instruqt track open
```

--------------------------------

### Start Background Process (Bash)

Source: https://docs.instruqt.com/sandboxes/lifecycle-scripts/lifecycle-scripts-examples

Starts a process in the background, detaching it from the current terminal session. `nohup` prevents it from being terminated by hangup signals, and `disown` further ensures it runs independently.

```Bash
nohup ./myprogram > foo.out 2> foo.err < /dev/null & disown
```

--------------------------------

### Create Instruqt Challenge via CLI

Source: https://docs.instruqt.com/getting-started/quickstart

Command to create a new challenge in an Instruqt track using the CLI. This command initializes a new challenge directory and prompts for basic details.

```bash
instruqt challenge create --title "Creating a text file"
```

--------------------------------

### Instruqt Health Check Example

Source: https://docs.instruqt.com/sandboxes/manage/hot-start

Implement health checks at the end of your setup scripts to verify the sandbox environment is fully functional before it's presented to users. This can involve checking critical services or endpoints.

```shell
# Example: Check if a web server is responding
if curl --fail http://localhost:8080 > /dev/null 2>&1; then
  echo "Web server is healthy."
  exit 0
else
  echo "Web server is not responding."
  exit 1
fi
```

--------------------------------

### Test Track with Instruqt CLI

Source: https://docs.instruqt.com/tracks/manage/test-a-track

Simulates a user starting and completing a track by executing all challenge lifecycle scripts. This command validates track setup and challenge script implementations.

```cli
instruqt track test
```

--------------------------------

### Instruqt Expandable Sections

Source: https://docs.instruqt.com/tracks/challenges/using-markdown-editor

Enables the creation of collapsible sections within assignment content using Markdown headings. Each heading signifies the start of a new expandable section.

```markdown
# Step 1

Click "Explorer" > "NPM Scripts" to open the corresponding panel.
Run the "test" task from it.

The tests should run, and you should see the failing one in the terminal panel.

# Step 2

Update the function in src/sum.ts to correctly return the sum.
At this point, you might want to re-run the tests to see whether the fix is helping.
```

--------------------------------

### Instruqt Challenge Configuration and Assignment (CLI)

Source: https://docs.instruqt.com/getting-started/quickstart

YAML configuration and markdown content for an Instruqt challenge, managed via the CLI. This includes challenge metadata, tab definitions, and the assignment content.

```yaml
---
slug: creating-a-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.
```

--------------------------------

### Long Line Wrapping in Shell Command

Source: https://docs.instruqt.com/tracks/challenges/using-markdown-editor

Shows an example of a shell command with a very long string. The `wrap` option is applied to ensure the text wraps to the next line instead of causing horizontal scrolling.

```bash
echo "This is a very long line of code that will now wrap to the next line instead of scrolling horizontally."
```

--------------------------------

### Instruqt Directory Structure Example

Source: https://docs.instruqt.com/reference/cli/configuration-files

Illustrates a typical file and directory layout for an Instruqt track project. It shows the organization of challenges, track-level configuration files, and track lifecycle scripts.

```markdown
# Example directory layout with track configuration files
.
├── 01-first-challenge          # First challenge
|   ├── assignment.md           # Challenge assignment and configuration
|   ├── check-host01            # Challenge lifecycle scripts
|   └── solve-host01
├── 02-second-challenge         # Second challenge
|   ├── assignment.md
|   ├── setup-host01
|   ├── check-host01
|   ├── solve-host01
|   └── cleanup-host01
├── track_scripts               # Track lifecycle scripts
|   ├── setup-host01
|   └── cleanup-host01
├── config.yml                  # Sandbox configuration
└── track.yml                   # Track configuration
```

--------------------------------

### Bash Cleanup Script Example

Source: https://docs.instruqt.com/sandboxes/lifecycle-scripts/add-a-script-to-check-challenge-execution

Example of a Bash cleanup script to reset a file to an empty state. This script runs asynchronously after a challenge is completed to remove unused artifacts.

```Bash
#!/bin/bash 
set -euxo pipefail

# overwrite with an empty file 
echo > challenge.txt
```

--------------------------------

### Instruqt Hot Start Pool Termination

Source: https://docs.instruqt.com/sandboxes/manage/hot-start

Terminate hot start pools after most users have begun their sessions to save costs. This process cleans up unclaimed instances, while instances already claimed by users remain unaffected.

```APIDOC
InstruqtHotStartPoolTermination:
  description: "Process for ending a hot start pool to optimize resource usage and costs."
  timing:
    recommendation: "Terminate 15 to 30 minutes after the session starts."
  impact:
    claimed_instances: "Instances claimed by users are not affected."
    unclaimed_instances: "Only unclaimed instances are cleaned up."
```

--------------------------------

### Add Assignment Markdown Content (Web UI)

Source: https://docs.instruqt.com/getting-started/quickstart

Markdown content for a challenge assignment, including instructions and commands for learners. This is typically entered into the Description field or a dedicated assignment markdown block.

```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.
```

--------------------------------

### Instruqt Webhook Event Data Example

Source: https://docs.instruqt.com/settings/integrations/integrate-with-hubspot

Example of the data structure received by Zapier from Instruqt webhooks, highlighting the custom parameter 'hsid' which contains the HubSpot contact ID.

```JSON
custom_parameters:
    hsid: 16025401
```

--------------------------------

### Bash Check Script Example (Directory Check)

Source: https://docs.instruqt.com/sandboxes/lifecycle-scripts/add-a-script-to-check-challenge-execution

Example of a Bash check script to verify if a directory exists. It provides feedback and controls challenge progression based on the directory's presence.

```Bash
#!/bin/bash
set -euxo pipefail

echo "Checking if the directory instruqt exists."

if [ -d /root/instruqt ]
then
    echo "The directory instruqt exists"
else
    fail-message "There is no directory named instruqt, did you create it?"
fi
```

--------------------------------

### Create and Push Sandbox Preset via Instruqt CLI

Source: https://docs.instruqt.com/sandboxes/manage/build-sandbox-presets

This snippet demonstrates how to create a new sandbox preset using the Instruqt CLI. It covers running the creation command, providing a name, navigating to the preset's directory, and pushing the preset to Instruqt for publishing.

```bash
instruqt sandbox create
==> Name: <PRESET_NAME>
cd <PRESET_NAME>
instruqt sandbox push
```

--------------------------------

### Instruqt CLI: Push and Open Track

Source: https://docs.instruqt.com/sandboxes/cloud-accounts/aws-accounts

Commands to push your local Instruqt track configuration to the platform and then open it for testing. This allows you to preview and interact with the track as a learner would.

```shell
instruqt track push
instruqt track open
```

--------------------------------

### Wait for Instruqt Bootstrap Completion (Bash)

Source: https://docs.instruqt.com/sandboxes/lifecycle-scripts/lifecycle-scripts-examples

Waits until the Instruqt host bootstrap process completes by checking for a specific file. This ensures that the environment is ready before proceeding with subsequent script steps.

```Bash
#!/bin/bash
set -euxo pipefail

until [ -f /opt/instruqt/bootstrap/host-bootstrap-completed ]; do
    echo "Waiting for instruqt bootstrap to complete"
    sleep 1
done
```

--------------------------------

### Basic Bash Hello World Script

Source: https://docs.instruqt.com/sandboxes/lifecycle-scripts/scripting-overview

A fundamental example of a Bash script that prints 'Hello World' to the console. This demonstrates the basic syntax and execution of a script in a Linux/Mac environment.

```bash
#!/bin/bash
echo "Hello World"
```