bertdotbill 0.2.5

Bert's Interactive Lesson Loader

Table of Contents generated with DocToc

• BILL - Bert's Interactive Lesson Loader
• Overview
• Features
• Installation
• Building the development instance
• Configuration File
• WebTerminal

BILL - Bert's Interactive Lesson Loader

Overview

Think Katacoda, but instead of a website with learning examples, you have a desktop app that creates hands-on lessons from markdown-formatted documents, complete with a web terminal.

I used the boilerplate from this repo r0x0r/pywebview-react-boilerplate to create the basis for the app.

As such, the UI is written in ReactJS, with the pywebview python package rendering the HTML as a GUI.

This is a similar approach to what Electron accomplishes, but with a much smaller resulting file.

Features

• Define your lessons catalog in a YAML-formatted configuration file, e.g. bill.config.yaml.example
• Lessons are Markdown-formatted files
  1. First rendered as jinja templates
  2. Then rendered as HTML
     
• Web-based terminals via xtermjs component
  See section on WebTerminal

Installation

• From pypi.org: pip install bertdotbill
• From locally-cloned repo: pip install bertdotbill
• From locally-cloned repo, in development mode: pip install -e .
• From git pip install git+http://www.github.com/berttejeda/bert.bill.git

Building the app

• Install and configure prerequisites:
  • Python 3.7+
  • Nodejs (tested with version 16.5.0)
• Install yarn: npm install yarn
• Install modules: yarn install
• Install python prerequisites: pip install -r requirements.txt
• Build: yarn build
• Launch the desktop app: yarn start:gui:dev
  Under the hood, this recompiles the HTML and launches bertdotbill/app.py

Notes for users on Windows 10 x64:

• If you want to be able to open the Developer Console from the Desktop App, you'll need to install
  Microsoft Edge WebView2 Runtime
• Ensure you configure Nodejs as per https://github.com/nodejs/node-gyp#on-windows:
  • Install the current version of Python from the Microsoft Store package.
  • Install tools and configuration manually:
  • Install Visual C++ Build Environment: Visual Studio Build Tools (using "Visual C++ build tools" workload) or Visual Studio Community (using the "Desktop development with C++" workload)
  • Launch cmd, npm config set msvs_version 2017
  • If the above steps didn't work for you, please visit Microsoft's Node.js Guidelines for Windows for additional tips.

Building the installer

You can run yarn build:installer to generate the installer.

Under the hood, the above command calls the setup.sh script to do the heavy lifting.

Once the process completes, the installer file should be located in the dist folder.

Platform-specific notes:

• Windows: The above script calls InnoSetup against the InnoSetup script setup.iss
  As such, you'll need to install InnoSetup for this to work,
  Important: The setup.sh script is written in bash, so it'll only work if you're on a posix emulation environment, e.g. Cygwin, git-bash, etc
• Linux: Not yet implemented
• OSX: Not yet implemented

Back to Top

Developing the app

If you want to make changes to the UI, you'll need to launch the web instance with yarn start:web:dev.

Your changes to UI components will re-render the HTML on-the-fly.

Configuration File

The configuration file is read by the desktop app , and is a YAML-formatted file.

As mentioned above, a sample configuration file is provided: bill.config.yaml.example

The desktop app will attempt to find the config file in the following locations:

• Under ~/bill.config.yaml
• Adjacent to the app, i.e. in the same folder as the app's script
• Under ~/.bill/bill.config.yaml
• Under /etc/bill.config.yaml

Do review the comments in the sample file, as these explain how the sections are interpreted/handled by the UI.

Storing credentials - OS Keyring

The config file allows you to specify credentials in the following jinja format:

auth:
  global:
    username: "{{ session.get_credential('mycredential').username }}"
    password: "{{ session.get_credential('mycredential').password }}"

Under the hood, we are calling a function (get_credential) from the session object.

This function utilizes the python keyring library to retrieve credentials stored in the OS keyring.

Windows

In the case of Windows, the function interacts with the Windows Credential Manager to retrieve the referenced Generic Credentials

As such, the example above will expect a Generic Windows Credential named 'mycredential', with a value filled in for username and password.

Lessons

As mentioned above, lessons are Markdown-formatted files interpreted as jinja templates.

You can define a lesson catalog in the configuration file.

If these files are stored in a password-protected web location, you'll need to specify credentials in the auth.global section of the config file.

Per-lesson credentials are not yet implemented, but will be in a future version.

Jinja Templating

To add to the templating goodies provided by the Jinja library, I've exposed the OS Environment via the environment key of the sessions object.

This means you should be able to reference any OS-level environment variable in your lesson content, e.g.

# Overview

Hello {{ session['environment']['USERNAME'] }}, welcome to Lesson 1

WebTerminal

Every lesson rendered through the app includes a web-based terminal emulator component that allows for practicing the lesson material.

These web terminals are embedded in the user interface, available at its footer and as a slide-in from the right (click Utils to reveal).

As mentioned before, the underlying technology for these web terminals is xterm.js.

As such, the xterm.js component requires a websocket to a bash process.

By default, the bert.bill desktop app will attempt to connect to a local instance of the websocket via http://127.0.0.1:5000/.

To get this running locally, you can invoke the docker image I've prepared via: docker run --rm -it --name aiohttp -p 5000:5000 berttejeda/aiohttp-websocket-bash:1.0.0

The command above will automatically start the websocket and bash process on the container and expose the websocket on your host port 5000.

Feel free to adjust the docker run command to your need, e.g. change the port mapping, but be aware that the desktop app's configuration file must be adjusted to reflect any changes to the way the websocket is accessed.