Package: bertdotbill
Table of Contentsgenerated withDocTocBILL - Bert's Interactive Lesson LoaderOverviewWhat is this and why did you make it?How did you make this?What's it look like?FeaturesQuick StartStep 1 - InstallStep 2 - Create your configuration fileStep 3 - Launch!UsageBuilding the appBuilding the installerDeveloping the appConfiguration FileConfiguration File - DefaultsStoring credentials - OS KeyringWindowsLessonsJinja TemplatingWebTerminalAppendixOS CommandsBILL - Bert's Interactive Lesson LoaderOverviewWhat is this and why did you make it?ThinkKatacoda, but instead of a website with learning examples,
you have a web app that creates hands-on lessons from markdown-formatted, jina-templated documents,
complete with a web terminal for interactive practice.How did you make this?The UI is written inReactJSThe API is usingFlaskMarkdown rendering rendering the optimized HTML assets.What's it look like?Here's a screenshot:Notice the menu dropdown forAvailable Lessons.
The entries are generated dynamically as defined in the app'sconfiguration file.FeaturesDefine your lessons catalog in a YAML-formatted configuration file, e.g.bill.config.yaml.exampleLessonsare Markdown-formatted filesFirst rendered asjinjatemplatesThen rendered as HTMLWeb-based terminals viaxtermjscomponentSee section onWebTerminalLocal Webterminal websocket is also availableOn Windows, viaspyder-terminalcomponentOn Posix-compliant systems (e.g. OSX, Linux), viaaiohttpAs such, you can practice the lesson material with your own OS/systemSimply click on a command, and it will be executed in the underlying shell via web terminal!Default shell is bash (for now)Quick StartStep 1 - InstallNoteYou'll need a minimum python version of 3.7 for the app to workYou can install the app in any of the following ways:Install pip package from pypi.org:pip install bertdotbillInstall pip package from locally cloned repo:git clone https://github.com/berttejeda/bert.bill.git
cd bert.bill
yarn compile:ui:dev
pip install .As you'll notice,nodejsandyarnare also required in this caseThe HTML assets were built using node v16.5.0To install from the locally cloned repo in development mode, do the same as above, but withpip install -e .insteadYou can install the pip package directly from git repopip install git+http://www.github.com/berttejeda/bert.bill.git,but you'll need to obtain the HTML assets and point the app to them, see theAppendixStep 2 - Create your configuration fileUsing the provided sample configbill.config.yaml.example,
you can create your own default configuration file, ensuring the following:The file name isbill.config.yamlThe file is located in one of the app's search paths,
see the section onConfiguration FileYou can always specify the config file explicitly from the cli, as withbill -f path/to/your/config.yamlHTTP(S) are also valid, as withbill -f http://some.website.com/path/to/your/config.yamlStep 3 - Launch!If installed via pip, launch the app from your terminal:billIf installed via pip as adevelopment instance, launch via python withpython ./bertdotbill/app.pyUsageUsage information can be obtained by invoking the executable with the--helpflag, as with:bill --helporpython ./bertdotbill/app.py --help.The help output should be similar to:usage: app.py [-h] [--username USERNAME] [--password PASSWORD]
              [--lesson-url LESSON_URL]
              [--static-assets-folder STATIC_ASSETS_FOLDER]
              [--config-file CONFIG_FILE] [--cors-origin CORS_ORIGIN]
              [--logfile-path LOGFILE_PATH] [--host-address HOST_ADDRESS]
              [--port PORT]
              [--webterminal-host-address WEBTERMINAL_HOST_ADDRESS]
              [--webterminal-port WEBTERMINAL_PORT]
              [--open-browser-delay OPEN_BROWSER_DELAY]
              [--logfile-write-mode {a,w}] [--config-file-templatized]
              [--api-only] [--all-in-one] [--debug] [--verify-tls]
              [--no-render-markdown]
              [run]

Bert's Interactive Lesson Loader (BILL)

positional arguments:
  run

optional arguments:
  -h, --help            show this help message and exit
  --username USERNAME, -U USERNAME
                        Username, if the URL requires authentication
  --password PASSWORD, -P PASSWORD
                        Password, if the URL requires authentication
  --lesson-url LESSON_URL, -url LESSON_URL
                        The URL for the lesson definition
  --static-assets-folder STATIC_ASSETS_FOLDER, -S STATIC_ASSETS_FOLDER
                        Explicity specify the folder for static HTML assets
  --config-file CONFIG_FILE, -f CONFIG_FILE
                        Path to app configuration file
  --cors-origin CORS_ORIGIN, -o CORS_ORIGIN
                        Override CORS origin pattern
  --logfile-path LOGFILE_PATH, -L LOGFILE_PATH
                        Path to logfile
  --host-address HOST_ADDRESS, -l HOST_ADDRESS
                        Override default host address
  --port PORT, -p PORT  Override default listening port
  --webterminal-host-address WEBTERMINAL_HOST_ADDRESS, -wh WEBTERMINAL_HOST_ADDRESS
                        Override default listening host address for the
                        webterminal socket
  --webterminal-port WEBTERMINAL_PORT, -wp WEBTERMINAL_PORT
                        Override default listening port for the webterminal
                        socket
  --open-browser-delay OPEN_BROWSER_DELAY, -bd OPEN_BROWSER_DELAY
                        Override default time in seconds to delay when opening
                        the system's web browser
  --logfile-write-mode {a,w}, -w {a,w}
                        File mode when writing to log file, 'a' to append, 'w'
                        to overwrite
  --config-file-templatized, -fT
                        Render configuration via jinja2 templating
  --api-only            Don't serve static assets, only start API
  --all-in-one, -aio    Run the shell websocket process alongside app
  --debug
  --verify-tls          Verify SSL cert when downloading web content
  --no-render-markdown, -nomarkdownBuilding the development instance of the appInstall and configure prerequisites:Python 3.7+Nodejs (tested with version 16.5.0)Install yarn:npm install yarnInstall modules:yarn installInstall python prerequisites:pip install -r requirements.txtBuild:yarn clean && yarn compile:ui:devLaunch the development instance of the desktop app:yarn start:devUnder the hood, this recompiles the HTML and launchesbertdotbill/app.pyBack to TopDeveloping the appIf you want to make changes to the UI, you'll need to launch the
web instance withyarn start:dev:parcel.Once parcel begins serving up the HTML assets, you
can make changes to UI components and they will re-render on-the-fly.Configuration FileThe configuration file is read by the Flask API process,
and is a YAML-formatted file.As mentioned above, a sample configuration file is provided:bill.config.yaml.exampleIf no configuration is specified via the cli,
the web app will attempt to find the config file in the
following locations:Under ~/bill.config.yamlAdjacent to the app, i.e. in the same folder as the app's scriptUnder ~/.bill/bill.config.yamlUnder /etc/bill.config.yamlDo review the comments in the sample file, as these explain how the sections are interpreted/handled by the UI.Configuration File - DefaultsIf no settings can be found, the app will resort to its defaults,
seedefaults.pyAs such, the defaults settings call for the import of an external config, hosted in mybert.lessonsrepo:seebert.lessons/bill.config.yamlThis external config is where I am listing all of my (mostly) hand-crafted tutorials and learning materials.LessonsAs already mentioned, lessons are Markdown-formatted
files interpreted asjinjatemplates.You can define a lesson catalog in theconfiguration 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 TemplatingTo add to the templating goodies provided by the Jinja library,
I've exposed the OS Environment via theenvironmentkey of
thesessionsobject.This means you should be able to reference any OS-level environment
variable in your lesson content, e.g.# OverviewHello {{ session['environment']['USERNAME'] }}, welcome to Lesson 1WebTerminalEvery 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 isxterm.js.As such, the xterm.js component requires a websocket to a bash process.Bydefault, the bert.bill desktop app
will attempt to connect to a local instance of the websocket viahttp://127.0.0.1:10000/.You can get this websocket running either by:Running thebillorbertdotbill/app.pyscripts with the-aioflag passed inDoing so will launch a local websocket that forwards keystrokes to a bash process on your systemRunning the pre-built docker image:docker run --rm -it --name aiohttp -p 10000:10000 berttejeda/aiohttp-websocket-bashEither of the commands above will start the websocket
and bash process on the target platform on port 10001 by default.Feel free to adjust either approach to your need.Appendix