(Some Scraggy Notes) Pondering Jupyter Book Interactive Code Deployments

This was originally a considered blog post, but the pile of crap that is WordPress threw it all away so now it’s just notes. F**k you, WordPress.

Jupyter Book is cool. And it’s useful. It does good stuff. I spent an hour writing about it and WordPress threw it away. F**k you WordPress.

I also commented on my workflow (early days: ou-jupyter-book-tools) where I process tagged Jupyter notebooks to generate Myst files that Jupyter Book can render in very rich ways, but WordPress threw it away. F**k you, WordPress.

Jupyter Book would be more useful for me if it let you execute code locally. I wrote several considered reasons why that’s really useful for edu purposes, not least because of the range of book types you can produce (eg books with generated assets but the code removed from final output, how such production workflows are good for quality and maintenance etc.) but WordPress threw it away. F**k you, WordPress.

At the heart of my local Jupyter Book deployment, I see the Jupyter Book being generated from a notebook deployment using a jupyter-server-proxy wrapper (jupyter-book-server-proxy). I explained the thinking and rationale behind this (the reduced dependency on trying to get anyone else to run a Jupyter server for you (which is a massive blovker in education), other than one you might already have access to), but WordPress threw it away. F**k you, WordPress.

One way to hook into a local server is just to have a link from the book page to the notebook running in the local server. In the dozens of executablebooks repos (I was more polite in the original that WordPress threw away (f**k you, WordPress) but I am ratty as hell right now) I can’t find where or how to make the change that would let me specify a simple _config.yml declaration to add an “interactive computing” link, so what I do is set-up Jupyter Book to add JupyterHub links then I string replace the generated files:

<!--
      <a class="jupyterhub-button" href="localhost:8351/notebooks/notebooks/hub/user-redirect/git-pull?repo=http://github.com/crap/path&urlpath=tree/path/notebooks/notebooks/Part 01 Notebooks/01.3 Basic python data structures.ipynb&branch=master"><button type="button"
                class="btn btn-secondary topbarbtn" title="Launch JupyterHub" data-toggle="tooltip"
                data-placement="left"><img class="jupyterhub-button-logo"
                    src="../_static/images/logo_jupyterhub.svg"
                    alt="Interact on JupyterHub">JupyterHub</button></a>
-->

<a class="jupyterhub-button" href="http://localhost:8351/notebooks/notebooks/Part 01 Notebooks/01.1 Getting started with IPython and Jupyter Notebooks - Bootcamp.ipynb"><button type="button"
                class="btn btn-secondary topbarbtn" title="Open local notebook" data-toggle="tooltip"
                data-placement="left"><img class="jupyterhub-button-logo"
                    src="../_static/images/logo_jupyterhub.svg"
                    alt="Interact on local notebook server">localhost</button></a>

Via @choldgraf, here’s a way in to the launch button templates.

Another way of using Jupyter Book is to execute code inline via a remote MyBinder server using ThebeLab. I wrote various bits about how that can work in edu contexts, before exploring what it means to be able to do that with purely local server (rather than remotely launched MyBinder server), but WordPress threw it away. F**k you, WordPress.

My current hack for running the proxied Jupyter Book is to replace the Jupyter Book created ThebeLab settings with local settings:

<script type="text/x-thebe-config">
  {
    requestKernel: true,
    kernelOptions: {
      name: "python3",
      serverSettings: {
        "baseUrl": "http://localhost:8351",
        "token": "letmein"
      }
    },
  }
  </script>
  <script>kernelName = 'python3'</script>

This works, but you get legacy cruft, like the announcement that the kernel has been launched using mybinder; that text is in the ThebeLab js not the Jupyter Book HTML, so to update it would probably require a tweak to the ThebeLab code and _config.yml settings. It’s also lacking an explicit start directory but I haven’t checked to see if (how) the local server route can accept a start directory path; from a quick test using the Binder start directory settings (setting kernelOptions.path), the setting didnlt seem to be picked up by the local server launch ).

I did explore what sorts of setting would be handy a bit more in the orginal post, but WordPress threw it away. F**k you, WordPress.

I tried to explore some of the security issues around using a local server as the code execution environment (albeit given my limited understanding of security stuff) in the two contexts I am interested in — a containerised environment running locally on a student’s own computer with a simple default token (letmein), where I don’t think there are any real issues, and a hosted environment running the same container being an authed JupyterHub entrypoint, where it’s a bit trickier. I tried to explore how the jupyter-book-server-proxy might be able to pick up a token from the server, and pondered how looping that token via public request from the (authed) Jupyer Book via a public http request back to the authed notebook server, but probably just confused the issue. Anyway, WordPress threw it away. F**k you, WordPress.

I finally reviewed what I think is a really exciting prospect, running Jupyter Book with a JupyterLite code execution enviornment purely in a web browser. I set this up by considering how Jupyter Book currently requires a Jupyter server as well as a web server, or a Jupyter server and a jupyter-server-proxied web book, but the pure web-server only play — Jupyter Book Lite or JupyterLite Book — seems really useful in open education, particularly if you struggle to get tech support. (I did review things like the need for a recent browser, good machine and the overhead involved in the initial download, but WordPress threw it away. F**k you, WordPress.) I noted my lack of understanding about the plumbing around Pyolite/WASM whilst describing how jupyterlite has already demonstrated a JupyterLab and RetroLab environment running with a full Python (or javascript, or P5) kernel purely in the browser, and idly wondered about how useful it would be to have something like a ThebeLite or ThebeLabLite version of, or extension to, ThebeLab, but WordPress threw it away. F**k you, WordPress.

Anyway, rather than that considered post, there’s this scraggy notey one. F**k you, WordPress.

PS here’s a minimal demo generated from our Data Managament and Analysis module notebooks…

And here’s an example script for hacking a local installation together [gist]: