Track scripts

Add setup and cleanup scripts to your tracks

Overview

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.

🌐 Web UI

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.

💻 Instruqt CLI

1. Track scripts are defined in the <track-name>/track_scripts directory and follow a <type>-<hostname> format. The two types of track scripts are setup and cleanup. For example, to add a track setup script that runs on a host named webserver, you must create a file named setup-webserver in the track_scripts directory. Here is an example structure of a track directory:

   my-track/
       01-example-challenge/
       track.yml
       config.yml
       track_scripts/
           setup-webserver-vm
           cleanup-database-vm

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:

Bash

#!/bin/bash
set -euxo pipefail

apt update
apt install nginx -y

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

Example cleanup script

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

Bash

#!/bin/bash
set -euxo pipefail

curl -X DELETE -s "https://example.com/api/resource/1234"

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.

Bash

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

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:

Bash

#!/bin/bash 
set -euxo pipefail