Customizing Environments with Scripts

Within each environment, users have the correct permissions to install any additional packages (via Apt/Yum/NPM/pip) required by the lab. Commands can be run automatically in the foreground and background when a lab starts and when a step loads.

Background Scripts

Running commands in the background can create a cleaner user experience by hiding noisy and confusing console output from the users. As they are running in the background, any background scripts shouldn’t prompt the user for input (such as confirmation when installing packages).

Background scripts are provided to the intro page or step via the "background" option in the lab’s index.json file. For example, if you wanted to run background.sh behind the intro page, you would include the following:

"intro": {
    "text": "intro.md",
    "background": "background.sh"
}

Foreground Scripts

As with background Scripts, scripts can be run automatically in the foreground allowing users to see the output. This can be useful for displaying progress about the environment configuration and blocking the user before they can continue successfully. For an improved user experience, scripts with a lot of output should be piped to /dev/null or be run in the background.

Foreground scripts are provided to the intro page or step via the "foreground" option in the lab’s index.json file. For example, if you wanted to run step2-foreground.sh at the beginning of the second step, you would include:

{
    "title": "Scripts Example",
    "text": "step2.md"
    "foreground": "step2-foreground.sh",
}

Asynchronous and Synchronous Scripts

Sometimes the learner needs to be blocked from proceeding until a background script finishes. In this case, using files as notifications can be useful.

For example, the following is a background script that is running:

#!/bin/bash

echo "This is a background script with a long running process"

sleep 10

echo "done" >> /opt/.backgroundfinished

The foreground script waits for the file to be created. After the file exists, the while loop finishes and the user is allowed to access the terminal:

echo "Waiting to complete"; while [ ! -f /opt/.backgroundfinished ] ; do sleep 2; done; echo "Done"

This can be further improved by displaying a Progress Spinner to the user. An example can be found in https://katacoda.com/scenario-examples/scenarios/displaying-progress-spinner and at https://github.com/katacoda/scenario-examples/tree/main/displaying-progress-spinner.