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

0

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:

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:

image

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

image

Then click on the second code block:

image

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

image

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:

image

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:

image

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:

image

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:

image

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

image

Finally to complete the scenario, click on Summary.

image

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.

image

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:

image

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

image

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

image

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.

image

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

About Author

Lucas Jellema, active in IT (and with Oracle) since 1994. Oracle ACE Director and Oracle Developer Champion. Solution architect and developer on diverse areas including SQL, JavaScript, Kubernetes & Docker, Machine Learning, Java, SOA and microservices, events in various shapes and forms and many other things. Author of the Oracle Press book Oracle SOA Suite 12c Handbook. Frequent presenter on user groups and community events and conferences such as JavaOne, Oracle Code, CodeOne, NLJUG JFall and Oracle OpenWorld.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.