Mercury — Convert Jupyter Notebook to a web app by adding YAML header

4 min readJan 22, 2022

Convert Jupyter notebook to web app with Mercury

You have a Jupyter notebook with your analysis ready and would like to share it with others. Unfortunately, your friends are not programmers. They don’t have Jupyter notebook installed, not even Python. You would like to give them a few parameters to tweak. How do you share the notebook with them?

I would like to introduce you an open-source framework Mercury that will help you with notebook sharing problem. You can convert the Jupyter notebook to a web app by adding a YAML header. The interactive widgets are generated based on YAML parameters. Your friends can tweak selected variables and click the Run button to execute the notebook.

In this post I would like to show you how to convert Jupyter notebook to web app and deploy it to Heroku (free dyno).

The notebook

I prepared a very simple notebook with Tips dataset from the seaborn package. The notebook screenshot is below.

I want to make the hue parameter to be interactive. User will select the hue value from a list: ["smoker", "sex", "time", "day"].

Install Mercury

Let’s install the Mercury package. You can do it with the following command:

pip install mljar-mercury

We can define the file requirements.txt and add it there. We will add additional package seaborn (for visualization).

The file requirements.txt:

mljar-mercury
seaborn

Mercury watch mode

We can use the Mercury watch command to see how the app will look during its development. Please execute the following command:

mercury watch tips_dashboard.ipynb

You can now open the web browser, and at the address http://127.0.0.1:8000, you will see the Mercury running.

You can click the Open button to see your notebook:

You can see a yellow warning box on the left. Let’s add a YAML header in the notebook. Please do not close the Mercury. It will watch your notebook file, and after each save on the notebook, Mercury will automatically refresh the web app.

Define YAML header

Please add an empty cell at the top of the notebook. You can do it by clicking on the current first cell and selecting Insert from the top menu.

It’s essential to change the type of the cell to RAW.

Let’s define the YAML header:

In the header, we defined:

title, and description,
hide code (a show-code parameter),
the hue — a variable that the user will select from the list.

Let’s update our code to use the hue variable. I will add a separate cell with the hue a variable and its default value. What is more, I will add a Markdown header. The updated notebook’s code is below:

Updated notebook’s code with YAML header

Let’s check the app in the web browser.

You can play with the application by selecting the different hue values and clicking the Run button.

Deploy to Heroku

The web app is ready! Let’s deploy it to Heroku.

We will need a Procfile that will tell Heroku how to run our code. The Procfile will have one line:

web: mercury run 0.0.0.0:$PORT

Please create a GitHub repository and add there your notebook, Procfile and requirements.txt file.

git add tips_dashboard.ipynb
git add requirements.txt
git add Procfile
git commit -am "add tips dashboard"
git push

Let’s create a new Heroku app:

heroku create mercury-demo-1

Deploy to Heroku:

git push heroku main

Congratulations!!! 🎉 🎉🎉 You can now open your app in the web browser.

My app is running at http://mercury-demo-1.herokuapp.com

My code is at https://github.com/pplonski/mercury_demo_1

You can see that I have several apps (notebooks) there. It’s because Mercury has an app gallery built-in so that you can publish several notebooks on a single server.

Our app running at Heroku:

Please notice that there is a Donwload button available. Users can download a final notebook.

Summary

There are several approaches available for sharing notebooks with others (especially with non-programmers). If you would like to share a Jupyter notebook as an application with several parameters that can be tweaked Mercury might be a good choice. The notebook can be converted to a web app by adding a YAML header. Your friends can play with parameters and execute the notebook.

The Mercury framework is open-source with code available at GitHub: https://github.com/mljar/mercury

The Mercury website: https://mljar.com/mercury