├── .gitignore ├── doc ├── _static │ └── images │ │ ├── logo.png │ │ └── favicon.png ├── environment.yml ├── Makefile ├── more-info.rst ├── reproducibility.rst ├── reliability.rst ├── status.rst ├── user-guidelines.rst ├── index.rst ├── introduction.rst ├── parse_readmes.py ├── using.rst ├── conf.py ├── dockerfile.rst ├── faq.rst └── sample_repos.md ├── readthedocs.yml ├── .github └── ISSUE_TEMPLATE.md ├── README.md └── LICENSE /.gitignore: -------------------------------------------------------------------------------- 1 | doc/_build 2 | doc/config_files.txt 3 | -------------------------------------------------------------------------------- /doc/_static/images/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cranmer/binder/master/doc/_static/images/logo.png -------------------------------------------------------------------------------- /doc/_static/images/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cranmer/binder/master/doc/_static/images/favicon.png -------------------------------------------------------------------------------- /readthedocs.yml: -------------------------------------------------------------------------------- 1 | name: mybinder 2 | type: sphinx 3 | conda: 4 | file: doc/environment.yml 5 | python: 6 | version: 3 7 | -------------------------------------------------------------------------------- /doc/environment.yml: -------------------------------------------------------------------------------- 1 | name: mybinder 2 | channels: 3 | - conda-forge 4 | dependencies: 5 | - python=3.5 6 | - sphinx>=1.3.6,!=1.5.4 7 | - pip: 8 | - recommonmark==0.4.0 9 | - sphinx_copybutton 10 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | 14 | -------------------------------------------------------------------------------- /doc/Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | SPHINXPROJ = Binder 8 | SOURCEDIR = . 9 | BUILDDIR = _build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | .PHONY: help Makefile 16 | 17 | # Catch-all target: route all unknown targets to Sphinx using the new 18 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 19 | %: Makefile 20 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -------------------------------------------------------------------------------- /doc/more-info.rst: -------------------------------------------------------------------------------- 1 | More information about Binder 2 | ============================= 3 | 4 | This is a place to aggregate information, goings-on, 5 | case-studies, blog posts, etc about the Binder community. 6 | If you'd like to add something to this page, feel free to 7 | `open an issue `_! 8 | 9 | Blog posts 10 | ---------- 11 | 12 | * `Four steps to Binder in five minutes `_ 13 | by `Titus Brown `_. 14 | * `Binder: an awesome tool for hosting Jupyter Notebooks `_ 15 | by `Julia Evans `_. 16 | 17 | Tools 18 | ----- 19 | 20 | * `Open in Binder `_, a Google Chrome extension 21 | by `Matthias Bussonier `_. 22 | -------------------------------------------------------------------------------- /doc/reproducibility.rst: -------------------------------------------------------------------------------- 1 | Tips for reproducibility 2 | ======================== 3 | 4 | Binder will create a new Docker image the first time is run with a repository. 5 | From then on, a new image will only be created if the commit hash changes 6 | (if you're linking Binder to a branch and not a specific commit hash). Here 7 | are some tips to ensure reproducibility of your Binder links even if you must 8 | re-build your repository image: 9 | 10 | Pin dependencies 11 | ---------------- 12 | 13 | When you install a dependency, include its version number (depending on the 14 | language you use, the exact syntax may vary). E.g., don't just specify ``numpy``, 15 | specify ``numpy==1.12.0``. 16 | 17 | ``pip freeze`` is a handy tool to export the exact version of every Python 18 | package in your environment in a format that can be used in ``requirements.txt``. 19 | 20 | ``conda env export -n `` is the equivalent for anaconda's environment.yml 21 | file. 22 | 23 | Using Dockerfiles 24 | ----------------- 25 | 26 | Ensuring reproducibility with Dockerfiles comes with its own set of challenges. 27 | For more information and best-practices when using Dockerfiles for Binder, 28 | see :doc:`dockerfile`. 29 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # binder 2 | 3 | This repository contains the documentation and usage instructions for the mybinder.org service. 4 | 5 | ## Communication 6 | 7 | [![Join the chat at https://gitter.im/jupyterhub/binder](https://badges.gitter.im/jupyterhub/binder.svg)](https://gitter.im/jupyterhub/binder?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) 8 | 9 | ## Related Repositories 10 | 11 | **For BinderHub, the open-source technology that runs Binder, please visit [jupyterhub/binderhub](https://github.com/jupyterhub/binderhub)** 12 | 13 | For deployment of the website [mybinder.org](https://mybinder.org), please 14 | visit [mybinder.org-deploy](https://github.com/jupyterhub/mybinder.org-deploy). 15 | 16 | BinderHub uses Helm to configure and manage deployment 17 | of the Binder service. For details about this deployment, please visit [helm-chart](https://github.com/jupyterhub/helm-chart). 18 | 19 | Binder is maintained by the [Binder team](https://github.com/jupyterhub/team-compass#binder-team). Administration is managed at [team compass](https://github.com/jupyterhub/team-compass). 20 | 21 | 22 | The JupyterHub team also maintains analysis of binder data including [billing data](https://github.com/jupyterhub/binder-billing) and [activity data](https://github.com/jupyterhub/binder-data). 23 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | BSD 3-Clause License 2 | 3 | Copyright (c) 2017, Project Jupyter Contributors 4 | All rights reserved. 5 | 6 | Redistribution and use in source and binary forms, with or without 7 | modification, are permitted provided that the following conditions are met: 8 | 9 | * Redistributions of source code must retain the above copyright notice, this 10 | list of conditions and the following disclaimer. 11 | 12 | * Redistributions in binary form must reproduce the above copyright notice, 13 | this list of conditions and the following disclaimer in the documentation 14 | and/or other materials provided with the distribution. 15 | 16 | * Neither the name of the copyright holder nor the names of its 17 | contributors may be used to endorse or promote products derived from 18 | this software without specific prior written permission. 19 | 20 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 23 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 24 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 26 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 27 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 28 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 | -------------------------------------------------------------------------------- /doc/reliability.rst: -------------------------------------------------------------------------------- 1 | ``mybinder.org`` status and reliability 2 | ======================================= 3 | 4 | This page serves as a source of information for general Binder status 5 | updates, building/launching statistics, and reliability metrics. 6 | 7 | Site Reliability Goals 8 | ---------------------- 9 | 10 | As ``mybinder.org`` is a research pilot project, the main goal for the project 11 | is to understand usage patterns and workloads for future project evolution. 12 | While we strive for site reliability and availability, we want our users to 13 | understand the intent of this service is research and we offer no guarantees 14 | of its performance in mission critical uses. 15 | 16 | We are still working on defining what the exact goals for uptime and reliability 17 | should be. 18 | 19 | .. note:: 20 | 21 | The ``mybinder.org`` team can always use more help in maintaining the 22 | BinderHub deployment that runs this site. If you're interested in getting 23 | involved, or have any thoughts or suggestions, 24 | please reach out to us on `our Gitter channel `_. 25 | 26 | Site metrics 27 | ------------ 28 | 29 | Below are two key reliability metrics that give an idea for the health of 30 | the ``mybinder.org`` deployment. Note that you can find many more metrics about 31 | the ``mybinder.org`` deployment at `grafana.mybinder.org `_. 32 | 33 | 34 | .. raw:: html 35 | 36 | 37 | -------------------------------------------------------------------------------- /doc/status.rst: -------------------------------------------------------------------------------- 1 | Status of ``mybinder.org`` 2 | ========================== 3 | 4 | This page displays several graphics that give an idea for the current 5 | status of the `mybinder.org `_ service. You can find 6 | a more complete set of graphs the reflect the current state of ``mybinder.org`` 7 | at `grafana.mybinder.org `_. 8 | 9 | .. note:: 10 | 11 | **If you notice an outage** or strong degradation of service at 12 | `mybinder.org `_, please reach out to 13 | the Binder team at the `Binder gitter channel `_! 14 | 15 | Running Binder sessions 16 | ----------------------- 17 | 18 | The total number of user sessions running on Binder. 19 | 20 | .. raw:: html 21 | 22 | 23 | 24 | Binder launch success 25 | --------------------- 26 | 27 | The percentage of new user sessions that successfully launched. If you see 28 | a dip that sustains itself over time, please alert the Binder team at the 29 | `Binder gitter channel `_. 30 | 31 | .. raw:: html 32 | 33 | 34 | 35 | Launch time percentiles 36 | ----------------------- 37 | 38 | The amount of time it takes for a Binder session to successfully launch. 39 | Note that if a Docker image for a repository is not on a node, the launch 40 | time takes much longer. 41 | 42 | .. raw:: html 43 | 44 | 45 | -------------------------------------------------------------------------------- /doc/user-guidelines.rst: -------------------------------------------------------------------------------- 1 | Binder Usage Guidelines 2 | ======================= 3 | 4 | This page details some guidelines and policies that we follow at ``mybinder.org``. 5 | 6 | Temporary Banning 7 | ----------------- 8 | 9 | Temporary banning means that `mybinder.org` will stop building / serving Binder 10 | sessions for a given repository. This usually happens because of some 11 | undesired behavior with the repository. Some examples of behavior that could 12 | result in temporary banning include: 13 | 14 | * A large, unexpected spike in traffic that persists over time. 15 | * Sessions that routinely use a large amount of CPU. 16 | * Sessions that attempt to perform a lot of outgoing networking traffic. 17 | 18 | The ``mybinder.org`` team uses the following workflow in discussing / deciding 19 | when to temporarily ban a repository: 20 | 21 | * An issue is created to document why a repo (or group of repos) is being banned 22 | * A PR that implements the ban is opened 23 | * A "bans" tag notes any PRs that created a ban 24 | * The issue stays open until the ban is lifted 25 | 26 | If you are temporarily banned, contact us on the 27 | `Gitter Channel `_ or 28 | `Open an Issue `_ to discuss 29 | how to un-ban the repository. 30 | 31 | Maximum Concurrent Users for a Repository 32 | ----------------------------------------- 33 | 34 | We don't want a single repository to dominate all of the traffic to Binder, so 35 | we've set a maximum limit of concurrent user sessions that point to the same 36 | Binder link. **The maximum number of simultaneous users for a given repo is 100**. 37 | If you think you have a *really* good reason for why this number should be 38 | higher, please `Open an Issue `_ 39 | to discuss with the community! 40 | 41 | Reporting Abuse 42 | --------------- 43 | 44 | If you'd like to report any abuse of the ``mybinder.org`` service, please 45 | `click here to send an abuse report `_. 46 | -------------------------------------------------------------------------------- /doc/index.rst: -------------------------------------------------------------------------------- 1 | Binder Documentation 2 | ==================== 3 | 4 | .. image:: https://badges.gitter.im/jupyterhub/binder.svg 5 | :alt: Join the chat at https://gitter.im/jupyterhub/binder 6 | :target: https://gitter.im/jupyterhub/binder?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge 7 | 8 | **Binder** allows you to create custom computing environments that can be shared 9 | and used by many remote users. It is powered by `BinderHub `_, 10 | which is an open-source tool that deploys the Binder service in the cloud. 11 | One-such deployment lives here, at `mybinder.org `_, and is free to use. 12 | 13 | This documentation provides information for those who 14 | wish to use a pre-existing Binder deployment such as `mybinder.org `_. 15 | If you'd like documentation on how to create and administer your own BinderHub deployment, 16 | see the `BinderHub documentation `_, which 17 | guides you through deploying your own BinderHub. 18 | 19 | See the `Binder Examples `_ GitHub 20 | organization for sample Binder repositories demonstrating its functionality. 21 | 22 | .. note:: 23 | 24 | Binder is a research pilot, whose main goal is to understand usage patterns 25 | and workloads for future evolution and development. It is not a service that 26 | can be relied on for critical operations. 27 | 28 | Using Binder 29 | ------------ 30 | 31 | The following sections cover the basics of how to use a Binder service. 32 | 33 | .. toctree:: 34 | :maxdepth: 2 35 | 36 | introduction 37 | using 38 | user-guidelines 39 | 40 | Sample repositories 41 | ------------------- 42 | 43 | The following is a list of sample repositories showing off various things 44 | you can do with Binder. 45 | 46 | .. toctree:: 47 | :maxdepth: 2 48 | 49 | sample_repos 50 | 51 | Advanced 52 | -------- 53 | 54 | These sections cover more advanced topics in the Binder ecosystem, as well 55 | as resources for more information. 56 | 57 | .. toctree:: 58 | :maxdepth: 2 59 | 60 | dockerfile 61 | reproducibility 62 | faq 63 | status 64 | reliability 65 | more-info 66 | -------------------------------------------------------------------------------- /doc/introduction.rst: -------------------------------------------------------------------------------- 1 | Getting started with Binder 2 | =========================== 3 | 4 | An interactive introduction to Binder 5 | ------------------------------------- 6 | 7 | For a quick introduction to Binder, and a demonstration of how you can 8 | make a Binder-ready repository, click the Binder link below: 9 | 10 | .. image:: https://mybinder.org/badge.svg 11 | :target: https://mybinder.org/v2/gh/binder-examples/zero-to-binder/master?filepath=intro-to-binder.ipynb 12 | 13 | What can I do with Binder? 14 | -------------------------- 15 | 16 | Binder makes it simple to generate reproducible computing environments from a 17 | Git repository. Binder uses the BinderHub technology to generate a Docker 18 | image from this repository. The image will have all the components that you 19 | specify along with the Jupyter Notebooks inside. You will be able to share a URL 20 | with users that can immediately begin interacting with this environment via the 21 | cloud. Binder's goal is to enable as many analytic workflows as possible. 22 | 23 | For example, Binder currently supports: 24 | 25 | * Python, Julia, and R kernels (natively, with other kernels possible via a 26 | Dockerfile) (links for `python `_, 27 | `R `_, and `Julia `_) 28 | * Jupyter Notebooks (`link `_) 29 | * Jupyter Lab (`link `_) 30 | * RStudio sessions (`link `_) 31 | * Interactive presentations with RISE (`link `_) 32 | 33 | Among many others workflows! 34 | 35 | Generating a sharable Binder link 36 | --------------------------------- 37 | 38 | You may share a link that generates a Binder. To generate a link for your 39 | Binder repository, visit `mybinder.org `_ and type in the information for your repository. 40 | You will see your Binder link automatically generated as you fill in the form. 41 | 42 | The link structure is:: 43 | 44 | https://mybinder.org/v2////?filepath= 45 | 46 | Share this link with anyone (i.e. colleagues, students) who would like to use 47 | your Binder. 48 | 49 | What technology does Binder use? 50 | -------------------------------- 51 | 52 | Binder combines several open-source technologies, especially: 53 | 54 | * `repo2docker `_, for quickly generating 55 | Docker images from a GitHub repository. 56 | * `JupyterHub `_, for connecting a built Docker 57 | image to cloud computation and a user-facing web portal. 58 | * `BinderHub `_, for gluing the above two 59 | tools together to create the Binder experience. 60 | -------------------------------------------------------------------------------- /doc/parse_readmes.py: -------------------------------------------------------------------------------- 1 | """This is a helper file to auto-generate the sample 2 | READMEs page for the mybinder documentation. It expects 3 | a couple of environment variables to be set corresponding 4 | to your github username / password. 5 | 6 | The script grabs some metadata and the README text for 7 | all of the binder-examples repositories, and then constructs 8 | a markdown file that can be served on the mybinder.org 9 | documentation page. 10 | """ 11 | 12 | from github import Github 13 | import os 14 | 15 | EXCLUDE_FILES = ['.gitignore', 'LICENSE', 'README.md'] 16 | EXCLUDE_REPOS = ['dockerfile-rstudio', 'zero-to-binder'] 17 | 18 | # First create a Github instance: 19 | g = Github(os.environ['GITHUB_USERNAME'], 20 | os.environ['GITHUB_PASSWORD']) 21 | 22 | org = g.get_organization('binder-examples') 23 | repos = list(org.get_repos()) 24 | repos = [repo for repo in repos if repo.name not in EXCLUDE_REPOS] 25 | 26 | lines = ['# Sample Binder Repositories\n', 27 | '\n' 28 | 'Below we list several sample Binder repositories that\n' 29 | 'demonstrate how to compose build files in order to create\n' 30 | 'Binders with varying environments. You can find all of the\n' 31 | 'repositories listed on this page at the\n' 32 | '[binder-examples GitHub organization](https://github.com/binder-examples).\n\n'] 33 | 34 | for i_repo, repo in enumerate(repos): 35 | print('{}/{}'.format(i_repo+1, len(repos))) 36 | 37 | # Base metadata 38 | link = repo.url.replace('api.github.com/repos', 'github.com') 39 | name = repo.name 40 | 41 | # Grab repo contents 42 | files = repo.get_dir_contents('.') 43 | file_names = [this_file.name 44 | for this_file in files if this_file.name not in EXCLUDE_FILES] 45 | file_names = ['{}'.format(this_name) for this_name in file_names] 46 | 47 | # Parse readme 48 | readme = repo.get_file_contents('README.md') 49 | readme_text = readme.decoded_content.decode() 50 | readme_text = readme_text.replace('beta.mybinder.org', 'mybinder.org') 51 | readme_text = readme_text.split('\n') 52 | 53 | # Correct for header lines 54 | for i_line, line in enumerate(readme_text): 55 | if line.startswith('#'): 56 | readme_text[i_line] = '#' + line 57 | if line.startswith('[![Binder]'): 58 | readme_text[i_line] = line + ' | [repo link]({})'.format(link) 59 | 60 | if i_line != 0: 61 | lines.append('---------') 62 | 63 | # Append to doc file 64 | lines += readme_text 65 | lines.append('### Files in this repository') 66 | lines.append('```') 67 | for this_file in file_names: 68 | lines.append(this_file) 69 | lines.append('```') 70 | lines.append('```eval_rst\n|\n|\n\n```') 71 | 72 | lines = [ln + '\n' for ln in lines] 73 | 74 | with open('sample_repos.md', 'w') as ff: 75 | ff.writelines(lines) 76 | 77 | print('Finished building docs for {} repos.'.format(len(repos))) 78 | -------------------------------------------------------------------------------- /doc/using.rst: -------------------------------------------------------------------------------- 1 | .. _using-binder: 2 | 3 | Using Binder 4 | ============ 5 | 6 | This page describes how to use Binder to create interactive, sharable 7 | repositories. It includes how to prepare your repository to be binder-ready, 8 | as well as how to build and launch that repository with Binder. 9 | 10 | .. _preparing_repositories: 11 | 12 | Preparing a repository for Binder 13 | --------------------------------- 14 | 15 | All of the code in a repository is available to users, 16 | your Binder repository should contain at least: 17 | 18 | * The code you want users to run. This might be a collection of Jupyter 19 | notebooks or scripts. 20 | * Configuration files (one or more text files) that specify the requirements 21 | for building your project's code. For a complete list of supported files, 22 | see :ref:`config-files`. Configuration files may be placed in the root of 23 | your repository or in a ``binder/`` folder in the repository's root 24 | (i.e. ``myproject/binder/``). If a ``binder/`` folder is used, Binder will 25 | only read configuration files from that location and will ignore those in 26 | the repository's root. 27 | 28 | .. tip:: 29 | 30 | For a list of sample repositories for use with Binder, see the 31 | `Sample Binder Repositories `_ page. 32 | 33 | .. include:: config_files.txt 34 | 35 | Launching your Binder 36 | --------------------- 37 | 38 | Once you have prepared your repository per the instructions above, 39 | it is time to build and launch your binder-ready repo. Navigate to ``mybinder.org`` 40 | and insert the URL for your git repository. Press ``Launch`` to automatically create your Binder. 41 | The Binder service will automatically send you to a live Jupyter session 42 | connected to this repository. 43 | 44 | If a previous version of the repository has already been built, Binder will 45 | only build a new one if the git hashes don't match. When Binder 46 | *doesn't* need to build a repository, the process of connecting to the live 47 | computational environment is much faster. 48 | 49 | Use cases 50 | --------- 51 | 52 | Below are some example use-cases and their respective repository 53 | configuration. 54 | 55 | For a full guide on how to configure your repository for 56 | Binder, see the `repo2docker configuration guide 57 | `_. 58 | For a list of sample repositories for use with Binder, see the 59 | `Sample Binder Repositories `_ page. 60 | 61 | Simple Python dependencies 62 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 63 | 64 | Many repositories already contain a ``requirements.txt`` specifying the 65 | dependencies of that repository. For 'simple to install' dependencies, a 66 | ``requirements.txt`` should meet your needs. To generate a ``requirements.txt`` from 67 | the environment you have locally use ``pip freeze > requirements.txt``. This 68 | will list all packages you have installed, and can be a starting point for 69 | constructing your ``requirements.txt``. We recommend you only list those 70 | packages you really need to successfully build the repository. 71 | 72 | Take a look at the `binder-examples/requirements `_ 73 | repository to see an example. 74 | 75 | Using conda packages 76 | ~~~~~~~~~~~~~~~~~~~~ 77 | 78 | For 'complex to install' packages, like ``geopandas``, we 79 | recommend using the `conda package manager `_. 80 | To specify your dependencies create an ``environment.yml`` listing the packages 81 | and versions required. For syntax help read `create an environment file manually `_ 82 | from the conda documentation. 83 | 84 | Take a look at the `binder-examples/conda `_ 85 | repository to see an example. 86 | 87 | .. note:: 88 | 89 | Packages that require ``pip`` for installation can be specified in 90 | the ``environment.yml`` file. We recommend this approach instead of having 91 | a ``requirements.txt`` and an ``environment.yml`` in the same repository. 92 | See `binder-examples/python-conda_pip `_. 93 | 94 | Using Python2 95 | ~~~~~~~~~~~~~ 96 | 97 | To use python 2.7 for your repository create a ``runtime.txt`` with 98 | ``python-2.7`` as only content. This will install a python2 environment in 99 | addition to the default python environment. The contents of ``requirements.txt`` 100 | are installed into the python2 environment. 101 | 102 | Take a look at the `binder-examples/python2_runtime `_ 103 | repository to see an example. 104 | 105 | .. note:: 106 | 107 | Make sure that you save your notebooks with a python2 kernel activated, 108 | as this defines which kernel Binder will use when a notebook is opened. 109 | The active kernel is displayed in the upper right corner of the notebook. 110 | 111 | .. note:: 112 | 113 | If you also wish to install dependencies into the python3 environment, 114 | include a file called ``requirements3.txt``. The packages inside it will be 115 | installed into the python3 environment. 116 | 117 | Executing post-build commands 118 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 119 | 120 | You might need to run arbitrary commands at the end of the build process. Place 121 | these in the ``postBuild`` file and make it executable. One use case is having 122 | a repository that contains a Python package and examples that use the package. 123 | In this case you can run ``python setup.py install`` from the ``postBuild`` 124 | file to avoid having to place your package in the ``requirements.txt``. It is 125 | also useful for activating notebook extensions you installed via a 126 | ``requirements.txt`` directive earlier. 127 | 128 | Take a look at the `binder-examples/jupyter-extension `_ 129 | repository to see an example. 130 | -------------------------------------------------------------------------------- /doc/conf.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | # -*- coding: utf-8 -*- 3 | # 4 | # Binder documentation build configuration file, created by 5 | # sphinx-quickstart on Fri Aug 18 10:42:06 2017. 6 | # 7 | # This file is execfile()d with the current directory set to its 8 | # containing dir. 9 | # 10 | # Note that not all possible configuration values are present in this 11 | # autogenerated file. 12 | # 13 | # All configuration values have a default; values that are commented out 14 | # serve to show the default. 15 | 16 | # If extensions (or modules to document with autodoc) are in another directory, 17 | # add these directories to sys.path here. If the directory is relative to the 18 | # documentation root, use os.path.abspath to make it absolute, like shown here. 19 | # 20 | # import os 21 | # import sys 22 | # sys.path.insert(0, os.path.abspath('.')) 23 | 24 | import requests 25 | from recommonmark.transform import AutoStructify 26 | github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/' 27 | def setup(app): 28 | app.add_config_value('recommonmark_config', { 29 | 'url_resolver': lambda url: github_doc_root + url, 30 | 'auto_toc_tree_section': 'Contents', 31 | }, True) 32 | app.add_transform(AutoStructify) 33 | 34 | # -- General configuration ------------------------------------------------ 35 | 36 | # If your documentation needs a minimal Sphinx version, state it here. 37 | # 38 | # needs_sphinx = '1.0' 39 | 40 | # Add any Sphinx extension module names here, as strings. They can be 41 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 42 | # ones. 43 | extensions = ['sphinx_copybutton'] 44 | 45 | # Add any paths that contain templates here, relative to this directory. 46 | templates_path = ['_templates'] 47 | 48 | # The suffix(es) of source filenames. 49 | # You can specify multiple suffix as a list of string: 50 | 51 | source_suffix = ['.rst', '.md'] 52 | 53 | from recommonmark.parser import CommonMarkParser 54 | source_parsers = { 55 | '.md': CommonMarkParser, 56 | } 57 | 58 | 59 | # The master toctree document. 60 | master_doc = 'index' 61 | 62 | # General information about the project. 63 | project = 'Binder' 64 | copyright = '2017, The Binder Team' 65 | author = 'The Binder Team' 66 | 67 | # The version info for the project you're documenting, acts as replacement for 68 | # |version| and |release|, also used in various other places throughout the 69 | # built documents. 70 | # 71 | # The short X.Y version. 72 | version = '0.1b' 73 | # The full version, including alpha/beta/rc tags. 74 | release = '0.1b' 75 | 76 | # The language for content autogenerated by Sphinx. Refer to documentation 77 | # for a list of supported languages. 78 | # 79 | # This is also used if you do content translation via gettext catalogs. 80 | # Usually you set "language" from the command line for these cases. 81 | language = None 82 | 83 | # List of patterns, relative to source directory, that match files and 84 | # directories to ignore when looking for source files. 85 | # This patterns also effect to html_static_path and html_extra_path 86 | exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 87 | 88 | # The name of the Pygments (syntax highlighting) style to use. 89 | pygments_style = 'sphinx' 90 | 91 | # If true, `todo` and `todoList` produce output, else they produce nothing. 92 | todo_include_todos = False 93 | 94 | # Binder Logo 95 | html_logo = '_static/images/logo.png' 96 | html_favicon = '_static/images/favicon.png' 97 | 98 | # -- Options for HTML output ---------------------------------------------- 99 | 100 | # The theme to use for HTML and HTML Help pages. See the documentation for 101 | # a list of builtin themes. 102 | # 103 | html_theme = 'alabaster' 104 | 105 | # Theme options are theme-specific and customize the look and feel of a theme 106 | # further. For a list of options available for each theme, see the 107 | # documentation. 108 | # 109 | # html_theme_options = {} 110 | 111 | # Add any paths that contain custom static files (such as style sheets) here, 112 | # relative to this directory. They are copied after the builtin static files, 113 | # so a file named "default.css" will overwrite the builtin "default.css". 114 | html_static_path = ['_static'] 115 | 116 | 117 | # -- Options for HTMLHelp output ------------------------------------------ 118 | 119 | # Output file base name for HTML help builder. 120 | htmlhelp_basename = 'Binderdoc' 121 | 122 | 123 | # -- Options for LaTeX output --------------------------------------------- 124 | 125 | latex_elements = { 126 | # The paper size ('letterpaper' or 'a4paper'). 127 | # 128 | # 'papersize': 'letterpaper', 129 | 130 | # The font size ('10pt', '11pt' or '12pt'). 131 | # 132 | # 'pointsize': '10pt', 133 | 134 | # Additional stuff for the LaTeX preamble. 135 | # 136 | # 'preamble': '', 137 | 138 | # Latex figure (float) alignment 139 | # 140 | # 'figure_align': 'htbp', 141 | } 142 | 143 | # Grouping the document tree into LaTeX files. List of tuples 144 | # (source start file, target name, title, 145 | # author, documentclass [howto, manual, or own class]). 146 | latex_documents = [ 147 | (master_doc, 'Binder.tex', 'Binder Documentation', 148 | 'The Binder Team', 'manual'), 149 | ] 150 | 151 | 152 | # -- Options for manual page output --------------------------------------- 153 | 154 | # One entry per manual page. List of tuples 155 | # (source start file, name, description, authors, manual section). 156 | man_pages = [ 157 | (master_doc, 'binder', 'Binder Documentation', 158 | [author], 1) 159 | ] 160 | 161 | 162 | # -- Options for Texinfo output ------------------------------------------- 163 | 164 | # Grouping the document tree into Texinfo files. List of tuples 165 | # (source start file, target name, title, author, 166 | # dir menu entry, description, category) 167 | texinfo_documents = [ 168 | (master_doc, 'Binder', 'Binder Documentation', 169 | author, 'Binder', 'One line description of project.', 170 | 'Miscellaneous'), 171 | ] 172 | 173 | # -- Scripts -------------------------------------------------------------- 174 | 175 | # Grab the latest version of the configuration file examples. 176 | url_config = "https://raw.githubusercontent.com/jupyter/repo2docker/master/docs/source/config_files.rst" 177 | resp = requests.get(url_config) 178 | with open('./config_files.txt', 'w') as ff: 179 | ff.write(resp.text) 180 | -------------------------------------------------------------------------------- /doc/dockerfile.rst: -------------------------------------------------------------------------------- 1 | .. _dockerfile: 2 | 3 | Using a Dockerfile 4 | ================== 5 | 6 | Binder supports configuration files for package 7 | installation, environment specification, post-build shell scripts, and more. 8 | It should be possible to create the environment that you want *without* 9 | using a Dockerfile. For more information about the different environment 10 | configuration files that Binder can create, see 11 | :ref:`preparing_repositories`. 12 | 13 | However, in case you cannot meet all your needs with these configuration 14 | files, it is also possible to use a Dockerfile to define your environment. 15 | This is considered an **advanced use case**, and we cannot guarantee that the 16 | Dockerfile will work. 17 | 18 | This guide will help you in preparing your Dockerfile so that it has the 19 | components needed to run JupyterHub, allowing it to work on Binder 20 | deployments. 21 | 22 | .. important:: 23 | 24 | We recommend against using a ``Dockerfile`` as a way to make your repository 25 | usable with binder. Use them as a last resort after all methods in 26 | :ref:`preparing_repositories` have failed. 27 | 28 | .. note:: 29 | 30 | Binder's requirements for Dockerfiles are in beta and subject to change. 31 | Dockerfiles may break on Binder from time to time during the beta period. 32 | 33 | 34 | When should you use a Dockerfile? 35 | --------------------------------- 36 | 37 | Below are a few use-cases where you *might* want to use a Dockerfile with 38 | Binder. 39 | 40 | When you must inherit from a popular Docker image 41 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 42 | 43 | If you want to use a pre-existing Docker image, you may source it in your 44 | Dockerfile. For example, this code sources the Jupyter-Scipy notebook: 45 | 46 | .. code-block:: Dockerfile 47 | 48 | # Note that there must be a tag 49 | FROM jupyter/scipy-notebook:cf6258237ff9 50 | 51 | See `Preparing your Dockerfile`_ for instructions on how to 52 | do this properly. 53 | 54 | When you are building complex software 55 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 56 | 57 | Most Binder configurations can be achieved without a Dockerfile. 58 | Before resorting to a Dockerfile, we recommend trying to use ``postBuild`` 59 | commands for configuration. See 60 | `the repo2docker documentation `_ 61 | for examples. 62 | 63 | When you're using a language that is not directly supported 64 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 65 | 66 | Binder supports many languages, but not all of them. If your need to use 67 | a different language, it may be possible to accomplish this with a Dockerfile. 68 | 69 | For a list of languages that Binder supports with configuration files, see 70 | `the repo2docker documentation `_. 71 | 72 | .. note:: 73 | 74 | We welcome contributions to ``repo2docker`` to add support for new 75 | languages. If interested, please 76 | `open an issue `_. 77 | 78 | 79 | Preparing your Dockerfile 80 | ------------------------- 81 | 82 | For a Dockerfile to work on Binder, it must meet the following requirements: 83 | 84 | 1. It must install a recent version of Jupyter Notebook. 85 | This should be installed via ``pip`` with the `notebook` package. 86 | So in your dockerfile, you should have a command such as: 87 | 88 | .. code-block:: Dockerfile 89 | 90 | RUN pip install --no-cache-dir notebook==5.* 91 | 92 | 2. It must explicitly specify a tag in the image you source. 93 | 94 | When sourcing a pre-existing Docker image with ``FROM``, 95 | **a tag is required**. The tag *cannot* be ``latest``. Note that tag 96 | naming conventions differ between images, so we recommend using 97 | the SHA tag of the image. 98 | 99 | Here's an example of a Dockerfile ``FROM`` statement that would work. 100 | 101 | .. code-block:: Dockerfile 102 | 103 | FROM jupyter/scipy-notebook:cf6258237ff9 104 | 105 | .. note:: 106 | 107 | The following examples would **not** work: 108 | 109 | .. code-block:: Dockerfile 110 | 111 | FROM jupyter/scipy-notebook 112 | 113 | or 114 | 115 | .. code-block:: Dockerfile 116 | 117 | FROM jupyter/scipy-notebook:latest 118 | 119 | 3. It must set up a user whose uid is `1000`. 120 | It is bad practice to run processes in containers as root, and on binder 121 | we do not allow root container processes. If you are using an ubuntu or 122 | debian based container image, you can create a user easily with the following 123 | directives somewhere in your Dockerfile: 124 | 125 | .. code-block:: Dockerfile 126 | 127 | ENV NB_USER jovyan 128 | ENV NB_UID 1000 129 | ENV HOME /home/${NB_USER} 130 | 131 | RUN adduser --disabled-password \ 132 | --gecos "Default user" \ 133 | --uid ${NB_UID} \ 134 | ${NB_USER} 135 | 136 | This is the user that will be running the jupyter notebook process 137 | when your repo is launched with binder. So any files you would like to 138 | be writeable by the launched binder notebook should be owned by this user. 139 | 140 | 4. It must copy its contents to the ``$HOME`` directory and change permissions. 141 | 142 | To make sure that your repository contents are available to users, 143 | you must copy all contents to ``$HOME`` and then make this folder 144 | owned by the user you created in step 3. If you used the snippet provided 145 | in step 3, you can accomplish this copying with the following snippet: 146 | 147 | .. code-block:: Dockerfile 148 | 149 | # Make sure the contents of our repo are in ${HOME} 150 | COPY . ${HOME} 151 | USER root 152 | RUN chown -R ${NB_UID} ${HOME} 153 | USER ${NB_USER} 154 | 155 | This chown is required because Docker will be default 156 | set the owner to ``root``, which would prevent users from editing files. 157 | 158 | 5. It must specify a default command. 159 | 160 | This is the command that is executed on startup. 161 | 162 | .. code-block:: Dockerfile 163 | 164 | # Specify the default command to run 165 | CMD ["jupyter", "notebook", "--ip", "0.0.0.0"] 166 | 167 | 168 | Ensuring reproducibility with Dockerfiles 169 | ----------------------------------------- 170 | 171 | Ensuring that your Binder environment is reproducible requires extra 172 | considerations when using a Dockerfile. This section provides some guidelines 173 | for making sure your Binder environment does not change in unexpected ways. 174 | 175 | As mentioned above, make sure that you source your Dockerfile from a **tag** 176 | of another image. This ensures that you will continue building off of 177 | the same image even if the image is updated to a new version. 178 | 179 | Next, make sure that all packages installed with your Dockerfile 180 | are pinned to specific versions. You should do this with the the image you are 181 | sourcing as well. 182 | -------------------------------------------------------------------------------- /doc/faq.rst: -------------------------------------------------------------------------------- 1 | Frequently Asked Questions 2 | ========================== 3 | 4 | What is a Binder? 5 | ----------------- 6 | 7 | A Binder is a Git repository that has been outfitted with the appropriate 8 | `build files `_ so 9 | that its content can be connected with a BinderHub instance. Currently these 10 | repositories mostly live on `GitHub `_, though we plan 11 | on supporting more online repositories such as GitLab or BitBucket. 12 | 13 | What is the Binder community? 14 | ----------------------------- 15 | 16 | A collection of people that aim to make it easy to turn 17 | computational material (e.g. Jupyter notebooks, R scripts, and environment 18 | files) into computational environments (a Docker image) and serve this 19 | environment through the cloud. The underlying technology that manages this 20 | process is called `BinderHub`_. 21 | 22 | What is BinderHub? 23 | ------------------ 24 | 25 | `BinderHub`_ is the server technology that 26 | turns computational material into 27 | interactive computational environments in the cloud. It utilizes 28 | `Kubernetes and JupyterHub `_ in order to 29 | simplify the deployment process and make it easy to scale. 30 | 31 | What is ``mybinder.org``? 32 | ------------------------- 33 | 34 | ``mybinder.org`` is a single deployment of a BinderHub instance, managed by 35 | the Binder community. It serves as both a public service and a demonstration 36 | of the BinderHub technology, though it is by no means the only BinderHub 37 | in existence. If you're interested in deploying your own BinderHub for your 38 | own uses, please see the `BinderHub documentation `_ 39 | and don't hesitate to reach out to the `Binder community `_. 40 | 41 | Is ``mybinder.org`` free to use? 42 | -------------------------------- 43 | 44 | Yes! Though note that it has relatively :ref:`limited computational resources 45 | `. 46 | 47 | How much does running ``mybinder.org`` cost? 48 | -------------------------------------------- 49 | 50 | Great question! If you're interested in the technical costs of running 51 | ``mybinder.org``, we publish a semi-up-to-date dataset of our costs at the 52 | `binder-data `_ 53 | repository. In addition, you can explore these costs with the binder link below! 54 | 55 | .. image:: https://mybinder.org/badge.svg 56 | :target: https://mybinder.org/v2/gh/jupyterhub/binder-billing/master?filepath=analyze_data.ipynb 57 | 58 | How can ``mybinder.org`` be free to use? 59 | ---------------------------------------- 60 | 61 | The Binder project has a `grant from the Moore Foundation `_ 62 | to sustain the cloud resources running ``mybinder.org``. In the future we hope to see more 63 | public BinderHub services running that can form a collection of community 64 | resources for interactive cloud computing. 65 | 66 | .. _user_memory: 67 | 68 | How much memory am I given when using Binder? 69 | --------------------------------------------- 70 | 71 | If you or another Binder user clicks on a Binder link, the ``mybinder.org`` 72 | deployment will run the linked repository. While running, users are guaranteed 73 | *at least* 1GB of RAM, with a *maximum* of 2GB. This means you will always have 74 | 1GB, you may occasionally have between 1 and 2GB, and if you go over 2GB your kernel 75 | will be restarted. 76 | 77 | How long will my Binder session last? 78 | ------------------------------------- 79 | 80 | Binder is meant for interactive and ephemeral interactive coding, meaning that 81 | it is ideally suited for relatively short sessions. Binder will automatically 82 | shut down user sessions that have more than 10 minutes of inactivity (if you 83 | leave your window open, this will be counted as "activity"). 84 | 85 | Binder aims to provide at least 12 hours of session time per user session. 86 | Beyond that, we cannot guarantee that the session will remain running. 87 | 88 | Can I use mybinder.org for a live demo or workshop? 89 | --------------------------------------------------- 90 | 91 | For sure! We hope the demo gods are with you. Please do make sure you have a 92 | backup plan in case there is a problem with mybinder.org during your workshop 93 | or demo. Occasionally, service on ``mybinder.org`` can be degraded, usually because 94 | the server is getting a lot of attention somewhere on the 95 | internet, because we are deploying new versions of software, or the team 96 | can't quickly respond to an outage. 97 | 98 | How does mybinder.org ensure user privacy? 99 | ------------------------------------------ 100 | 101 | We take user privacy very seriously! Because Binder runs as a public, 102 | free service, we don't require any kind of log-in that would let us 103 | keep track of user data. All code that is run, data analyzed, papers 104 | reproduced, classes taught - in short, everything that happens in a 105 | Binder session - is destroyed when the user logs off or becomes inactive 106 | for more than a few minutes. 107 | 108 | Here are the pieces of information we do keep: We run google analytics 109 | with anonymized IPs and no cookies, which gives us just enough information 110 | to know how Binder is being used, and but won't be able to identify users. 111 | We also retain logs of IP addresses for 30 days, which is used solely in 112 | the case of detecting abuse of the service. If you have suggestions for 113 | how we can ensure the privacy of our data and users, we'd love to hear it! 114 | 115 | How secure is mybinder.org? 116 | --------------------------- 117 | 118 | The Binder team has put in a lot of work to ensure that the mybinder.org 119 | service runs as secure as possible. However, it is a free, public service 120 | that is open to the world, and **you should never share sensitive or personal 121 | information within a Binder repository**. This includes passwords, data that 122 | shouldn't be public, API keys, etc. 123 | 124 | You should ensure that sensitive information doesn't make it into the built 125 | docker image for your Binder (aka, that it isn't used in one of your 126 | configuration files) and that you don't use this information from within 127 | a Binder session (e.g. hard-coding an API key into an HTTP request that you 128 | call from a Jupyter Notebook). 129 | 130 | If you require private information within your 131 | Binder instance, consider `deploying a BinderHub for your group `_. 132 | 133 | Where can I report a security issue? 134 | ------------------------------------ 135 | 136 | If you find a security vulnerability in with ``mybinder.org``, please report 137 | it to `security@ipython.org `_. 138 | 139 | If you prefer to encrypt your security reports, you can use `this PGP public key 140 | `_. 141 | 142 | Can I push data from my Binder session back to my repository? 143 | ------------------------------------------------------------- 144 | 145 | While it is *technically* possible to push information from a Binder 146 | session onto a platform like GitHub, we *strongly discourage* it. We 147 | cannot guarantee the security of data moving through ``mybinder.org``, 148 | and your password or any sensitive data may be compromised. You 149 | shouldn't do anything on ``mybinder.org`` that you wouldn't mind sharing 150 | with the world! 151 | 152 | Can I put my configuration files outside the root of my repository? 153 | ------------------------------------------------------------------- 154 | 155 | Yes! Configuration files may be placed in the root of your repository or 156 | in a ``binder/`` folder in the root of your repository (i.e. ``myproject/binder/``). 157 | If a ``binder/`` folder is used, Binder will only read configuration files 158 | from that location (i.e. ``myproject/binder/requirements.txt``) and will 159 | ignore those in the repository's root (``myproject/environment.yml`` and 160 | ``myproject/requirements.txt``). 161 | 162 | What factors influence how long it takes a Binder session to start? 163 | ------------------------------------------------------------------- 164 | 165 | Understanding why some operations take longer than others requires a very 166 | brief overview of the pieces of machinery at play with BinderHub. There two 167 | things worth mentioning: 168 | 169 | * A *user pod* is the virtual machine that runs a users' code. 170 | * A *node* is the machine, running in the cloud, where a bunch of pods live. 171 | There are many nodes for a Binder server, depending on the number of people 172 | using the service. 173 | * A *registry* is a service in the cloud where Docker images are stored. BinderHub 174 | has the ability to push / pull from this registry, which it uses to 175 | manage Binder environment images. 176 | 177 | With that being said, there are three primary things that need to happen any 178 | time someone clicks a Binder link. 179 | 180 | 1. A Docker image for the link must exist in Binder's image registry. If an image 181 | for the current ``ref`` of the repository *doesn't* exist, one will be built 182 | and registered automatically using ``repo2docker``. If your 183 | configuration files specify a large or complex environment, this will take 184 | some time while your image builds. 185 | 2. The Docker image must exist on the node that the user will use. If it does not, 186 | then BinderHub will pull the image. If the image is large, this will 187 | take some time depending on the server load and image size. 188 | 3. A pod for the user must be created to serve this Docker image. This usually 189 | happens in seconds, though may take longer if the server is under a heavy 190 | load. 191 | 192 | These three things happen in a nested fashion. "3" always happens, "2" only 193 | happens the *first* time a node is used to serve a particular Docker image, "1" 194 | only happens the first time someone clicks a Binder link for a repository with 195 | an updated ``ref``. They take roughly decreasing amounts of time to complete, 196 | so 1 >> 2 >> 3 in terms of how long each operation takes. 197 | 198 | If Binder sessions take a while to start, but you know that your image has 199 | already been built, there's a good chance you are in step 2, and the server is 200 | still pulling the image onto the node that you'll be using. Please be patient! 201 | 202 | Will repos with fewer notebooks launch faster? Should I split my notebooks into smaller repos? 203 | ---------------------------------------------------------------------------------------------- 204 | 205 | Number of notebooks in a repo shouldn't have any impact on binder launch time, 206 | assuming a docker image for that repo is already built. It is worth noting, however, 207 | that there is a limit to the number of instances of a repository that can be active 208 | at any moment in time. 209 | 210 | Will repos that are launched often get prioritized and launch faster? 211 | --------------------------------------------------------------------- 212 | 213 | There isn't any intentional prioritization for repos that are launched frequently, 214 | however, in practice the repos that launch more often will tend to launch faster. 215 | This is because if a user pod is put on a node that doesn't already have the Docker 216 | image for that repo, then it'll have to do a Docker pull first, which takes time. If 217 | a repo is launched a lot, then most likely it will already be on a given node. 218 | 219 | What can I do if ``mybinder.org`` does not meet my needs? 220 | --------------------------------------------------------- 221 | 222 | ``mybinder.org`` uses software called `BinderHub`_ to carry out its services. 223 | This is an Open Source, community-driven project that can be deployed on 224 | most cloud providers. If you desire more computational resources for users or 225 | want guaranteed uptime, consider setting up your own BinderHub deployment. 226 | 227 | For more information, see the `BinderHub documentation `_ 228 | for instructions on how to deploy your own BinderHub, and the 229 | `Zero to JupyterHub `_ 230 | documentation for how to customize the user environment. 231 | 232 | .. _BinderHub: https://binderhub.readthedocs.io/en/latest 233 | -------------------------------------------------------------------------------- /doc/sample_repos.md: -------------------------------------------------------------------------------- 1 | # Sample Binder Repositories 2 | 3 | 4 | Below we list several sample Binder repositories that 5 | demonstrate how to compose build files in order to create 6 | Binders with varying environments. You can find all of the 7 | repositories listed on this page at the 8 | [binder-examples GitHub organization](https://github.com/binder-examples). 9 | 10 | 11 | --------- 12 | ## Julia and Python environments 13 | 14 | [![Binder](http://mybinder.org/badge.svg)](http://mybinder.org/v2/gh/binder-examples/julia_python/master) | [repo link](https://github.com/binder-examples/julia-python) 15 | 16 | This example shows how you can install a Julia and Python environment side-by-side. 17 | In this repository are *both* an `environment.yml` file as well as a `REQURE` file. 18 | The former corresponds to an anaconda python environment, and the latter corresponds 19 | to a Julia environment. Both kernels will be available to you in a built Binder 20 | environment. 21 | 22 | ### Files in this repository 23 | ``` 24 | REQUIRE 25 | environment.yml 26 | julia.ipynb 27 | python-and-julia.ipynb 28 | python.ipynb 29 | ``` 30 | ```eval_rst 31 | | 32 | | 33 | 34 | ``` 35 | --------- 36 | ## Python environment with requirements.txt 37 | 38 | [![Binder](http://mybinder.org/badge.svg)](http://mybinder.org/v2/gh/binder-examples/requirements/master) | [repo link](https://github.com/binder-examples/requirements) 39 | 40 | A Binder-compatible repo with a `requirements.txt` file. 41 | 42 | Access this Binder at the following URL: 43 | 44 | http://mybinder.org/v2/gh/binder-examples/requirements/master 45 | 46 | ### Notes 47 | The `requirements.txt` file should list all Python libraries that your notebooks 48 | depend on, and they will be installed using: 49 | 50 | ``` 51 | pip install -r requirements.txt 52 | ``` 53 | 54 | The base Binder image contains no extra dependencies, so be as 55 | explicit as possible in defining the packages that you need. This includes 56 | specifying explict versions wherever possible. 57 | 58 | In this example we include the library `seaborn`, and our notebook uses it 59 | to plot a figure. 60 | 61 | ### Files in this repository 62 | ``` 63 | index.ipynb 64 | requirements.txt 65 | ``` 66 | ```eval_rst 67 | | 68 | | 69 | 70 | ``` 71 | --------- 72 | ## Conda environment with environment.yml 73 | 74 | [![Binder](http://mybinder.org/badge.svg)](http://mybinder.org/v2/gh/binder-examples/conda_environment/v1.0?filepath=index.ipynb) | [repo link](https://github.com/binder-examples/conda) 75 | 76 | A Binder-compatible repo with an `environment.yml` file. 77 | 78 | Access this Binder at the following URL: 79 | 80 | http://mybinder.org/v2/gh/binder-examples/conda_environment/v1.0?filepath=index.ipynb 81 | 82 | ### Notes 83 | The `environment.yml` file should list all Python libraries on which your notebooks 84 | depend, specified as though they were created using the following `conda` commands: 85 | 86 | ``` 87 | source activate example-environment 88 | conda env export > environment.yml 89 | ``` 90 | 91 | Note that the only libraries available to you will be the ones specified in 92 | the `environment.yml`, so be sure to include everything that you need! 93 | 94 | ### Files in this repository 95 | ``` 96 | environment.yml 97 | index.ipynb 98 | ``` 99 | ```eval_rst 100 | | 101 | | 102 | 103 | ``` 104 | --------- 105 | ## Remote Storage with Binder 106 | 107 | [![Binder](http://mybinder.org/badge.svg)](http://mybinder.org/v2/gh/binder-examples/remote_storage/master) | [repo link](https://github.com/binder-examples/remote_storage) 108 | 109 | A Binder-compatible repo that shows accessing data from remote sources. 110 | 111 | Access this Binder at the following URL: 112 | 113 | http://mybinder.org/v2/gh/binder-examples/remote_storage/master 114 | 115 | 116 | ### Notes 117 | The notebooks use `boto` and `requests` to load both images and tables from S3. 118 | The image loading makes use of `PIL` and the table loading 119 | makes use of `pandas`. 120 | 121 | ### Files in this repository 122 | ``` 123 | index.ipynb 124 | requirements.txt 125 | ``` 126 | ```eval_rst 127 | | 128 | | 129 | 130 | ``` 131 | --------- 132 | ## Using latex with Binder 133 | 134 | [![Binder](http://mybinder.org/badge.svg)](http://mybinder.org/v2/gh/binder-examples/latex/master) | [repo link](https://github.com/binder-examples/latex) 135 | 136 | This repository demonstrates how to install latex alongside matplotlib 137 | for Binder. This requires a few different build components: 138 | 139 | * `apt.txt` for apt-installing the latex components 140 | * `requirements.txt` for installing the python dependencies 141 | * `postBuild` for forcing matplotlib to build the font cache 142 | 143 | Thanks to [m-weigand](https://github.com/m-weigand) for giving 144 | [inspiration for this repo](https://github.com/m-weigand/binder-example-latex-mpl/blob/master/index.ipynb)! 145 | 146 | ### Files in this repository 147 | ``` 148 | apt.txt 149 | index.ipynb 150 | postBuild 151 | requirements.txt 152 | ``` 153 | ```eval_rst 154 | | 155 | | 156 | 157 | ``` 158 | --------- 159 | ## JupyterLab + Binder 160 | 161 | [![Binder](http://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/binder-examples/jupyterlab/master?urlpath=lab/tree/index.ipynb) | [repo link](https://github.com/binder-examples/jupyterlab) 162 | 163 | JupyterLab is packaged with Binder repositories by default. In order to 164 | run a JupyterLab session, you have two options: 165 | 166 | ### Start JupyterLab after you start your Binder 167 | 168 | Do the following: 169 | 170 | 1. Launch a Binder instance (e.g., by clicking the Binder badge) 171 | 2. Replace `tree` at the end of your URL with `lab`. 172 | 3. That's it! 173 | 174 | ### Create a Binder link that points to JupyterLab 175 | 176 | You can also create a Binder link that points to JupyterLab by adding the following 177 | to the end of your link: 178 | 179 | `?urlpath=lab` 180 | 181 | You can point to a specific file using JupterLab by including a file path 182 | beginning with `tree/` to the end of `urlpath`, like so: 183 | 184 | `?urlpath=lab/tree/path/to/my/notebook.ipynb` 185 | 186 | For example, the Binder badge above goes to the following URL: 187 | 188 | `http://mybinder.org/v2/gh/binder-examples/jupyterlab/master?urlpath=lab/tree/index.ipynb` 189 | 190 | Note: this repository also installs several JupyterLab extensions via a `postBuild` script, allowing 191 | you to use JupyterLab's extensions and widgets functionality. 192 | 193 | For a more complete demo of JupyterLab using Binder, see the 194 | [JupyterLab Demo](https://github.com/jupyterlab/jupyterlab-demo). 195 | 196 | ### Files in this repository 197 | ``` 198 | .profile 199 | .test 200 | .tmp 201 | binder 202 | geojson-extension.geojson 203 | index.ipynb 204 | ``` 205 | ```eval_rst 206 | | 207 | | 208 | 209 | ``` 210 | --------- 211 | ## Specifying an R environment with a runtime.txt file 212 | 213 | Jupyter+R: [![Binder](http://mybinder.org/badge.svg)](http://mybinder.org/v2/gh/binder-examples/r/master?filepath=index.ipynb) | [repo link](https://github.com/binder-examples/r) 214 | 215 | RStudio: [![Binder](http://mybinder.org/badge.svg)](http://mybinder.org/v2/gh/binder-examples/r/master?urlpath=rstudio) | [repo link](https://github.com/binder-examples/r) 216 | 217 | Binder supports using R + RStudio, with libraries pinned to a specific 218 | snapshot on [MRAN](https://mran.microsoft.com/documents/rro/reproducibility). 219 | 220 | You need to have a `runtime.txt` file that is formatted like: 221 | 222 | ``` 223 | r---
224 | ``` 225 | 226 | where YYYY-MM-DD is a snapshot at MRAN that will be used for installing 227 | libraries. 228 | 229 | You can also have an `install.R` file that will be executed during build, 230 | and can be used to install libraries. 231 | 232 | Both [RStudio](https://www.rstudio.com/) and [IRKernel](https://irkernel.github.io/) 233 | are installed by default, so you can use either the Jupyter notebook interface or 234 | the RStudio interface. 235 | 236 | ### Files in this repository 237 | ``` 238 | index.Rmd 239 | index.ipynb 240 | install.R 241 | runtime.txt 242 | ``` 243 | ```eval_rst 244 | | 245 | | 246 | 247 | ``` 248 | --------- 249 | ## Specifying a Python 2 environment with `runtime.txt` 250 | 251 | [![Binder](http://mybinder.org/badge.svg)](http://mybinder.org/v2/gh/binder-examples/python2_runtime/master) | [repo link](https://github.com/binder-examples/python2_runtime) 252 | 253 | We can specify various runtime parameters with a `runtime.txt` file. In this 254 | repository, we demonstrate how to install python 2 with the environment. 255 | 256 | If you specify `python-2.7` in `runtime.txt`, then: 257 | 258 | * A python3 environment is created & installed (this is what the notebook runs from) 259 | * A python2 environment is created and registered 260 | * The contents of `requirements.txt` are installed into the python2 environment 261 | 262 | **important:** 263 | Make sure that you save your notebooks with a python 2 kernel activated, 264 | as this defines which kernel Binder will use when a notebook is opened. 265 | 266 | **note:** 267 | If you *also* wish to install python 3 dependencies, you may do so 268 | by including a file called `requirements3.txt`. The packages 269 | inside will be installed into the python 3 environment. 270 | 271 | ### Files in this repository 272 | ``` 273 | index.ipynb 274 | requirements.txt 275 | runtime.txt 276 | ``` 277 | ```eval_rst 278 | | 279 | | 280 | 281 | ``` 282 | --------- 283 | ## Enabling Jupyter Extensions with post-build commands 284 | 285 | [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/binder-examples/jupyter-extension/master?filepath=index.ipynb) | [repo link](https://github.com/binder-examples/jupyter-extension) 286 | 287 | This example demonstrates how to enable Jupyter extensions with Binder. We'll 288 | cover a few in this repo because some are idiosyncratic in how they're enabled. 289 | 290 | We accomplish each using a `requirements.txt` file to install the extensions, 291 | then a `postBuild` file to enable them. 292 | 293 | ### ipywidgets 294 | 295 | Ipywidgets lets you create interactive widgets in your notebook. 296 | Installation is fairly straightforward. You install the python package, 297 | then enable the extension. 298 | 299 | ### python-markdown 300 | The `python-markdown` extension is useful for interweaving computational 301 | cells (e.g., python cells) and markdown cells. As this extension automatically 302 | runs code in the notebook, you need to be sure to "trust" the notebooks in your 303 | `postBuild` script (see the script in this repo for example). 304 | 305 | ### Files in this repository 306 | ``` 307 | index.ipynb 308 | postBuild 309 | requirements.txt 310 | ``` 311 | ```eval_rst 312 | | 313 | | 314 | 315 | ``` 316 | --------- 317 | ## Using conda with pip in the same build 318 | 319 | [![Binder](http://mybinder.org/badge.svg)](http://mybinder.org/v2/gh/binder-examples/python-conda_pip/master?filepath=index.ipynb) | [repo link](https://github.com/binder-examples/python-conda_pip) 320 | 321 | If you use `environment.yml`, then Binder will use a Miniconda distribution 322 | to install your packages. However, you may still want to use `pip`. In 323 | this case, you should **not** use a `requirements.txt` file, but instead use 324 | a `- pip` section in `environment.yml`. This repository is an example of how 325 | to construct your `environment.yml` file to accomplish this. 326 | 327 | ### Files in this repository 328 | ``` 329 | environment.yml 330 | index.ipynb 331 | ``` 332 | ```eval_rst 333 | | 334 | | 335 | 336 | ``` 337 | --------- 338 | ## Creating interactive presentations on Binder with RISE 339 | 340 | [![Binder](http://mybinder.org/badge.svg)](http://mybinder.org/v2/gh/binder-examples/jupyter-rise/master?filepath=index.ipynb) | [repo link](https://github.com/binder-examples/jupyter-rise) 341 | 342 | RISE allows you to quickly generate a live, interactive presentation from a 343 | Jupyter Notebook that is connected to the underlying Kernel of the notebook. 344 | Using a new feature for automatically launching 345 | the RISE plugin when a notebook is opened, RISE can be used to share interactive 346 | presentations that run in the cloud with Binder. 347 | This repository demonstrates how to accomplish this. 348 | 349 | To make your RISE presentation automatically-launch with it is open, 350 | add an `autolaunch=true` configuration 351 | parameter to a notebook's `livereveal` section in the 352 | metadata. E.g.: 353 | 354 | ``` 355 | ... 356 | "livereveal": { 357 | "autolaunch": true 358 | } 359 | ... 360 | ``` 361 | 362 | When the notebook is launched, your 363 | presentation will automatically begin. 364 | 365 | See the [RISE Documentation](https://damianavila.github.io/RISE/) 366 | for more information. 367 | 368 | ### Files in this repository 369 | ``` 370 | environment.yml 371 | index.ipynb 372 | ``` 373 | ```eval_rst 374 | | 375 | | 376 | 377 | ``` 378 | --------- 379 | ## Interactive apps from Jupyter Notebooks 380 | 381 | [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/binder-examples/appmode/master?urlpath=apps%2Findex.ipynb) | [repo link](https://github.com/binder-examples/appmode) 382 | 383 | This repository demonstrates how to create interactive webapps from a Jupyter Notebook. 384 | This is similar to how Shiny apps work in R. 385 | 386 | Using the `appmode` Jupyter plugin, a notebook's code will be run, and then only the markdown cells and 387 | code outputs will be shown. 388 | 389 | You can check out the `appmode` repository here: https://github.com/oschuett/appmode 390 | 391 | ### Files in this repository 392 | ``` 393 | environment.yml 394 | index.ipynb 395 | ipyvolume_demo.ipynb 396 | postBuild 397 | ``` 398 | ```eval_rst 399 | | 400 | | 401 | 402 | ``` 403 | --------- 404 | ## Using a Docker image from the Jupyter `docker-stacks` repository 405 | 406 | [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/binder-examples/jupyter-stacks/master) | [repo link](https://github.com/binder-examples/jupyter-stacks) 407 | 408 | Sometimes you just want to inherit from one of the pre-built images 409 | maintained by the Jupyter Project's [Docker Stacks](https://github.com/jupyter/docker-stacks), 410 | and perhaps add just an extra library or two. This example shows you how 411 | to do that - check out the Dockerfile. 412 | 413 | Note that in this case we are using a docker image that already satisfies 414 | the [criteria](http://mybinder.readthedocs.io/en/latest/dockerfile.html#preparing-your-dockerfile) 415 | for use on binder, we don't need to install notebook or anything manually. 416 | 417 | ### Files in this repository 418 | ``` 419 | Dockerfile 420 | ``` 421 | ```eval_rst 422 | | 423 | | 424 | 425 | ``` 426 | --------- 427 | ## Mixing Python 2 and 3 kernels with `runtime.txt` 428 | 429 | [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/binder-examples/python2_with_3/master) | [repo link](https://github.com/binder-examples/python2_with_3) 430 | 431 | Sometimes you want *both* Python 2 and Python 3 (e.g., if you have a mixture of notebooks that use each 432 | version of the language). This repository demonstrates how to handle these cases with `repo2docker`. You can 433 | specify a Python 2.7 environment with the `runtime.txt` file. In this case, `repo2docker` will install Python 2 434 | *alongside* Python 3 (though all commands will default to Python 2). In this case, you can install Python 3 dependencies 435 | with `requirements3.txt`, while a file called `requirements.txt` alone will install to the Python 2 environment. 436 | ### Files in this repository 437 | ``` 438 | index2.ipynb 439 | index3.ipynb 440 | requirements.txt 441 | requirements3.txt 442 | runtime.txt 443 | ``` 444 | ```eval_rst 445 | | 446 | | 447 | 448 | ``` 449 | --------- 450 | ## Installing packages from `apt` repositories 451 | 452 | [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/binder-examples/apt_install/master?filepath=index.ipynb) | [repo link](https://github.com/binder-examples/apt_install) 453 | 454 | Sometimes you want packages that exist outside of the language-specific packaging 455 | ecosystems of Python/R/Julia. Binder makes it possible to `apt-install` packages 456 | from the ubuntu apt repository. This repository demonstrates how to do this by specifying 457 | names in an `apt.txt` file. 458 | ### Files in this repository 459 | ``` 460 | apt.txt 461 | index.ipynb 462 | postBuild 463 | ``` 464 | ```eval_rst 465 | | 466 | | 467 | 468 | ``` 469 | --------- 470 | ## Importing data with Quilt 471 | 472 | [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/binder-examples/data-quilt/master?filepath=index.ipynb) | [repo link](https://github.com/binder-examples/data-quilt) 473 | 474 | ### Pull data into Binder notebooks 475 | This example uses [Quilt](http://quiltdata.com) to inject data packages into a Jupyter notebook. 476 | 477 | Data packages are versioned, immutable snapshots of data. Data packages may contain data of any size. Here is an example of data package: [uciml/iris](https://quiltdata.com/package/uciml/iris). 478 | 479 | ### How to specify data dependencies in your own Binder 480 | 481 | 1. Add `quilt` to `requirements.txt` 482 | 483 | 2. Specify data package dependencies in `quilt.yml` ([docs](https://docs.quiltdata.com/cli.html)). For example: 484 | 485 | ``` 486 | packages: 487 | - vgauthier/DynamicPopEstimate # get the latest version 488 | - danWebster/sgRNAs:a972d92 # get a specific hash (short hash) 489 | - akarve/sales:tag:latest # get a specific tag 490 | - asah/snli:v:1.0 # get a specific version 491 | ``` 492 | 493 | 3. Include the following lines at the top of `postBuild`. (`postBuild` should be executable: `chmod +x postBuild` on UNIX, `git update-index --chmod=+x postBuild` for Windows). 494 | 495 | ``` bash 496 | ##!/bin/bash 497 | quilt install 498 | ``` 499 | 500 | Now you can access the package data in your Jupyter notebooks: 501 | 502 | ``` 503 | In [1]: from quilt.data.akarve import sales 504 | In [2]: sales.transactions() 505 | Out[2]: 506 | Row ID Order ID Order Date Order Priority Order Quantity Sales \ 507 | 0 1 3 2010-10-13 Low 6 261.5400 508 | 1 49 293 2012-10-01 High 49 10123.0200 509 | 2 50 293 2012-10-01 High 27 244.5700 510 | ... 511 | ``` 512 | 513 | ### Developer 514 | 515 | * [Quilt repository](https://github.com/quiltdata/quilt) 516 | * [Quilt docs](https://docs.quiltdata.com) 517 | 518 | ### Files in this repository 519 | ``` 520 | index.ipynb 521 | postBuild 522 | quilt.yml 523 | requirements.txt 524 | ``` 525 | ```eval_rst 526 | | 527 | | 528 | 529 | ``` 530 | --------------------------------------------------------------------------------