Package: btdashboard
Table of Contentsgenerated withDocTocOverviewWhat 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 TemplatingWebTerminalAppendixGithub PagesBert's DashboardOverviewWhat is this and why did you make it?This is my attempt at creating a sort of life dashboard for myself.The aim is to make it as customizable as possible in as easy a way as possible.This project is the successor tobert.bill.As such, the interactive lesson features from that project have been ported over.As with the previous project, the interactive lesson feature was inspired byKatacoda.
And, as with the previous iteration of my work, 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 UIReactJSfor the UI frameworkTailwindCSSfor easier CSSMosaic Lite Admin Dashboardfor the UI layoutReact Reduxfor session state managementThe APIPython FlaskWhat's it look like?Here's a screenshot of the dashboard:Here's a screenshot of the Knowledgebase layout:Here's a screenshot of an interactive lesson:FeaturesThe dashboard cards can be configured via the dashboard configration file:etc/dashboard.yaml.The knowledgebase catalog is configured via the lessons configuration file:etc/lessons.yamlLessonsare Markdown-formatted filesFirst rendered asjinjatemplatesThen rendered as HTMLWeb-based terminals viaxtermjscomponentSee section onWebTerminalLocal Webterminal websocket is also availableUtilizesspyder-terminalcomponentYou can practice the lesson material with your own OS/systemSimplyclickon 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 btdashboardInstall pip package from locally cloned repo:git clone -b ${REMOTE_BRANCH-main} https://github.com/berttejeda/bert.dashboard.git
cd bert.dashboard
nvm install
npm config set timeout 100000
npm install -g parcel yarn
yarn install --frozen-lockfile --network-timeout 100000
yarn compile:ui:dev
pip install .From the above,nvmis used to installnodejs, and we useyarnfor installing package dependencies,
andparcelfor the web build..nvmrcis set to use node v16.5.0To install from the locally cloned repo in development mode, do the same as above, but withpip install -e .insteadYou can also install the pip package directly from git repopip install git+http://www.github.com/berttejeda/bert.dashboard.git,but you'll need to obtain the HTML assets and point the app to them, see theAppendixStep 2 - Adjust your configuration files as neededUnder theetcdirectory, you'll find the following configuration files:app.yamldashboard.yamllessons.yamlsidebar.yamlIf not specified, the app will use the configuration files above.TODO: Documentation on configuration file options.Step 3 - Launch!If installed via pip, launch the app from your terminal:btdashboardIf installed via pip as adevelopment instance, launch via python withpython ./btdashboard/app.pyUsageUsage information can be obtained by invoking the executable with the--helpflag, as with:btdashboard --helporpython ./btdashboard/app.py --help.The help output should be similar to:usage: btdashboard [-h] [--username USERNAME] [--password PASSWORD]
              [--lesson-url LESSON_URL]
              [--static-assets-folder STATIC_ASSETS_FOLDER] [--app-id APP_ID]
              [--app-user APP_USER] [--app-config-file APP_CONFIG_FILE]
              [--lessons-config-file LESSONS_CONFIG_FILE]
              [--dashboard-config-file DASHBOARD_CONFIG_FILE]
              [--sidebar-config-file SIDEBAR_CONFIG_FILE]
              [--cors-origin CORS_ORIGIN] [--logfile-path LOGFILE_PATH]
              [--host-address HOST_ADDRESS] [--port PORT]
              [--webterminal-listen-host WEBTERMINAL_LISTEN_HOST]
              [--webterminal-listen-port WEBTERMINAL_LISTEN_PORT]
              [--webterminal-host WEBTERMINAL_HOST]
              [--webterminal-shell WEBTERMINAL_SHELL]
              [--webterminal-shell-command WEBTERMINAL_SHELL_COMMAND]
              [--open-browser-delay OPEN_BROWSER_DELAY]
              [--logfile-write-mode {a,w}] [--config-file-templatized]
              [--api-only] [--webterminal-only] [--all-in-one] [--no-browser]
              [--debug] [--no-verify-tls] [--no-render-markdown]
              [run]

Bert's Dashboard

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
  --app-id APP_ID, -id APP_ID
                        Specify the App's Identifier
  --app-user APP_USER, -iu APP_USER
                        Specify the App's User
  --app-config-file APP_CONFIG_FILE, -cfa APP_CONFIG_FILE
                        Path to app configuration file
  --lessons-config-file LESSONS_CONFIG_FILE, -cfl LESSONS_CONFIG_FILE
                        Path to lessons configuration file
  --dashboard-config-file DASHBOARD_CONFIG_FILE, -cfd DASHBOARD_CONFIG_FILE
                        Path to dashboard configuration file
  --sidebar-config-file SIDEBAR_CONFIG_FILE, -cfs SIDEBAR_CONFIG_FILE
                        Path to sidebar 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-listen-host WEBTERMINAL_LISTEN_HOST, -wlh WEBTERMINAL_LISTEN_HOST
                        Override default listening host address for the
                        webterminal socket
  --webterminal-listen-port WEBTERMINAL_LISTEN_PORT, -wlp WEBTERMINAL_LISTEN_PORT
                        Override default listening port for the webterminal
                        socket
  --webterminal-host WEBTERMINAL_HOST, -wh WEBTERMINAL_HOST
                        Override the webterminal socket address to which the
                        UI initially connects
  --webterminal-shell WEBTERMINAL_SHELL, -wS WEBTERMINAL_SHELL
                        Override default shell for the webterminal session
  --webterminal-shell-command WEBTERMINAL_SHELL_COMMAND, -wSc WEBTERMINAL_SHELL_COMMAND
                        Override default shell command for the webterminal
                        session
  --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
  --webterminal-only    Don't serve static assets or start API, only invoke
                        Webterminal Websocket
  --all-in-one, -aio    Run the shell websocket process alongside app
  --no-browser, -nobrowser
                        If applicable, don't open the web browser
  --debug
  --no-verify-tls, -notls
                        Verify SSL cert when downloading web content
  --no-render-markdown, -nomarkdownStarting the development instance of the appInstall Python 3.7+Install this project's required version ofnodejs(v18.11.0):nvm installNote that this command implicitly reads the local.nvmrcInstall yarn & parcel:npm install -g yarn parcelInstall node modules:yarn install --frozen-lockfileInstall python prerequisites:pip3 install -e .Launch the development instance of the UI:yarn start:dev:uiLaunch the api and local webterminal process:yarn start:apiUnder the hood, this launchespython btdashboard/app.py --debug --api-only -aio,
seepackage.jsonBack to TopDeveloping the appStarting the development instance of the UI will cause it to reload
whenever you make changes to any of the UI
files under thesrcfolder.This functionality helps increase UI development velocity.I have not yet implemented similar functionality for the API files underbtdashboard,
so you'll have to kill and reload the API whenever you make changes.App 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/lessons.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.These are defined in thelessons.yamlconfiguration file.You can override the location of this file via the appropriate cli parameter.Review the--helpoutput for details.TODOImplement per-lesson credentialsJinja TemplatingTo add to the templating goodies provided by the Jinja library,
I've exposed the OS Environment via theenvironmentkey of a
special variable namedsession.This means you should be able to dynamically load any OS-level environment
variable into your lesson material, e.g.# Overview{% set USERNAME = session['environment'].get('USER') or session['environment'].get('USERNAME')  %}
Hello {{ 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.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.dashboard web app
will attempt to connect to a local instance of the websocket viahttp://127.0.0.1:10001/.You can get this websocket running either by:Installing btdashboard withpip install btdashboardand runningbtdashboard -aioor by installing all requirements and runningpython btdashboard/app.py -aioDoing so will launch a local websocket that forwards keystrokes to a bash process on your systemAppendixConfiguration filesImportant note about the configuration files:Environment variable interpolation is supported, e.g.user: ${USER},You can see this in use in theappconfig fileGithub PagesIf you want to publish the assets from your own fork of this repo:Fork this repoConfigureGithub PagesRunyarn installto initialize the project requirementsRunyarn deployto publish the static assets to thegh-pagesbranch