API Docs
Hugging Face

Deploy Jupyter Notebooks at Hugging Face Spaces with Mercury

One of possible options for Mercury deployments is the Hugging Face (opens in a new tab) Spaces.

What are pros:

  • they have free machines with 2 vCPU and 16 GB,
  • in paid plan they offer different size of machines also with GPU.

What are cons:

  • you can't use Mercury authantication, in HF deployment the SQLite database is used, that's why after machine restart you will have clean database (you lost all your users).
  • your apps will be hosted at hf.space domain, you can't setup custom domain.

If you want to try this option, please create an account at https://huggingface.co/ (opens in a new tab) and let's start.

Create a new Space

Please create a new Space. The Space name will be used to create URL address for your application, so it is good to have some meaningful name.

For Space SDK please select Gradio. Why Gradio? Because Gradio SDK is in fact Python environment which can be used to run any Python application.

By the way, the Gradio (opens in a new tab) is a framework for show-casing Machine Learning models (the Gradio was acquired by HuggingFace company). It is a good choice for making a simple web app that takes input values, runs Machine Learning model and presents computed output. It is not a good choice for general Data Science things (dashboards, visualizations, reports).

Create a new Space at Hugging Face

Add app.py file

Please select Files in the top menu. And click Add file->Create a new file in the empty Space.

Empty Space at Hugging Face

Please add app.py file with below code and click Commit new file to main (should be at the bottom):

import os
from subprocess import Popen
 
command = ["mercury", "run", f"0.0.0.0:{os.environ.get('PORT', 7860)}"] 
worker = Popen(command) 
worker.wait()
App.py file in Space at Hugging Face

The app.py is a file that starts the Mercury in this Space. The 7860 is a default port that is open in the HF Spaces.

Add requirements.txt file

We need to add requirements.txt with required Python packages. Please click Add file->Create a new file.

mercury>=2.2.6
requirements.txt file in Space at Hugging Face

You can add here more packages - depends what you will need in you notebooks (for example pandas, numpy, matplotlib).

Please add a new file by clicking Commit new file to main.

Upload notebooks

The last step is to upload your notebooks. In the Files view, please click Add file->Upload files.

Upload Notebooks in Space at Hugging Face

After notebooks upload, please remember to click Commit changes to main.

App

The last step is to refresh the website and open the App view.

Share notebooks with Mercury in Space at Hugging Face

You can right click on Mercury logo and open app in the new tab. You will see that your app is hosted at domain:

https://username-app-name.hf.space/

In my case it is:

https://pplonski-my-notebooks.hf.space/

You can play with my notebooks at https://pplonski-my-notebooks.hf.space/ (opens in a new tab).

Docker ComposeNgrok