How to Embed Serverless Jupyter Notebooks on Any Website

March 21, 2022

How to Embed Serverless Jupyter Notebooks on Any Website

If you are a programmer and don't know what Jupyter notebooks are, you're living under a rock.

Along with the evolution of data science, Jupyter notebooks also gained traction. Today we use notebooks beyond the scope of data science.

Because it allows us to develop and document simultaneously, I use it as my default environment to prototype any idea. It's a REPL; you get interpreter feedback on your code then and there.

Yet, the accessibility of Jupyter notebooks is bound to its server. You can't let a random person try out your code without incurring a running cost for your servers.

Then came Binder. It allows you to quickly spin up a docker container of your Jupyter server from a Github repo on Google Cloud. Yet, this excellent solution faces funding issues to keep the good work coming.

The solution is to go to an edge computing approach. We need notebooks that run on the clients' browsers and use their resources.

This is what Jupyterlite is built for!

What's Jupyter Lite?

Jupyterlight is a distribution of the Jupyter Lab - server for self-hosting notebooks. It runs entirely on the browser thanks to in-browser Python kernels such as Pyodide.

Jupyter lite doesn't require a remote server. It doesn't require any special software installed on the client-side either. It starts a lightweight environment just in the browser. 

The following links would give you a taste of how they work. 

Jupyterlite with JupyterLab.

Jupyterlite with RetroLab.

You can build one like this and deploy it on free static file hosting solutions like Github Pages. You can then embed them on your website or app. You don't have to worry about traffic and server management. It's all in the client's browser.

Getting started with Jupyterlite.

The easiest way to create an embeddable notebook starts with Jupyterlite's demo Github repository. This repository has pre-built Github actions that automatically pick notebook files and build a static interactive HTML with it.

We need to fork this repository and change its content folder with our notebooks. The Github Actions will automatically start building the production package as we do this. 

Related: How to Run Python Tests on Every Commit Using GitHub Action.

Let's start by attempting to edit any of the files in the repository. You can't do it as you're not playing any role in the repository (Unless you're a contributor to the package.) 

GitHub will automatically fork the repository and create a copy under your profile.

Creating a fork from the Jupyterlite demo repository by attempting to edit any of its files.

Take a look at the content folder. It already has some examples you can copy for your projects. 

When you fork the repository, chances are GitHub Actions aren't activated yet. You can visit the actions tab on your new repository and click the big green activate actions button.

Let's go ahead and change the content repository with our notebook files. To do this the most convenient way is to have a local repository. The following statements will do the trick. 

Since my notebook also uses another Python package, cufflinks for creating beautiful graphics in less code, I also updated the requirements.txt file. When Github Action starts building the static version, it looks for the requirement file and install them to use in the static version.

Related: Create Stunning Visualizations With Pandas Dataframes in One Line of Code

git clone [email protected]:<YOUR GITHUB PROFILE ID>/demo.git
cd demo/content/
rm -rf *
mv <YOUR NOTEBOOK>.ipynb .
git add .
git commit -m 'Test build'
git push origin main

If you visit the actions tab again on the GitHub repository, you'll see that the build process has started.

GitHub Actions build process for Jupyterlite.

Once the build process has finished, you'd see the package available to download. This is a static version of our notebooks.

Downloading build files for Jupyterlite.

GitHub actions picked our commit and automatically triggered the build process. We can also extend this further to complete a CI/CD pipeline.

We can host these files using any static file hosting solution. To test it out, download and extract the built file. And from within the folder, run the following commands.

python -m 'http.server' 8000

Now we can go access our notebook from http://localhost:8000 on any browser.

Embedding notebook on your website.

Embedding a notebook is very straightforward.

Just grab the URL of the hosted notebook and put it as an iframe on your website. The below code is an example.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Test Jupyterlite</title>
</head>
<body>
    <!-- This is where we embedd the Notebook -->
    <iframe 
      src="http://localhost:9000/?kernel=python&toolbar=1"
      width="100%" 
      height="100%"
    >
</iframe>
</body>
</html>

Unfortunately, most third-party sites don't support such embeds. Thus, embedding, as of now, is only possible if you have access to the backend HTML.

Related: 7 Ways to Make Your Python Project Structure More Elegant

Final Thoughts

Running a Jupyter notebook on the client-side and letting them play around with the code is a fantastic idea.

Yet, it comes with several limitations. Firstly any assumption about the client's computational power is not practical. Though I haven't tested this hypothesis, in my opinion, we can use this feature only for demonstration purposes.

Then, Jupyterlite itself is still in beta mode. A stable production release hasn't come yet.

Also, despite their lovely site, I still believe that Jupyterlite's documentation needs improvement.

Yet, it's definitely an excellent start for great client-facing programming environments.

Thanks for the read, friend. It seems you and I have lots of common interests. Say Hi to me on LinkedIn, Twitter, and Medium. I’ll break the ice for you.
Not a Medium member yet? Please use this link to become a member because I earn a commission for referring at no extra cost for you.

How we work

Readers support The Analytics Club. We earn through display ads. Also, when you buy something we recommend, we may get an affiliate commission. But it never affects your price or what we pick.

Connect with us