Preparing a Binder repository
How to perform this step?¶
Prepare your files¶
Prepare your repository for use with the BinderHub
:
- The online repository (e.g., on GitHub or BitBucket) containing the notebook is public
- The repository does not require any personal or sensitive information (such as passwords)
- The repository has configuration files that specify its environment (e.g. environment.yml, requirements.txt)
Let's consider a simple model housed in the following repository.
If we inspect the contents of this repository, we see the following files:
./
├── environment.yml
├── simpleModel.ipynb
└── README.md
In this case, we have two important files:
- A content (Notebook) file:
simpleModel.ipynb
is a simple example using line fitting. In this case, we are trying to predicty
(the output), given the input datax
and input parametersa,b,c
according to the following equation:y=ax+b+c
. The input datax
is contained in a.csv
file and the model outputsy
in a.csv
file. - An environment configuration file:
environment.yml
is a standard file that specifies an Anaconda environment. The environment contains information about the packages needed to execute the notebook. To learn how to createenvironment.yml
file from Anaconda, follow this guide.
Importart
You may notice that environment.yml
is not Binder-specific. This is
intentional! Binder tries to use environment configuration files that
are already standards in the data science community. For a list of all
configuration files available, see the Binder page.
Build your repository¶
Next, let's build your Binder repository. Head to https://mybinder.org. You'll see a form that asks you to specify a repository for mybinder.org to build. In the first field, paste the URL of your forked repository. It'll look something like this:
https://github.com/<your-username>/simpleModel-1
Finally, click the launch button. This will ask mybinder.org to build the environment needed to run the repository. You can click on the "Build logs" button to see the logs generated by the build process.
While your Binder repository is building, note the URL that points to your unique Binder. You can share this URL with a friend, allowing them to access an interactive version of your repository.
See below for a quick layout of the BinderHub user interface.
If your Binder repository has already been built once, then subsequent clicks on the Binder link will not re-trigger the build process. However, if you push any changes to the repository, then it will be re-built the next time somebody clicks a link.
If your environment files and content files are not housed in the same branch of the same repository, see this documentation on how to generate a URL.
Now that you're acquainted with Binder, see this page for more information about what you can do with it.