Sample build repositories

There are many options for specifying your environment with repo2docker. The following sections describe a few samples to get you started.

Note

These files must be in the root of your repository, or in a folder called binder that is in the root of your repository. If you include a folder called binder in the root of your repository, then all build files not inside this folder will be ignored.

System - Post-build scripts

It is possible to run scripts after you’ve built the environment specified in your other files. This could be used to, for example, download data or run some configuration scripts. For example, this will download and install a Jupyter extension.

File: requirements.txt

Contents:

ipyleaflet

File: postBuild

Contents:

#!/bin/bash

jupyter nbextension enable --py --sys-prefix ipyleaflet

System - Specifying runtime environments

You can specify runtime environments (such as Python 2 or 3) with a runtime.txt file.

File: requirements.txt

Contents:

numpy

File: runtime.txt

Contents:

python-2.7

System - APT Packages

It is possible to install packages using the Shell with the apt.txt file. In this case we install gfortran which does not have an easy Python install.

File: apt.txt

Contents:

# testing to skip comments in this file



gfortran



# testing to see if all packages get installed

unp

byacc

Python - Requirements.txt

The simplest way to specify Python packages is with a requirements.txt file that is compatible with pip install.

File: requirements.txt

Contents:

numpy

Julia - REQUIRE

The simplest way to specify dependencies in Julia, a REQUIRE file simply lists the names of packages. Each one will be installed but not pre-compiled. In this case, we also specify python dependencies with an environment.yml file.

File: environment.yml

Contents:

dependencies:

  - matplotlib

File: REQUIRE

Contents:

PyPlot

Docker - Specifying dependencies

You can specify dependencies with Dockerfiles, which may be more flexible in running non-standard code. We recommend sourcing your Dockerfile from one of the Jupyter base images. In this case, we use a stripped-down image that has minimal dependencies installed.

File: Dockerfile

Contents:

FROM jupyter/base-notebook:b4dd11e16ae4



RUN pip install there

ADD verify verify

Docker - Running scripts

It’s possible to run scripts using Docker in your build. In this case, we run a simple shell script after installing dependencies. However, we recommend that you see if it’s possible to accomplish what you want using apt and postInstall files, and use Dockerfiles only when necessary.

File: Dockerfile

Contents:

FROM python:3.5



ENTRYPOINT "/bin/sh"



ADD sayhi.sh /usr/local/bin/sayhi.sh

ADD verify verify

File: sayhi.sh

Contents:

#!/bin/bash

echo hi

exit 0

Docker - Legacy Dockerfiles

This demonstrates the Dockerfile syntax that was often found in the first version of Binder. It sources the andrewosh Docker image, which contained many different dependencies, then installs Julia. We encourage users to source one of the Jupyter base images as they are more streamlined.

File: Dockerfile

Contents:

FROM andrewosh/binder-base



USER root



# Add Julia dependencies

RUN apt-get update

RUN apt-get install -y julia libnettle4 && apt-get clean



USER main



# Install Julia kernel

RUN julia -e 'Pkg.add("IJulia")'

RUN julia -e 'Pkg.add("Gadfly")' && julia -e 'Pkg.add("RDatasets")'



ADD verify verify

R environment - install.R

You can install an R, RStudio, and IRKernel environment with the following two files:

  • A runtime.txt file with the text:

    r-YYYY-MM-DD

    Where ‘YYYY’, ‘MM’ and ‘DD’ refer to a specific date snapshot of https://mran.microsoft.com/timemachine from which libraries will be installed.

  • An optional install.R file that will be executed by an R installation at build time. It can be used for installing packages from MRAN or GitHub.

The presence of runtime.txt is enough to set up R, RStudio, and IRKernel. It uses the r-base package from the Ubuntu apt repositories to install R itself.

File: install.R

Contents:

install.packages("ggplot2")

File: runtime.txt

Contents:

r-2017-10-24

Conda - Mixed Requirements

An environment.yml takes precedence over requirements.txt. To install Python packages into a conda environment with pip, use the pip key in environment.yml:

dependencies:
  - numpy
  - pip:
    - tornado

File: requirements.txt

Contents:

there

File: environment.yml

Contents:

dependencies:

  - numpy

  - pip:

    - simplejson

Conda Environment

Conda environments files may allow for more complex builds and dependencies. You can specify them in the standard environment.yml files.

File: environment.yml

Contents:

dependencies:

  - numpy

Conda Environment

Conda environments files may allow for more complex builds and dependencies. You can specify them in the standard environment.yml files.

File: environment.yml

Contents:

dependencies:

  - python=2

  - numpy