Skip to content

How to Run Jupyter using Docker

In this how-to, we are going to deploy a Jupyter Server on UbiOps, by making use of the bring-your-own-image and port-forwarding functionalities.

A Jupyter Server is a backend component that provides the core services, APIs, and REST endpoints for Jupyter web applications such as Jupyter Notebook, JupyterLab, and others. It runs in the background and manages the creation, communication, and lifecycle of notebook kernels, which are the computational engines executing the code in notebooks.

It allows developers to use the resources of a remote server while storing changes to Jupyter notebook files on a local machine. Also, multiple clients can share Jupyter server resources by connecting to the same instance of such a server. By deploying it on UbiOps developer can expose deployment computing resources and accelerate their product development cycle.

Prerequisites for this how to are having docker and ubiops-cli installed locally. Also, you should install JupyterLab on a computer that will access Jupyter Sever.

The Jupyter server can be deployed on UbiOps in the same way as any dockerized web application. You can find a standard steps to deploy a custom image in this guide: Bring Your Own Docker.

First, we will need to build a docker container and store it as an archive. We can use the following Dockerfile. Also, set NotebookApp.token to authenticate client connections later.

FROM python
RUN pip install jupyter
ENTRYPOINT ["jupyter", "server", "--no-browser", "--port=8888", "--ip='*'", "--ServerApp.disable_check_xsrf=True", "--allow-root", "--NotebookApp.token=<your-token>"]

Run the following commands to generate an jupyter-server.tar.gz image: 

docker build . -t jupyter-server
docker save jupyter-server -o jupyter-server.tar.gz

Then sign in to UbiOps if you have not done that yet. You can follow this page to generate a new user token. 

ubiops signin --token -p "<your-token>" --api https://api.ubiops.com/v2.1

Create a configuration file for the environment and save it as environment_config.yaml. It is important to set environment_supports_request_format to false, because we will interface with the Jupyter server over an open port, rather than via the managed UbiOps request format. 

environment_display_name: Jupyter server
environment_supports_request_format: false
environment_description: Env with running Jupyter server
environment_labels:
    type: jupyter-server

Afterwards, upload the image archive to UbiOps as an environment and wait for build to finish: 

ubiops environments deploy <environment-name> -f environment_config.yaml -a jupyter-server.tar.gz --overwrite -y
ubiops environments wait <environment-name>

Create a configuration file deployment_config.yaml for the Deployment that will run an Environment. It also should not support request format. 

deployment_description: Jupyter server instance
deployment_supports_request_format: false
input_type: plain
output_type: plain
deployment_labels:
  type: jupyter-server

Set up a deployment based on a configuration file: 

ubiops deployments create -f deployment_config.yaml <deployment-name>

Create a configuration for the Deployment Version deployment_version_config.yaml. There you can specify an instance type group. Also set deployment_port to 8888 to match Jupyter server port and public_port to any port you would like to access a server on. 

version_description: Version created via command line.
instance_type_group_name: 16384 MB + 4 vCPU (Dedicated)
static_ip: false
deployment_labels:
  foo: bar
ports:
- public_port: 8888
  deployment_port: 8888
  protocol: tcp

Deploy a version:

ubiops deployments deploy -v <version-name> --environment <environment-name> -f deployment_version_config.yaml -y <deployment-name>

Usage

Check the IP of the running deployment in the UI. In a web app follow a path <your organization> -> <your project> -> Deployments -> <deployment-name> -> <version-name> -> Active instances. There press on a green circle of a running instance. IP information in the UI

Start local instance of JupyterLab connected to a gateway. 

jupyter lab --gateway-url=http://<deployment-ip-address>:8888/ --GatewayClient.auth_token=<your-token>

Now you can use resources of a UbiOps deployment in your local Jupyter notebook. Alternatively, you can integrate VScode with remote Jupyter kernel by following this how to.