Jupyter Blog - Docker

CUDA enabled Jupyter Docker Images

2024-04-16T22:08:00+00:00

I am happy to announce that Jupyter Docker Stacks project now provides GPU accelerated Docker images. This allows PyTorch or TensorFlow operations to use compatible NVIDIA GPUs for accelerated computation.

How to find these images

All our images are available on Quay.io registry. We provide CUDA accelerated versions of images are available for tensorflow-notebook and pytorch-notebook.

To use such an image, you have to specify a special prefix tag to the image: versioned CUDA prefix like cuda11- or cuda12- for pytorch-notebook or just cuda- for tensorflow-notebook.

We build pytorch-notebook only for 2 last major versions of CUDA, tensorflow-notebook image supports only the latest CUDA version listed in the officially tested build configurations list. CUDA-enabled images are available on x86_64 platform.

For example, you can use an image quay.io/jupyter/pytorch-notebook:cuda12-python-3.11.8 or quay.io/jupyter/tensorflow-notebook:cuda-latest.

Running the images

To enable CUDA support on Linux host machine, you need to:

have compatible Nvidia GPU
have NVIDIA Linux driver installed
add --gpus all (or --gpus '"device=all"') flag to if you’re using Docker
add --device 'nvidia.com/gpu=all' flag if you’re using Podman

For example, you can run the image like this: docker run -it --rm -p 8888:8888 --gpus all quay.io/jupyter/tensorflow-notebook:cuda-latest.

You can also enable GPU support on Windows using Docker or Podman.

Reaching out

You will find our documentation here.
If you encounter any problems, please, take a look at GitHub issues.
If you would like to improve GPU support in our images, please, reach out here.

Acknowledgments

I would like to thank:

Johanna Reiml, for implementing general variant concept for our images and making it work for pytorch-notebook (PR #2091)
Christof Kaufmann, for making it work for tensorflow-notebook (PR #2100)
Olivier Benz, for helping me out to write this blog post

Updating defaults on mybinder.org

2023-03-09T08:31:00+00:00

This week, we are deploying some updates to repo2docker, the image-building tool that underpins mybinder.org. This may affect your repos. Please get in touch if you have problems! Hopefully this will make things better, more stable, and less surprising overall, but change always breaks something, however hard we work to keep things working.

To highlight the changes:

Python 3.10 is now the default Python version
Python 3.11 is now supported, and new versions of Python should be supported more quickly
If a repo requests an old version of Python (≤ 3.6), it will be installed in a separate environment, as we’ve been doing with Python 2.7 for a long time.
The server implementation is switched from jupyter-notebook to jupyter-server

More detail on each change, the reasons behind them, and their consequences below.

Python 3.11 and separate envs for legacy Python support

When building an image, repo2docker installs packages in one or two environments — the kernel environment where your code runs, and the server environment, which runs the Jupyter server. If you’re using a reasonably supported version of Python, these are actually the same environment. This is the vast majority of repositories on mybinder.org. In order to function properly, we have certain requirements of what goes in the ‘server’ environment. Eventually, those requirements start making it difficult to setup the server environment with an outdated version of Python, as packages march ahead with their minimum required Python (The widely adopted NEP 29 suggested dropping Python 3.7 support in December, 2021). Our solution for this has been to separate the kernel environment from the server environment, so they don’t create a conflict. Until recently, only Python 2 was handled this way (most packages dropped Python 2 support years ago). As part of adding support for Python 3.11, we have expanded this behavior to include Python ≤3.6, so if you are using a ‘legacy Python’, currently defined to be Python ≤3.6, your requested packages will be installed in the kernel environment instead of the server environment. This should only have a noticeable effect if you are installing something with server extension components , which includes anything modifying the JupyterLab or notebook interfaces— those will not be available in the server environment. To address this, you will have to upgrade Python or handle the server extension installation in postBuild . PR adding Python 3.11 and adding Python ≤3.6 to legacy Python versions.

Default Python is now 3.10

The default Python for repo2docker and thereby mybinder.org is now Python 3.10, upgraded from 3.7. 3.10 will be used when a repository does not specify which version of Python to use. Following Python’s own annual release cadence, we plan to update this more regularly in the future, lagging behind Python itself by a version or two. This has no effect on your repos if they specify a Python version, which is why we encourage you to specify your Python version! If you don’t, then your Python version will change over time, probably about once a year. PR switching the default Python.

Now launching Jupyter Server

The default UI for mybinder.org has been JupyterLab for some time, with the classic notebook still available if you specify a url of /tree/or /notebooks/mynb.ipynb. When we rolled out that change, we kept the default server as the jupyter-notebook server, for improved compatibility with existing server extensions. As the newer Jupyter Server has taken over, the situation is becoming reversed — using the older notebook server is now the cause of compatibility issues with server extensions, so we are switching the server to launch jupyter-server instead of jupyter-notebook. The classic UI is still available at the same URLs, thanks to nbclassic. This should have no visible effects, as jupyter-server and nbclassic make a great deal of effort to keep classic notebook extensions working, but some extensions may need an update for jupyter-server compatibility if they haven’t been updated already. Because of where the server is specified, there is no supported way for images to express a preference for the deprecated notebook server (PR switching the default server command.

Introducing repo2docker

2018-12-14T18:24:00+00:00

The Binder Project’s repo2docker tool gives data scientists the benefits of containerization technology without needing to learn Docker itself. To make your repository compatible with repo2docker, you only need to add text files that are already present in many repositories. This means that you get the benefits of containerization, a powerful and complex ecosystem, without having to change your workflow.

repo2docker is a lightweight command-line tool written in Python that takes a path or URL to a git repository and creates a suitable docker image for it. To achieve this it follows the steps that a human would take to do so. The steps are:

Inspect the repository for common “configuration” files (like requirements.txt),
From these well-known files infer the Docker commands to run; and
Build a Docker image.

It has a few more tricks up its sleeve, such as automatically installing RStudio for you when it detects that you are using R. Once the image has been built, a Docker container is created and executed, giving you access to the environment in which the repository author wanted the code to be executed. To achieve this, one needs access to two things: repo2docker and a docker daemon (they do not necessarily have to have docker installed on their local computer).

The JupyterHub team just released v0.7 of repo2docker, so we decided to spend a bit of time explaining what it’s all about.

An example repo2docker workflow. In this case, repo2docker is invoked locally. repo2docker is passed a URL to a git repository (https://github.com/norvig/pytudes). It then clones the repository, discovers configuration files in the repo (in this case, requirements.txt), builds a Docker image with this environment installed, and opens a local Jupyter server to explore and run the contents of the repo.

The guiding principles behind repo2docker

repo2docker is meant to be as lightweight and common-sense as possible. The driving principles behind repo2docker are as follows:

Leverage pre-existing workflows in data science as much as possible. This means using standard configuration files (like requirements.txt) instead of requiring people to learn new configuration patterns.
The shareable unit is a repository or directory containing human-readable files. Not a single file (like a notebook) nor a binary blob (like a built docker image). This means that humans can inspect and extend other repositories meant for repo2docker, and that they can manually do what repo2docker does automatically. No black box.
Be workflow agnostic. repo2docker supports many languages and user interfaces, it can run arbitrary shell scripts that are baked into the image, or it can trigger a script to be run each time a person runs the Docker image.
Be extensible and composable. repo2docker should allow for multiple languages, tools, or workflows to be defined in a single GitHub repository. It should also be relatively easy to extend to support new use-cases.
Enable deterministic outputs. We want repo2docker to make it possible for authors to generate the exact same environment from their repository every time, provided that they follow best-practices in computational methods (like providing specific version numbers for packages). repo2docker can build a specific commit, tag, or branch of a repository, which allows for an image to be deterministically built.

How can repo2docker be used?

Over the last 18 months, we have been using repo2docker in production to automatically generate images that run repositories for mybinder.org.
It is used to build around 1000 unique repositories every week. The core functionality has proven itself and is considered production ready.

Over the last year, we’ve seen a few major use-cases come out of repo2docker:

First, it can be used as a part of production systems like BinderHub. BinderHub automatically uses repo2docker to build images that run a user’s environment, and lets them share links that let others interact with the image.

Second, repo2docker can be used to build an image for use with a JupyterHub. For example, teachers have used repo2docker to convert their GitHub repository with course materials into a runnable Docker image that students access via a shared jupyterhub in the cloud.

Finally, repo2docker has been used by individuals who wish to build reproducible images from their local work. repo2docker can optionally run a Jupyter server from within the built image, which makes it possible to verify the results of analyses in an environment that was built solely from the configuration files present in the repository.

What next?

We think that repo2docker serves as a useful tool for the community and that it is an important part of the large reproducible scientific software stack. It gives data scientists the benefits of containerization technology without needing to learn a new tool like Docker. It achieves this by being a lightweight command-line tool written in Python that automates the creation of the environment in which the authors of a piece of software wanted it to be executed.

We’d love to see the repo2docker community grow, and for more
languages, interfaces, use-cases, and workflows to be supported
with repo2docker’s build pack system. Let us know what you think!

repo2docker is primarily maintained by the JupyterHub and Binder teams. If you’d like to get involved with the community or want to learn
more about the tool, reach out! Check out these links for more information:

Note*: some folks might be wondering why we developed repo2docker instead of contributing to a pre-existing containerization tool such as the excellent* source2image project. We take the decision to create new open-source tech very seriously, and wrote a blog post about our decision to do-so in this case: http://words.yuvi.in/post/why-not-s2i/

Binder 2.0, a Tech Guide

2017-11-30T16:01:00+00:00

Authors: The Binder project is comprised of many individuals within and outside of the core Jupyter team. A list of members that contributed to this post is at the end of this article.

Note: this post focuses more on technical changes in the Binder 2.0 reboot. For a post about user-facing features and future plans, see this eLife blog post.

We are undergoing a dramatic increase in the complexity of techniques for analyzing data, doing scientific research, and sharing our work with others. In early 2016, the Binder project was announced, attempting to connect these three components. A blogpost in eLife described a vision where scientists could specify dependencies along with a collection of Jupyter notebooks. Binder builds a Docker image from these dependencies, and provides a URL where any user in the world can instantly recreate this environment.

Want to see it in action? Click the button below.

With this post we are proud to announce the next version of Binder. It aims to be more modular, more flexible, more stable, faster, and more extensible than its predecessor. Powering this version of Binder is a collection of tools in the Jupyter ecosystem. Since being released, the Binder project has learned many things about implementing fast, flexible online deployments. In addition, its vision has expanded to include not only Jupyter notebooks, but many other computational workflows. You can access an open beta version of this deployment here:

mybinder.org

You can find a list of sample repositories to learn how to create “Binder”-ready repositories here:

github.com/binder-examples

You can also see what the Binder community has been up to in creating their own repositories by checking the GitHub Binder topic:

https://github.com/topics/binder

Give it a shot, build some repositories, and importantly, tell us what could be improved on our GitHub repo. Below we’ll describe a bit about what’s new.

The new Binder UI. Users input a URL to a git repository (or specify a specific branch/tag/commit). Upon clicking “launch”, you will be directed to a live environment where you can interact with the code.

What’s new?

First off we’ll describe how the experience will change for users. The short answer is: not much. The goal of Binder is still enabling you to intantly create interactive and shareable repositories. We’ve completely rebuilt the backend of Binder, but we’ve made minimal changes to the front-end user experience.

The biggest difference you should notice is that Binder is both faster and more stable. You’ll still be able to generate Binder links from a git URL from a single web-page. However, there are a few key differences:

New Default Environment

Old versions of Binder were based off of a Docker image that contained a fairly heavy computational environment. The new Binder deployment makes minimal assumptions about what environment you want installed, by default the only thing that will be installed is the Jupyter Notebook and Python 3. This means you’ll need to be more expressive in the dependencies you include in your dependency files. For example, if you want numpy or matplotlib, you should specify them in a requirements.txt or environment.yml file. Since you’re explicitly listing your requirements it makes reproducing your work more reliable, and allows the Binder infrastructure to change more freely without breaking your repository code.

New URL structure

The new URL structure for Binder follows the following convention:

https://mybinder.org/v2/gh/<org-name>/<repo-name>/<branch|tag|hash-name>?filepath=<path-to-file>

For example, below is the URL for a basic Binder-ready Python 3 repository, it includes basic information about the repository:

https://mybinder.org/v2/gh/binder-examples/requirements/master

You can also specify parameters that do things like point users to a particular file or initialize a user-interface. For example, the following URL starts JupyterLab once users click the link:

https://mybinder.org/v2/gh/binder-examples/jupyterlab/master?urlpath=lab

In each case, note the gh at the very beginning — this specifies that the git URL exists on github.com. It is possible to build new URL parsers for other online repositories such as BitBucket, osf.io, or any other provider. We are currently focusing on Git and GitHub, but nothing prevents Binder from being compatible with other kinds of content providers. Shortly before this blog post we added support for arbitrary git URLs to binderhub, so watch this space.

Specify a specific branch / tag / commit

Also notice that in the URL above you can specify a branch, tag, or commit hash for the Binder image. This allows you to ensure that a Binder image will always remain the same (if you specify package versions properly). This is a crucial step for reproducibility and maintaining consistency in how users experience the files in your repository.

Notice that in the URL above you can specify a commit hash or git tag for the Binder image. This hash is unique to the state of the code at the moment that the commit was made, ensuring that Binder can rebuild the exact same environment any time. Note that if authors don’t want to guarantee the same reproducible environment, they can specify a branch and BinderHub will resolve it to the latest commit hash before building the environment.

Binder auto-building

When a git repository is launched, Binder will now check whether an image has already been built for that repository at the same commit hash. If it has, then Binder will skip the building process and take you straight to a JupyterHub instance that serves this image.

If the image hasn’t been built, then it will automatically be generated before sending the user to JupyterHub. The only difference will be the amount of time it takes before entering the JupyterHub environment. This means that authors no longer need to explicitly build their Binder images when they update a branch. The next time someone clicks a Binder link, it will happen automatically. If you don’t want this behavior, be sure to point Binder to a specific tag or commit hash, rather than a branch name or tag. For example, here’s a Binder URL that will always point to the same commit hash:

https://mybinder.org/v2/gh/wildtreetech/explore-open-data/binder20-elife

While this URL points to a branch, and will thus be re-built each time a new commit is made to that branch:

https://mybinder.org/v2/gh/wildtreetech/explore-open-data/master

More options for dependency files

Users often want to specify a computational environment that is more complex than a simple list of Python requirements. While this is possible by specifying a Dockerfile, it’s often an overly-complicated solution to this problem. Binder now uses repo2docker to build a Docker image from your repository. This makes it possible to specify a more complex environment with text files. For example, you can use an apt.txt file to install packages with apt-get, or use a file called postBuild to define shell commands that are run before generating the Docker image (e.g. for downloading some data or running scripts). See the repo2docker documentation for a list of files that are supported with Binder.

For a selection of examples that show off how to specify dependencies take a look at the example gallery: https://github.com/binder-examples

More user interfaces

The JupyterLab interface running on Binder. You can access the JupyterLab demo repository at ``mybinder.org/v2/gh/binder-examples/jupyterlab/master?urlpath=lab

The previous iteration of Binder only supported the classic Jupyter Notebook user interface, while the new deployment will additionally support RStudio and JupyterLab. Because of the extra build configuration files specified above, you can also utilize more tools in the Jupyter widgets ecosystem, such as the RISE plugin for interactive presentations or the appmode plugin to generate interactive apps from your repository. We also welcome contributions to add support for other user interfaces.

More online repository providers

While GitHub is a fantastic repository of open-source code, it’s not the only repository. The new Binder deployment makes it straightforward to adding support for new sources of code (for example, GitLab, the OSF, or even non-git codebases). Currently GitHub is the only supported source for code, but we welcome contributions enabling support for new sources.

We’re excited about this next step in Binder’s development, and hopeful that we can build a community around this powerful set of tools. Don’t hesitate to open an issue or pull request on our GitHub repository, or to reach out via our Gitter channel. We look forward to seeing what comes next, and to continue enabling reproducible and open workflows in data science and research.

For developers

The next few sections are meant for developers interested in deploying their own Binder, or for those interested in the technical details behind the new deployment.

Tech components

The three main technical components behind the new Binder backend are:

BinderHub, currently on display at mybinder.org and contained in the binderhub repository.
repo2docker, a tool that converts a code repository into a Docker image with an environment specified via dependency files (e.g., requirements.txt).
JupyterHub, which hosts user instances with a server in the cloud. We use a distribution of JupyterHub that runs on top of Kubernetes.

For more information on the infrastructure behind Binder, see the documentation.

A prototype of RStudio running in a Binder. This is currently support with a Dockerfile, and we are working on supporting R build files natively. You can access this repository at: <https://mybinder.org/v2/gh/binder-examples/dockerfile-rstudio/master>

Kubernetes

Binder now also heavily relies on Kubernetes for scaling our image building service and the JupyterHub. Kubernetes is massively scalable and has a strong community of developers behind it. Moreover, Kubernetes is cloud-agnostic. It can be run on Google Cloud, Microsoft Azure, and AWS among others, as well as on your own bare metal hardware if needed. Because BinderHub is built to run on top of Kubernetes, you can deploy Binder off of any of these resources as well (see below).

Deploying your own Binder server

While mybinder.org will continue to exist as a public service, we hope to see new Binder deployments for many different use cases in the wild. One of our primary goals is to make it easier for users to deploy their own Binder servers. This is relatively straightforward by following the instructions on the BinderHub documentation, which are currently under active development to make ongoing improvements as the Kubernetes technology evolves. We’re continuously updating these steps to make them as clear as possible, so please don’t hesitate to open an issue or a pull request on our github repository and make suggestions.

We would love to see others deploy their own BinderHub servers, either for their own communities, or as part of a federated public service of BinderHubs.

Future development

This is the just the beginning of new features and improvements to Binder. We’re working hard to grow an open-source community around these tools, and we encourage issues, comments, and PRs on the BinderHub, repo2docker, and JupyterHub repositories. We look forward to growing the Binder ecosystem, and we’re excited to see all of the Binders that people design.

Acknowledgements (alphabetical order)

C. Titus Brown (UC Davis), Matthias Bussonnier (UC Berkeley), Jessica Forde (UC Berkeley), Brian Granger (Cal Poly), Tim Head (Wild Tree Tech), Chris Holdgraf (UC Berkeley), Andrew Osheroff (Google), Naomi Penfold (eLife Sciences), M Pacer (UC Berkeley), Yuvi Panda (UC Berkeley), Fernando Perez (UC Berkeley), Min Ragan-Kelley (Simula Research Laboratory), and Carol Willing (Cal Poly). The Binder project is currently being funded from a grant from the Moore Foundation.