Share your Notebook as a website in a couple of lines!

Photo by Kyle Sudu on Unsplash

Introduction

For a couple of weeks, when I was listening to TWIML AI Podcast with SAM CHARRINGTON, he was talking with his guest about the evolution of AI and how it is overriding the business nowadays — his guest mentioned something related to Jupyter Notebooks;

“It will be fabulous if I can share my Notebooks as a webpage since I have to redo all the work from scratch if I have a minor issue in my post.”

His words touched me. If I want to share my work with someone, he has adjustments — I have to investigate my kernel and start adjusting my notebook again.

Sound painful to most of the readers, right!? Not anymore!

Mr Steve Nouri ( Chief Data Scientist and Co-founder of iN2iTY Lab and Founder of AI4Diversity) shared a post from a week ago articulating a new framework that brings the solution to most Data scientists & AI practitioners,

Steve Nouri on LinkedIn: #innovation #artificialintelligence #datascience | 60 comments | +1.1k Likes

which is Mercury!

Image by Piotr from Mercury

What is Mercury?

Mercury is Web Framework that allows you to share your Notebooks with interaction tools (optionally) added to your notebook connected with your variables and hosted for free!

Capture from Mercury demo website

How to Start with Mercury?

It is simpler than you think, first; you’re going to download the package:

• Method 01:

You can install Mercury directly from the PyPi repository with pip command:

pip install mljar-mercury

• Method 02:

Installation from GitHub:

pip install -q -U git+https://github.com/mljar/mercury.git@master

Let’s Give it a shot!

1. Let’s define some basics and concepts.

• First, you need to define a header into your notebook — to create the header; you need to select the cell type as Row:

Capture by Author

• Second, you need to define global variables in your notebook, if you’re going to use interaction tools (Optionally).

This table contains some of the Interaction tools corresponding to its YAML script with an image to each script & the interaction tool:

Table built by Author

Notice: these are not the only variables you can use in Mercury, but we can use all the YAML based tools. Check this link for more tools you can add to Mercury — Define widget with YAML

2. Build our first local Application

• We’re going to build our local application using this demo.

First, we’re going to clone the application using

git clone https://github.com/pplonski/mercury_demo_1.git

second, we’re going to install the prerequisites using requirements.text

Notice: if you faced any issue of not having the plot shown in your notebook, please follow the guides of how you can install the `plotly` extension in Jupyter Lab/Jupyter Notebook.

A. Explain the header

• The header contains title, descripion , show-code: False (It means — in the notebook, you don’t need to show the code but run it in the background of the framework.), and params (It contains 2 `select` types parameters that allow you to select multiple options simultaneously.)

Parameters of nationalities – Capture by Author

Parameters of clubs — Capture by Author

B. Upload the notebook to Mercury

• First, you need to run the server by:

mercury runserver --runworker

Capture by Author

You will find that the server is empty and it tells you to add your notebook

• Second, open a new terminal and add your notebook to Mercury by:

mercury add <path to notebook>

Capture by Author

• Third, refresh the page of your Mercury page now!

Capture by Author

C. Delete the notebook from Mercury

• you can do that easily by creating createsuperuser local login account

mercury createsuperuser

Capture by Author

• Then go to your browser and insert admin ad the end of your localhost URL

http://127.0.0.1:8000/admin

Capture by Author

• Login and then select Notebooks

Capture by Author

• Select the app

Capture by Author

• Then, Delete

Capture by Author

3. Immigrate your app to the production

• Running an application on production is challenging for most people who just started their journey in Data Science or AI overall, so Mercury thought about that. Now you can immigrate your notebook application in production.

Mercury is available for production on any cloud provider.

There are currently two guides:

• AWS
• Heroku

Let’s Start with Heroku

Heroku is a cloud platform as a service supporting several programming languages. One of the first cloud platforms, Heroku has been in development since June 2007, when it supported only the Ruby programming language, but now supports Java, Node.js, Scala, Clojure, Python, PHP, and Go. Wikipedia

First, you need to signup on Heroku to have your secret key

Second, go to The Heroku CLI to install Heroku command-line interface so we can create our app from the terminal.

Third, prepare your application for having its journey to Heroku. The application I will deploy to Heroku is dashbot.

Capture by Author

you can clone the project using

git clone https://github.com/AI-Ahmed/dashbot.git

Steps to Deploy Mercury Dashbot

1. Let’s go to the project directory and login to Heroku using

heroku login

2. create our app inside Heroku using

heroku create mercury-dashbot

After this line, you will notice that your application has created an available in specific IPs

Capture by Author

3. Let’s now obtain our URL by

heroku open <link-of-app> -a <app-name>

Capture by Author

4. Now, let’s add our app.

Notice: you need to make sure that you’ve listed the requirements of the application inside .txt file

Capture by Author

5. Add .env file in your main directory to have your host and notebooks’ information

ALLOWED_HOSTS=mercury-dashbot.herokuapp.com
SERVE_STATIC=True
NOTEBOOKS=/app/*.ipynb

Please set ALLOWED_HOSTS it to your app address. In my case, it was mercury-dashbot.herokuapp.com . I set the NOTEBOOKS variable to point to all *ipynb files in the project directory. The /app/ directory is used because it is a path of notebooks after deploying to Heroku.

6. We need to set our environment variables in the Heroku dyno. We can do this by running the following command:

heroku config:set SERVE_STATIC=True -a <app-name>

7. This needs to be repeated for all variables. The alternative is to use the following command that will set all env variables from the .env file:

heroku config:set $(cat .env | sed '/^$/d; /#[[:print:]]*$/d') -a <app-name>

Notice: you can also add the variable using dashboard settings

Capture by Author

8. Before deployment, we will need to create Procfile that will tell Heroku how to run Mercury. It will have one line:

web: mercury runserver --runworker 0.0.0.0:$PORT

Capture by Author

9. Let’s deploy the whole app now!

• Create a new Git repository

Initialize a git repository in a new or existing directory

cd my-project/
git init
heroku git:remote -a <app-name>

• Deploy your application

Commit your code to the repository and deploy it to Heroku using Git.

git add .
git commit -am "deploy my application"
git push heroku master

Application

Capture by Author

To test the project, you would find the line here: https://dashbot-mercury.herokuapp.com/

For Admin Panel

To access the Admin Panel in the Mercury you need to define three more variables in .env file:

DJANGO_SUPERUSER_USERNAME=your_user_name
DJANGO_SUPERUSER_PASSWORD=your_secret_password
DJANGO_SUPERUSER_EMAIL=your_email

Please add the above to the .env and to the Heroku with heroku config:set command.

Notice: Make sure not to add your .env file inside your app directory while you’re pushing it to master.

Django SECRET_KEY

• For better security please set your SECRET_KEY in .env file and apply changes to Heroku.

SERVE_STATIC=False
DJANGO_SUPERUSER_USERNAME=username
DJANGO_SUPERUSER_PASSWORD=password
DJANGO_SUPERUSER_EMAIL=emailaddress@host.com
SECRET_KEY="x3%q8fs(-q3i(m&=e1g%9xtvcn*q!c%i@v0*ha4@ow2crdktpw"

You can generate SECRET_KEY with the following command:

python -c ‘from django.core.management.utils import get_random_secret_key; \
 print(get_random_secret_key())’

Lastly, Data Science and AI are now one of the most potential jobs in the industry. Having a framework that facilitates the way to share your exciting and mindblowing notebooks, not just that but with interaction, tools are something out of sacking, every data scientist and AI practitioner are looking for something like that to share their new tactics and their thoughts.

Take the step now and try Mercury, to build your website in just a couple of lines!

References

• https://github.com/mljar/mercury
• Mercury (piotr-data-science-portfolio.herokuapp.com)
• https://github.com/mljar/mercury/wiki/Deploy-to-Heroku
• https://devcenter.heroku.com/articles/heroku-cli-commands