mirror of
https://github.com/avatao-content/baseimage-tutorial-framework
synced 2024-11-05 16:31:21 +00:00
50 lines
3.0 KiB
Markdown
50 lines
3.0 KiB
Markdown
# baseimage-tutorial-framework
|
||
|
||
This is the beating heart of TFW – the Docker baseimage containing the internals of the framework.
|
||
|
||
All tutorial-framework challenges are child images of this one: their `Dockerfile`s all begin with `FROM avatao/tutorial-framework`.
|
||
|
||
This document explains the general concepts of TFW and should be the first thing you read before getting started with development.
|
||
|
||
For more on building and running you should consult the `test-tutorial-framework` repo.
|
||
|
||
## The framework
|
||
|
||
The goal of the tutorial-framework is to help content developers in creating interactive tutorials for the Avatao platform.
|
||
|
||
To make this possible TFW implements a robust messaging system and provides several pre-written components built upon it, such as a file editor or a terminal (running in your browser).
|
||
|
||
The foundation of the whole framework is the messaging system connecting the frontend with the backend.
|
||
Frontend components use websockets to connect to TFW, to which you can hook several *event handlers* defining how to handle specific messages.
|
||
|
||
|
||
|
||
### Event handlers
|
||
|
||
Imagine event handlers as callbacks that are executed when TFW receives a specific type of message. For example you could send a message to the framework when the user does something of note.
|
||
|
||
This allows you to define actions triggered on the backend when the user presses a button on the frontend, moves the cursor to a specific area or anything like that.
|
||
|
||
Event handlers use ZeroMQ to connect to the framework. They are as loosely-coupled as possible: usually they are running in separate processes and only communicate with TFW through ZMQ.
|
||
|
||
Most of pre-made event handlers are writen in Python3, but you can write event handlers in any language that has ZeroMQ bindings (this means virtually any language).
|
||
|
||
This makes the framework really flexible: you can demonstrate the concepts you want to in any language while using the same set of tools provided by TFW.
|
||
|
||
### FSM
|
||
|
||
Another unique feature of the framework is the FSM – finite state machine – representing the state of your challenge.
|
||
This allows you to track users progressing with the tasks you've defined for them to complete.
|
||
|
||
For instance you could represent whether the user managed to create a malicious user with a state called `user_registered` and subscribe callbacks to events regarding that state (like entering or leaving).
|
||
|
||
You could create challenges that can be completed in several different ways: imagine a state called `challenge_complete`, which represents when the challenge is completed. Several series of actions could lead to this state.
|
||
|
||
This enables you to guide your users through the experience you've envisioned with your tutorial.
|
||
We can provide a whole new level of interactivity in our challenges because we know what the user is doing.
|
||
This includes context-dependent hints and the automatic typing of commands to a terminal.
|
||
|
||
### Frontend
|
||
|
||
Note that our frontend implementation is written in Angular. It is maintained and documented in the `frontend-tutorial-framework` repository.
|