Lifecycle scripts
Content developers create lifecycle scripts that run on the sandbox hosts to setup and tear down the sandbox environment, give your learners feedback on their solution, or to automatically solve a challenge.
  • All lifecycle scripts are optional
  • You can use any scripting language to write the scripts (bash is the most common choice)

Track setup script

A track setup script runs during the track setup phase. Learners can only start playing the track if all track setup scripts have completed successfully with an exit code 0.
To add track setup scripts using the CLI, create a folder with the name track_scripts and place the setup scripts in the folder with the following name format: setup-<hostname>.
Use the track setup script to:
  • Download and install specific packages that are not included in the container or virtual machine image.
  • Start background services.
  • Pull down runtime configuration parameters.

Hot start and track setup scripts

If you've added your track to a hot start, sandboxes will be started in advance. This means Instruqt starts all the hosts and runs a track setup script on the hosts where you added one. When the track level setup script executes in a hot start, script parameters that reference a user are empty.

How to wait for a complete bootstrap

On a virtual machine, the track setup script starts to run before Instruqt has finished setting up the host. Use this snippet to wait for the bootstrap to complete. This ensures that files such as /root/.bashrc will not be overwritten if you change them.
1
while [ ! -f /opt/instruqt/bootstrap/host-bootstrap-completed ]
2
do
3
echo "Waiting for Instruqt to finish booting the VM"
4
sleep 1
5
done
Copied!

Script execution order

Instruqt sorts the hosts in a track in alphanumeric order and executes the track setup scripts sequentially (one by one).
If you want to run setup scripts in parallel on all hosts, orchestrate the setup from the track setup script on the first host and use SSH to connect to other hosts.

Package updates and large downloads

If setup speed is important to you, avoid downloading data or installing packages in the setup script. This makes the setup less reliable because downloads can fail. Also, your tracks could break at runtime because a newer version of a package is available.
Increase track setup speed and improve the reliability of your track by adding everything you need to the container image or virtual machine image, then use the track setup script only for runtime configuration.

Exit on failure

If the track setup script fails with exit code 1, the sandbox is marked as failed. If the track is played on-demand, the learner sees an error. If the sandbox is provisioned as part of a hot start, the sandbox is discarded before a leaner sees the sandbox. To avoid putting learners in unfinished sandboxes, you should exit the setup script when a failure happens. When using the bash shell it's a good practice to start your script with the following snippet. This set command ensures that your script will stop on any and all errors:
1
#!/bin/bash
2
set -euxo pipefail
Copied!

Challenge setup script

The setup script runs before a challenge starts. Use it to:
  • Create files that are necessary for the challenge
  • Send analytics events

Challenge check script

The check script runs after a learner pressed the Check button.
The platform determines if the script was successful or not by looking at the exit code that is returned from the script:
  • If the exit code is 0, the platform marks the check as successful.
  • If the exit code is not 0, it will mark it as unsuccessful.

Providing feedback to the learner

If the check is unsuccessful, you can provide feedback to the learner. Write a feedback message to stdout, prefixed with FAIL: . This message (after stripping the prefix) is shown to the learner. We also provide a fail-message helper script for this.
Example of a check script:
1
#!/bin/bash
2
# check
3
echo "Checking the solution of the challenge"
4
if [ !$EVERYTHING_WENT_WELL ]; then
5
fail-message "Your challenge failed because of [REASON]"
6
# which is equivalent to
7
echo "FAIL: Your challenge failed because of [REASON]"
8
exit 1
9
fi
Copied!

Challenge solve script

The solve script solves the current challenge to allow the learner to skip ahead if you enable skipping.
The solve script is applied in the following scenarios:
  • When a user skips a challenge
  • By the instruqt track test CLI command
When running the instruqt track test CLI command, the CLI starts the track on the Instruqt platform and executes the following life cycle scripts:
  1. 1.
    setup
  2. 2.
    check (expect failure, since the solve script has not been executed yet)
  3. 3.
    solve
  4. 4.
    check (expect success, since the solve script was executed)
  5. 5.
    cleanup

Challenge cleanup script

The cleanup script runs after a challenge is been completed, before the next challenge is setup.

Track cleanup script

The track cleanup script runs just before a sandbox environment is cleaned up. This allows you to call external systems to trigger a clean up, or to register that a user has finished with their track. The track cleanup script executes on a sandbox host.
To add track cleanup scripts using the CLI, create a folder with the name track_scripts and place the cleanup scripts in the folder with the following name format: cleanup-<hostname>
You can also use lifecycle scripts to publish events to external systems. For example, you can publish an event when a user starts a track. Use the script parameters to correlate these events with data in your own systems.

Script parameters

The Instruqt platform injects a set of parameters using environment variables into every script:
On a sandbox VM, start any script with #!/bin/bash -l as the first line to load the environment variables.
Environment Variable
Description
INSTRUQT_TRACK_ID
The ID of the track
INSTRUQT_TRACK_SLUG
The slug of the track
INSTRUQT_CHALLENGE_ID
(Optional) The ID of the challenge that the script is running on. This can be empty, in case of a track cleanup script.
INSTRUQT_PARTICIPANT_ID
The ID of the participant. This value is guaranteed to be unique for every play of a track, i.e. when a user starts the same track twice, the IDs will differ. Participant is the sandbox identifier, not a user.
INSTRUQT_TRACK_INVITE_ID
(Optional) The ID of the track invite. It is only present if the user accessed the track via an invite link.
INSTRUQT_USER_ID
(Optional) The ID of the user. This value uniquely identifies a user. Empty in a Hot Start track setup script.
INSTRUQT_USER_NAME
(Optional) The full name of the user (as they entered it when creating their account). This value is only be present if the user has given consent to share their details. For example, if a learner started a track through a track invite. Empty in a Hot Start track setup script.
INSTRUQT_USER_EMAIL
(Optional) The email address of the user. This value is only be present if the user has given consent to share their details. For example, if a learner started a track through a track invite. Empty in a Hot Start track setup script.
INSTRUQT_PRIVACY_POLICY_CONSENT
Whether the user accepted the organization's privacy policy.
Last modified 29d ago