Track scripts

Add setup and cleanup scripts to your tracks


Track scripts are powerful ways to configure sandboxes before and after a learner uses them. There are two types of track scripts:

  • Setup: Automate commands before a learner gets access to a track

  • Cleanup: Automate commands once a learner completes a track

A typical use case for a track setup script would be to deploy pods in a Kubernetes cluster, or to clone a git repository onto a machine. Track cleanup scripts are not typically needed, but may be useful if you are managing resources outside of Instruqt sandboxes.

Every host in a sandbox has its own setup and cleanup script. Additionally, learners can only start playing the track if all track setup scripts have been completed successfully with an exit code 0.

The longer a track setup script runs, the longer your learners must wait. Reduce wait times by incorporating as much as you can into custom VM images.

Track scripts

Track setup and cleanup scripts are added using the Web UI or the Instruqt CLI.

  1. Click the track you want to add track scripts to.

  2. In the Sandbox menu on the right-hand side of the Track Dashboard page, select Scripts.

  3. In the web editor, determine which host you want to add track scripts to. The hosts will be listed under the Tracks directory in the top-left corner of the editor.

  4. Add a script to the host's setup or cleanup file.

  5. Click Save.

Track setup scripts are executed in advanced as part of hot start pools.

Example setup script

The following is an example track setup script that installs a web server and pulls some code:

set -euxo pipefail

apt update
apt install nginx -y

git clone

Example cleanup script

The following is an example track cleanup script that deletes an imaginary resource via an API call:

set -euxo pipefail

curl -X DELETE -s ""

Setup scripts

There are a couple of things specific to setup scripts that are good to know.

Wait for bootstrap

The track setup script for a host starts to run before Instruqt has finished bootstrapping the host. Use the following snippet to wait for the bootstrap to complete. This snippet ensures that files such as /root/.bashrc will not be overwritten if you change them.

while [ ! -f /opt/instruqt/bootstrap/host-bootstrap-completed ]
    echo "Waiting for Instruqt to finish booting the virtual machine"
    sleep 1

Waiting for the bootstrap to complete is especially important if you plan to modify files like /root/.bashrc in the setup script. Generally speaking, it never hurts to add it in.

Exit on failure

Instruqt marks a sandbox as failed when the track setup script fails with exit code 1. And shows the learner an error if the track plays on-demand. If the sandbox runs hot started, Instruqt discards the sandbox before a learner sees the sandbox. To avoid putting learners in unfinished sandboxes, you should exit the track setup script when a failure happens. When using bash, it is good practice to start your track setup script with the following snippet. The set command ensures that your script will stop on all errors:

set -euxo pipefail

Last updated