Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 39 ยท Collaboration and Deployment

Sharing with JupyterHub, Binder and Cloud Notebooks

Compare ways to share notebooks: static HTML, Binder, JupyterHub for teams and classes, and hosted notebooks. Learn architecture, repo2docker files and security trade-offs.

Sending someone an .ipynb file works only if they have Python, the right libraries and the right data. For anything beyond a quick look you need a way to share the notebook together with its environment. This lesson maps the options, from a static page that needs nothing to a multi-user server that gives every student a private workspace.

None of these services can be run from this site, so everything below is read-only description of real tools. The runnable cells are small models of the ideas: choosing a sharing method, and reading an environment specification the way a builder like repo2docker does.

Choose by what the reader needs

Reader needs to... Good option
just read results exported HTML or PDF, or GitHub's built-in notebook viewer
try the code once, no install Binder or a hosted notebook service
work in a persistent account JupyterHub or a managed hosted service
use a dashboard, no code Voila or a web app (see Voila)
rerun it regularly scheduled runs (see Papermill)

Static export is by far the cheapest and safest: nothing runs on your servers. Use it unless people really need to execute code.

Binder: a temporary environment from a repository

Binder (mybinder.org is a free public service) builds a Docker image from a Git repository and starts a short-lived JupyterLab session in the cloud. A reader clicks a badge and gets a live copy with your dependencies installed, no account needed. Sessions end after inactivity, and changes are lost unless the user downloads them.

The builder, repo2docker, looks for configuration files in the repository:

  • requirements.txt for pip packages,
  • environment.yml for conda,
  • runtime.txt or a .python-version-style pin for the Python version,
  • apt.txt for system packages,
  • postBuild for a shell script run after installation,
  • a Dockerfile for full control.
TEXT
my-analysis/
  report.ipynb
  data/sample.csv
  requirements.txt      # pandas==2.2.3, matplotlib==3.9.2
  apt.txt               # (optional) graphviz
  postBuild             # (optional) jupyter labextension install ...

You can run the same builder locally to test: pip install jupyter-repo2docker then repo2docker . builds the image and starts it. Then add a badge to the README with a link of the form https://mybinder.org/v2/gh/<user>/<repo>/HEAD?urlpath=lab/tree/report.ipynb.

Binder is a showcase tool. Keep the repository small, pin dependencies exactly (see pinning dependencies), keep data small and public, and never put secrets there: the environment is public and anyone can read it.

JupyterHub: a server for many users

JupyterHub is the multi-user server. Users sign in, and the hub starts a separate single-user Jupyter server for each of them, with its own home directory and kernels. It is used by universities, research groups and companies.

flowchart LR
  U["Users"] --> P["Configurable HTTP proxy"]
  P --> H["Hub: login and spawning"]
  H --> A["Authenticator"]
  H --> S["Spawner"]
  S --> N1["Single-user server: alice"]
  S --> N2["Single-user server: bob"]
  P --> N1
  P --> N2

The hub decides who may log in and starts servers; the proxy sends each user's traffic to their own server.

The main components:

  • Authenticator: how people sign in (PAM, OAuth with GitHub or Google, LDAP, a shared password for a class).
  • Spawner: how a single-user server is created (a local process, a Docker container, a Kubernetes pod, a Slurm job).
  • Proxy: routes browser traffic to the hub or to the right user server.
  • Configuration: one Python file, jupyterhub_config.py.
Python
# jupyterhub_config.py
c = get_config()
c.JupyterHub.authenticator_class = "github"
c.GitHubOAuthenticator.allowed_users = {"alice", "bob"}
c.Spawner.default_url = "/lab"
c.Spawner.mem_limit = "2G"
c.Spawner.cpu_limit = 1

Two well-known distributions help you start. The Littlest JupyterHub (TLJH) installs on a single virtual machine and suits a class or a small team of up to a few dozen users. Zero to JupyterHub with Kubernetes scales to hundreds or thousands of users with containers, autoscaling and shared storage.

Operating a hub means you now run a service: updates, backups of user data, resource limits so that one person's runaway loop does not exhaust the machine, and a clear policy on what the notebooks may reach on your network.

Other hosted options

Many vendors host notebooks as a service: Google Colab, Kaggle Notebooks, Amazon SageMaker Studio, Azure ML notebooks, Databricks, Deepnote and others. You pay with accounts, usage limits and some vendor lock-in; in exchange, you get GPUs and zero setup. Differences to check before committing: how long sessions last, whether files persist, which packages are preinstalled, how secrets are handled and where the data is stored.

Model the decision

Python Pick a sharing method (decision model)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Real decisions add budget, privacy rules and who maintains the system, but the shape of the reasoning is the same: start from the least infrastructure that meets the need.

What repo2docker looks for

When Binder builds a repository, the first matching configuration decides what is installed. This cell models the detection order on a list of file names.

Python Detect the build configuration (model of repo2docker)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The details differ slightly between repo2docker versions (check its documentation for the exact order), but the principle holds: add files that describe your environment, and the builder follows them.

Security notes

  • A notebook server runs arbitrary code by design. On a shared hub, isolate users with containers or separate system users, and set resource limits.
  • Never publish tokens, passwords or private data in a repository that goes to Binder or a public service. See notebook security.
  • Binder sessions have no private data: assume anything inside is public.
  • Keep a hub behind HTTPS and an authenticator you trust.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Binder do?

    Binder builds an image from the repository's configuration files and launches a short-lived session for each visitor.
  2. 2. In JupyterHub, what does the spawner do?

    The authenticator signs users in; the spawner creates their servers (process, container or pod).
  3. 3. Which file would you add to install system packages for a Binder build?

    apt.txt lists Debian/Ubuntu packages installed before the Python packages.
  4. 4. A reader only needs to see the results of your analysis. What is the simplest, safest way to share?

    A static export needs no running code or servers and carries no execution risk.

Summary

  • Pick the lightest sharing method that fits: static export, Binder, a hub, or a hosted service.
  • Binder and repo2docker read requirements.txt, environment.yml, apt.txt, postBuild or a Dockerfile.
  • JupyterHub has an authenticator, a spawner and a proxy; TLJH suits small groups, Kubernetes large ones.
  • Treat any shared notebook server as a code-execution service and keep secrets out of it.

Next: Voila, Dashboards and Apps