Have you ever want to share your Jupyter notebook with non-programming friends? Would you like to hide the code, to not scare them. Give them option to change the input with interactive widgets. In this post, I will show you how to easily share a notebook as an interactive web app with Mercury framework.
Mercury is an open-source framework that is perfect for sharing multiple notebooks as web applications. You can turn a notebook into a web app without changing any code in the notebook. You just need to specify a YAML header as a first raw cell.
You can read more about Mercury at the GitHub: https://github.com/mljar/mercury.
In this post I will show you step-by-step guide how to create very simple notebook and deploy it with Mercury to Heroku (using free dyno).
Setup GitHub repo
Please create a new repo for our project. You can do this by going to https://github.com/new. Below is my filled form to create the repo.
After repository creation you should see a view similar to mine. Please click on a green
Code button and copy the address to clone the repository.
Clone the repository with the command:
git clone email@example.com:pplonski/mercury-simple-demo.git
Set virtual environment and install requirements
Let’s change the directory to project folder. We will use
virtualenv to create virtual environment for our python packages.
virtualenv simple_venv source simple_venv/bin/activate
requirements.txt file with Mercury package:
Please install needed package by running:
pip install -r requirements.txt
This should install required packages and Jupyter Notebook. To use the new virtual environment in the Jupyter run:
python -m ipykernel install --user --name=simple_venv
Create demo Notebook
Please start Jupyter Notebook with the following command:
Let’s create a new notebook. Remember to select a kernel with the name of the virtual environment.
Change the name of the notebook by clicking the
Untitled in the top. I set
greetings as a new notebook name. It will be very simple notebook. Please add a code:
Run the cell by clicking
Run button in top menu or by Ctrl+Enter. You should see
OK. Let’s say our very simple notebook is ready. You would like to share it with friends. Your friends don’t speak Polish, so they would like to see
Hi instead of
Cześć. What if your friends would like to use the application in other than 2022 year?
Add parameters to notebook
We need to parametrize our notebook. Let’s add one more cell at the top (click
Insert in top menu). In the first cell we will define two variables:
greetings = "Cześć" year = 2022
and our greetings message will be in the second cell:
It should look like below:
OK, so our notebook has two variables that can be changed, and the notebook can be executed. Is it ok to share it with firends? If they are comfortable with Python and Jupyter then yes. If they can’t code and don’t know Python, then Mercury is to the rescue.
We will use Mercury to convert our simple notebook to web application with two interactive widgets. Let’s start the Mercury in watch mode to see our app development. Please open separate terminal in the project’s folder and activate the vritual environment:
Then start watch mode in Mercury:
mercury watch greetings.ipynb
It will start the server at http://127.0.0.1:8000/. Please copy the address and paste to your web browser. You should see your notebook.
Open button to see your notebook running as a web app. You should see view similar to the image below:
As you can see from the warning message, we need to define the YAML config in the notebook. Please go to the Jupyter tab and add a new cell at the top of the notebook.
Please set the raw cell content to:
--- title: My app description: My first notebook shared on Mercury params: greetings: input: select label: Select greetings value: Cześć choices: [Cześć, Hello, Hi, Salut, Ciao] year: input: slider label: Select year value: 2022 min: 2021 max: 2030 ---
Your notebook should look like:
Your web app in Mercury should auto-refresh after you save the Notebook.
You can now change widgets values and click
Run to see recomputed values.
If you would like to hide the code, you can add parameter
show-code: False before
params definition in YAML config. To read more about available widgets please check our readme in the Mercury repo.
Deploy to Heroku
I assume that you have Heroku account and Heroku CLI installed. Please login to your Heroku account in the command line:
Let’s create a free dyno by running:
heroku create mercury-simple-demo
The string after the
create command will be the URL address of your app. It should be unique across Heroku. If you just run
heroku create then some random name will be generated.
Let’s set envrionment variables in Heroku:
heroku config:set SERVE_STATIC=True heroku config:set ALLOWED_HOSTS=mercury-simple-demo.herokuapp.com heroku config:set NOTEBOOKS=/app/*.ipynb
We need to add a
Procfile to the project. It will tell Heroku how to run our app. The
Procfile will have only one line:
web: mercury runworker & gunicorn mercury.server.wsgi --bind 0.0.0.0:$PORT --workers 2 --threads 2
Ups, one more thing. We need to add
gunicorn to the
requirements.txt file - it should look like:
OK, let’s add our files to the GitHub:
git add greetings.ipynb git add requirements.txt git add Procfile git commit -am "initial commit with simple notebook" git push
Now we are ready to deploy to Heroku:
git push heroku main
Please wait a little till all packages are installed. And that’s all! Our notebook should be running as a web app available to others.
My is running at http://mercury-simple-demo.herokuapp.com/.
My repository with simple notebook: https://github.com/pplonski/mercury-simple-demo
The Mercury GitHub repository: https://github.com/mljar/mercury