Lifecycle scripts

What is a script?
A script is a set of commands in a command or programming language that execute without compiling. Bash is a popular command language for Linux and Mac. The famous Hello World example looks like this in bash:
1
#!/bin/bash
2
echo "Hello World"
Copied!
Building scripts
As a content developer, you can build scripts with the Web UI or the Instruqt CLI.
What is the lifecycle?
The lifecycle in Instruqt is a series of stages that tracks and challenges pass from setting up till cleaning up.
The track lifecycle consists of the following stages:
Setup 
Cleanup
And the challenge lifecycle consists of:
Setup
Check
Solve
Cleanup
Instruqt scripts and the lifecycle
You can define a script in Instruqt for every stage of the lifecycle:
The track and challenge lifecycle stages
Content developers create lifecycle scripts that run on the sandbox hosts to:
Set up and clean up the sandbox environment and the challenges.
Check and give your learners feedback on their challenge solution.
Automatically solve a challenge when a learner skips a challenge. 
Script features
All lifecycle scripts are optional.
Any scripting language can be used to write the scripts—for example, bash or Python, where bash is the most common choice for Instruqt.
Instruqt determines if a script was successful by checking the returned script exit code:
If the exit code is 0, Instruqt marks the script as successful. 
If the exit code is not 0, Instruqt marks the script as unsuccessful.
Track setup script
A track setup script runs during the track setup stage. Every host within a track has its own setup script. Learners can only start playing the track if all track setup scripts have been completed successfully with an exit code 0.
Use track setup scripts to: 
Download and install specific packages not included in the container or virtual machine image.
Start background services.
Pull down runtime configuration parameters.
Example
See this track setup script for an example of how to download and install a package.
Advanced scenarios
Hot start and track setup scripts
Instruqt starts sandboxes in advance if you have added your track to a hot start pool. In that case, any track setup script also executes in advance, leaving script parameters empty that reference a user.
How to wait for a complete bootstrap
The track setup script for a virtual machine 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
1
while [ ! -f /opt/instruqt/bootstrap/host-bootstrap-completed ]
2
do
3
    echo "Waiting for Instruqt to finish booting the virtual machine"
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. If you want to run setup scripts parallel on all hosts, orchestrate the setup from the track setup script on the first host and use Secure Shell (SSH) to run scripts on other hosts. 
Package updates and large downloads
If track setup speed is essential to you, avoid downloading and installing packages in the setup script. Furthermore, downloading makes the setup less reliable because downloads can fail. And 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
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
1
#!/bin/bash 
2
set -euxo pipefail
Copied!
Preventing scripting errors
Use the online ShellCheck to find and solve bugs in your shell scripts.
Track cleanup script
A track cleanup script runs just before a sandbox environment is cleaned up. And just like with the track setup script, every host has its own cleanup script. 
Use track cleanup scripts to:
Call external systems to trigger a clean-up.
Register that a user has finished with their track. 
Example
See this track cleanup script for an example of removing an installed package.
Challenge setup script
A challenge setup script runs before a challenge starts. 
Use challenge setup scripts to:
Create files that are necessary for the challenge.
Send analytics events.
Example
The following example creates an empty file and a pre-filled file that are available in a challenge:
Bash
1
#!/bin/bash 
2
set -euxo pipefail
3
​
4
# create an empty file called challenge.txt
5
echo > challenge.txt
6
​
7
# create a pre-filled file called readme.md
8
echo " # How to create a challenge setup script  " > readme.md
Copied!
Follow these steps to create a challenge setup script yourself:
🌐 Web UI
💻 Instruqt CLI
1.Open your browser and go to play.instruqt.com.
↳ Instruqt shows your content.  
2.Click the TRACK_NAME of the track where you want to add the setup script.
↳ Instruqt shows the corresponding Track overview page. 
3.Click Edit on the challenge where you want to add the script.
4.Click Scripts followed by setup.
↳ The setup file opens in the editor.
5.Copy the example code and paste it into the editor.
6.Click Save followed by Close.
7.Click Back.
8.Click Build track because you changed a lifecycle script.
9.Click Start track to test the challenge setup script.
1.Open the setup-HOSTNAME file of the challenge where you want to add a setup script in your code editor.
⇨ Replace HOSTNAME with your hostname. For example, setup-container if your host is called container.
2.Copy the example code and paste it into your setup-HOSTNAME file.
3.Save the file and deploy your track:
1
instruqt track push
Copied!
4.Start your track for testing:
1
instruqt track open
Copied!
Challenge check script
A challenge check script runs after a learner clicks the Check button in a challenge. 
Use challenge check scripts to:
Check if a learner solved a challenge correctly.
Provide a fail message and a hint if the learner failed to solve the challenge.
Example
The following example checks if the learner created a directory called instruqt. If the learner created the directory, the script returns a success message, and Instruqt continues with the next challenge. If the learner has not created the directory, the script returns a fail message with a hint to the learner, and Instruqt stays at the current challenge.
Bash
1
#!/bin/bash
2
set -euxo pipefail
3
​
4
echo "Checking if the directory instruqt exists."
5
​
6
if [ -d /root/instruqt ]
7
then
8
    echo "The directory instruqt exists"
9
else
10
    fail-message "There is no directory named instruqt, did you create it?"
11
fi
Copied!
Alternatively, the following example uses an exit code to process the challenge check. If the check fails, line 5 sends a feedback message prefixed with FAIL: to the stdout and line 6 sets the exit code to 1, which marks the script as unsuccessful:
Bash
1
#!/bin/bash
2
# check
3
echo "Checking the solution of the challenge"
4
if [ !$EVERYTHING_WENT_WELL ]; then
5
  echo "FAIL: Your challenge failed because of [REASON]"
6
  exit 1
7
fi
Copied!
Follow these steps to create a challenge check script yourself:
🌐 Web UI
💻 Instruqt CLI
1.Open your browser and go to play.instruqt.com.
↳ Instruqt shows your content.  
2.Click the TRACK_NAME of the track where you want to add the setup script.
↳ Instruqt shows the corresponding Track overview page. 
3.Click Edit on the challenge where you want to add the script.
4.Click Scripts followed by check.
↳ The setup file opens in the editor.
5.Copy the example code and paste it into the editor.
6.Click Save followed by Close.
7.Click Back.
8.Click Build track because you changed a lifecycle script.
9.Click Start track to test the challenge check script.
1.Open the check-HOSTNAME file of the challenge where you want to add a setup script in your code editor.
⇨ Replace HOSTNAME with your hostname. For example, check-container if your host is called container.
2.Copy the code of the first example and paste it into your check-HOSTNAME file.
3.Save the file and deploy your track:
1
instruqt track push
Copied!
4.Start your track for testing:
1
instruqt track open
Copied!
Challenge solve script
A challenge solve script solves the current challenge to allow the learner to skip ahead if you enabled skipping. Challenge solve scripts run in the following scenarios:
When a learner skips a challenge.
When you issue the instruqt track test  command in Instruqt CLI to test a track.
When running the instruqt track test command, Instruqt CLI starts the track on the Instruqt platform and executes the following challenge life cycle scripts:
1.setup
2.check 
↳ Expect failure since the solve script has not been executed yet.
3.solve
4.check 
↳ Expect success since the solve script has been executed.
5.cleanup
Example
The following example solves a challenge by creating a directory called instruqt:
Bash
1
#!/bin/bash
2
set -euxo pipefail
3
​
4
echo "Creating directory instruqt"
5
​
6
mkdir -p /root/instruqt;
Copied!
Follow these steps to create a challenge setup script yourself:
🌐 Web UI
💻 Instruqt CLI
1.Open your browser and go to play.instruqt.com.
↳ Instruqt shows your content.  
2.Click the TRACK_NAME of the track where you want to add the setup script.
↳ Instruqt shows the corresponding Track overview page. 
3.Click Edit on the challenge where you want to add the script.
4.Click Scripts followed by solve.
↳ The solve file opens in the editor.
5.Copy the example code and paste it into the editor.
6.Click Save followed by Close.
7.Click Back.
8.Click Build track because you changed a lifecycle script.
9.Click Start track to test the challenge setup script.
1.Open the solve-HOSTNAME file of the challenge where you want to add a solve script in your code editor.
⇨ Replace HOSTNAME with your hostname. For example, solve-container if your host is called container.
2.Copy the example code and paste it into your solve-HOSTNAME file.
3.Save the file and deploy your track:
1
instruqt track push
Copied!
4.Start your track for testing:
1
instruqt track open
Copied!
Challenge cleanup script
A challenge cleanup script runs after the learner completes a challenge before Instruqt sets up the next challenge. 
Use challenge cleanup scripts to reset script artifacts for the next challenge.
Example
The following example resets an earlier file that the learner changed:
Bash
1
#!/bin/bash 
2
set -euxo pipefail
3
​
4
# overwrite with an empty file 
5
echo > challenge.txt
Copied!
Follow these steps to create a challenge setup script yourself:
🌐 Web UI
💻 Instruqt CLI
1.Open your browser and go to play.instruqt.com.
↳ Instruqt shows your content.  
2.Click the TRACK_NAME of the track where you want to add the cleanup script.
↳ Instruqt shows the corresponding Track overview page. 
3.Click Edit on the challenge where you want to add the script.
4.Click Scripts followed by cleanup.
↳ The cleanup file opens in the editor.
5.Copy the example code and paste it into the editor.
6.Click Save followed by Close.
7.Click Back.
8.Click Build track as you changed a lifecycle script.
9.Click Start track to test the challenge setup script.
1.Open the cleanup-HOSTNAME file of the challenge where you want to add a solve script in your code editor.
⇨ Replace HOSTNAME with your hostname. For example, cleanup-container if your host is called container.
2.Copy the example code and paste it into your cleanup-HOSTNAME file.
3.Save the file and deploy your track:
1
instruqt track push
Copied!
4.Start your track for testing:
1
instruqt track open
Copied!
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 systems.
More examples
See the Helper scripts for some prebuilt scripts for common tasks. And see the Examples for more inspiration.
Script parameters
The Instruqt platform injects a set of environment variables, which are available as parameters in every script:
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.
On a virtual machine sandbox, start any script with #!/bin/bash -l as the first line to load the environment variables. 
Example
The following challenge setup script writes the learner's name and the challenge id to the logging: 
Bash
1
#!/bin/bash
2
echo $INSTRUQT_USER_NAME started challenge $INSTRUQT_CHALLENGE_ID
Copied!
If you play a track that contains this script and view the track log, you will see a log entry with the learner's name and the challenge id.