# Creating Challenges

# Challenge vs Scenario

A scenario is designed to be a step-by-step guide on how to solve real-world problems.

A challenge is designed to encourage learners to solve the problem for themselves. It should provide tasks, but very little guidance/support on how to complete the task. As the learner completes each task, the UI provides real-time feedback to encourage the learner on what to do next.

If additional support is required, it should refer the learner to existing materials available.

# Configuring Scenario as a Challenge

Source: https://github.com/katacoda/scenario-examples/tree/main/challenges

Scenarios: https://katacoda.com/scenario-examples/courses/challenges

To convert a Katacoda Scenario to a Katacoda Challenge, additional config is required to be added to the index.json along with a new challenge.sh script to define the challenge tasks.

# Changes to index.json

Add "type": "[email protected]", to the file of the JSON root object. This indicates that the scenario will be a challenge, and the version of the challenge API it is using.

At the moment the only valid version is 0.5.

# Starting Challenge

During the challenge initialization, the file /opt/katacoda-background-finished must be created once the challenge environment is configured. This can be done using a background script as shown in the examples using:

echo 'done' > /opt/katacoda-background-finished

In the foreground, once everything has started, start the challenge UI by running the command:

/usr/local/bin/start.sh

A working example is shown at https://github.com/katacoda/scenario-examples/tree/main/challenges.

# Creating Your First Challenge Script

A script called challenge.sh must be created and uploaded as a scenario asset.

The challenge script defines the tasks the user must complete, together with the output for the user and the command to run to validate if the user has completed the section successfully.

Here is a complete example which tests that a file must exist:

function kc_start_tasks()
{
  kc_instructions "Example Challenge - Follow the tasks" 

  kc_task \
      "Task 1: Create a file called /root/challengefile" \
      "Well Done!" \
      "test -f /root/challengefile"


  echo "You successfully completed it"
}

# Challenge API

The challenge.sh script has accessed to a collection of Bash functions that are used to define the challenge.

# start_challenge

This must be included at the bottom of the challenge.sh script to start the challenge when everything is defined.

# kc_start_tasks

An author-defined function that the challenge script will call in order to set up the tasks for the user.

The kc_start_tasks can have multiple kc_task based on how complex the challenge is.

# kc_instructions

Define the header and any initial instructions for the user that might be helpful. This is only meant to be a short hint, such as which Port the application is running on.

This must always be the first function called within kc_start_tasks.

# kc_task

A function to define a task used within kc_start_tasks.

The function has four parameters:

  1. Text to output to the user about the task they need to complete.
  2. Text to output to the user when they have completed the task.
  3. The bash command to run to validate if the user has completed the task. This is run constantly. The user is assumed to have completed the first when the bash command returns an exit code of 0.
  4. An optional 4th parameter is used to define Hints to output to the user based on how long it is taking to complete the task. The value of seconds taken so far is provided as a parameter.

# Hints

The Hint parameter to kc_task is the ability to pass in a Bash function that is called every second with the ability to provide users with a hint or suggestion on how to proceed.

These hints are useful to provide users with an indication of how to unblock themselves if they appear to be taking a long time.

As the Hint functions are run within the environment, they can fully inspect and interact with the state of the environment and provide users with targeted contextually related information. For example, if the task is to deploy an application to Kubernetes, you can inspect if the user has deployed an app but made a mistake with the Container Image used. A hint can be used to prompt the user to fix the Image name before they can continue.

An example of a Hint function is below. This prompts the user after 5 seconds that a Hint will soon be displayed. After 10 seconds, it indicates to use cURL.

function hint1() {
  seconds_sofar=$1

  echo "Debug Hint Task 1: $seconds_sofar"

  if [[ $seconds_sofar -ge 5 &&  $seconds_sofar -lt 10 ]]; then
    echo "Keep going, a hint will be shown soon..."
  fi


  if [ $seconds_sofar -ge 10 ]; then
    echo "Hint: try running the command:"
    echo "curl node01:30080"
  fi
}

# UI Example

During challenge an example of the UI shown to users is:

Katacoda Challenge Example

Once the user has completed the challenge they are shown a success message as defined in the challenge.sh script:

Katacoda Challenge Example Completed

This success message can include links which will automatically be rendered to be clickable.

# Challenge Hints and Tips

# Keep the task focused

A challenge should provide users with focused tasks. If the challenge is complex then it should be broken down into multiple tasks to match real-life.

Any output to the user can include links which will automatically be rendered to be clickable. This can be useful to provide users with additional information or resources.

# 😸 Emoji 🌈

Emoji's are supported and can be used to provide a visualise indication and add some fun/color to the tasks.