Creating a Katacoda scenario – A Tailor Made On Line Tutorial Environment – for example for Jupyter Notebook

Learn new technologies using real environments – right in your browser. Katacoda is an online platform that offers hundreds of scenarios and sandbox environments to learn about and play with different kinds of technologies. Katacoda is special in that it not only offers the handson instructions – it also provides the runtime environment in which these steps can be executed instantly. Examples of such environments: Linux server, Docker engine, Kubernetes cluster and almost anything that can be run as container.

Some of the technologies for which Katacoda has scenarios and playground environments – but this is list is by no means exhaustive:

• Kubernetes
• Docker
• Prometheus
• Linux
• Machine Learning
• .NET (on Linux)
• Git
• Consul
• Istio

When you want to learn about a technology, one of the easiest way to get started frequently is a Katacoda scenario – not least of all because it comes with a ready to play environment, right in your browser.

Katacoda users can also make use of the Katacoda platform to create their own scenarios. The workshop assignments that we create for MeetUp or SIG sessions could in many cases be created as Katacoda scenario that we could work through in our browser. No local installation, no time lost with configuration issues etc. And free.

Try out one of the Playgrounds at Playgrounds – for example Ubuntu, OpenShift, Kubernetes, Ansible, Node, PHP, ASP.NET Core, or one of the predefined scenarios:

• Weavescope – for visualizing Docker Containers and their dependencies (and allowing shells opened in containers from a browser UI)
• A 17-scenario course on Kubernetes
• A 10-step course on Git
• Building and Running MySQL on Docker
• Get going with MongoDB
• First steps with Ansible

In this article I will also show how to create your own custom scenario. I have created a Katacoda scenario for Jupyter Notebook – with a number of hand picked Python libraries and a Notebook git cloned from GitHub. We will be using this environment shortly in a MeetUp at AMIS on Data Analytics.

Create a Custom Scenario

In addition to walking through an existing scenario or playing with a technology in a Playground, you can also create your own scenario – for others to walk through. This is a great way to teach a certain tool, technology component or feature to others.

Let’s first look at a custom scenario I have create, and then at the steps I went through in order to create it.

Custom scenario based on Jupyter Notebook

This is what the final scenario looks like when it is live:

Start scenario – click on first code block to have it executed in the terminal on the right:

Then click on the second code block:

The output of performing this action is shown. When the execution is complete, click on Continue:

The container is running with Jupyter Notebook running inside. To log in to that environment, we need a token. We can read the token from the log-files produced in the container. Click on the next code block to retrieve these logs:

Copy the token shown in the terminal to the clipboard.

Click on the tab Jupyter Notebook – or the link in the text on the left hand side – to open the Jupyter Notebook web console. Paste in the token and press Login:

This will open the Jupyter web environment. Open for example the preloaded notebook Example Word Cloud, click on Cells | Run All and see the result:

Another code block can be clicked on to add another notebook to the running container – by git cloning it from a GitHub repo into the container:

Subsequently, this notebook too is available to run inside the web console:

Finally to complete the scenario, click on Summary.

And you’re done.

Next we will look at how to create such a scenario.

Steps to implement scenario

In order to create a custom Katacoda scenario, you have to sign up for the platform, using a GitHub account, at: sign up. Once you do, a repository will be created in your GitHub environment with an hello world Katacoda scenario, that through webhooks is synchronized with the Katacoda platform. This means you are in business immediately. You can then tinker with the scenario as well as create new ones. See for a good introduction and overview this Medium article.

Once signed up and signed in, you can go to create scenario to create a scenario or edit one you have already started work on.

Katacoda has recently started to offer a CLI tool which which you can “Create and manage courses and scenario from the command-line”.

Documentation on how to create a scenario can be found here.

A list of all available base environments that can be used for scenarios is provided; the list includes Java, C#, Go, .Net Core, Ubuntu, Bash, Kubernetes. Code for some example scenarios is available in GitHub.

Using the Katacoda CLI, I have created a new scenario. Alternatively, make a copy of the demo scenario that Katacoda creates in the Katacoda Scenarios repo in your GitHub account when you sign up. Note: you can configure a different GitHub repo for Katacoda scenarios in your Katacoda profile page.

Create a new folder in the katacoda-scenarios repo – with in it at the very least the index.json, intro.md, finish.md and typically one or more step#.md files. You can add a folder called assets for files you want the scenario player to edit an work with.

Alternatively create a new scenario via the Web UI:

Click on the Editor icon – and define the scenario right here in the browser.

The Git Repo for the Jupyter Notebook scenario contains the following files.

The backbone of the scenario is the index.json file. This file specifies how many steps the scenario entails, what the configuration is of the UI, which files are to be copied to the live scenario environment, and which backend (image) should be used for the scenario environment.  In this case, the imageid is docker, two assets are defined – to scripts that will be used to further prepare the container, and two steps are identified.

The main challenges in setting up this scenario are:

• find the right container image to run in the scenario environment; I settle on jupyter/scipy-notebook
• define a command in the scenario to execute in the terminal in the Katacoda environment to run the container:
  `docker run -p 8888:8888 -d –name jupyter jupyter/scipy-notebook:2c80cf3537ca`{{execute}}
• find out how to copy a script from the Katacoda environment into the running container; it turns out that `docker cp <file> <containerName>:<target folder and file inside container>` command will do this for me
• determine how a script copied into the container can be executed (it needs to be copied and the execute privilege needs to be set); check the runPrep.sh script to see what commands orchestrate the preparation of the container
• compose a script to run inside the container – to install relevant Python packages using PIP and install a Jupyter notebook (by cloning it from GitHub); this script is prepareContainer.sh.
• find out how to allow the user to easily get hold of the logs produced from within the container (in order to learn the token required for accessing the Jupyter Notebook); this can be done simply using
  `docker logs jupyter`{{execute}}
• include a link in the scenario text that will open the Jupyter Notebook in the scenario’s player’s browser window (by opening a URL to port 8888 into the scenario environment); this is done using the following notation: `https://[[HOST_SUBDOMAIN]]-8888-[[KATACODA_HOST]].environments.katacoda.com/` – note the two substitution variables and the port (8888) reference
• find an easy way for the scenario player to add Jupyter Notebooks from GitHub into the running container; this can easily be done with this command: `docker exec -it jupyter git clone https://github.com/Noura/hello-jupyter`{{execute}}`

Check the files index.json, step1.md, step2.md and the two script files in the assets folder to see how these challenges were dealt with.

Resources

The GitHub Repository with the scenario sources: https://github.com/lucasjellema/katacoda-scenarios/tree/master/jupyter-notebook 

The Katacoda Scenario: https://www.katacoda.com/lucasjellema/scenarios/jupyter-notebook

Katacoda Documentation: https://www.katacoda.com/docs