Customising your workspace

Owned by Mark Moloney
Last updated: Jul 11, 2020
3 min read

A workspace is created on demand at the start of your session when you click the ‘Build Shed’ button. A workspace uses a Linux-based image as the starting point. Workspace builds follow The Reproducible Execution Environment Specification (REES).

The goal of the REES is to automate and encourage existing community best practices for reproducible computational environments. This includes installing packages using community-standard specification files and their corresponding tools, such as requirements.txt (with Python and pip), REQUIRE (with Julia), or apt.txt (with apt). A user should be able to look at a REES-compliant repository and reproduce the environment using common, clear steps independently of DEVsheds.

The configuration files have to all be placed either in the root of the project repository, in a binder sub-directory or a .binder sub-directory.

For example, the REES recognises requirements.txt as a valid config file. The file format is as defined by the requirements.txt standard of the Python community.

Supported configuration files

Supported configuration files include:

Python

  • environment.yml - install a conda (Python) environment

    • environment.yml is the standard configuration file used by conda that lets you install any kind of package, including Python, R, and C/C++ packages.

    • Note: this configuration updates a predefined base conda environment, which means that the environment will always have the same default name, not the name specified in your environment.yml.

    • You can also specify which Python version to install in your built environment with environment.yml. The default preinstalled version (to support Jupyter notebooks) is Python 3.7 unless you include a specific Python version in this file.

    • Note that if you include a Python version in a runtime.txt file in addition to your environment.yml, your runtime.txt will be ignored.

  • Pipfile (and/or Pipfile.lock) - install a Python environment using pipenv

    • pipenv allows you to manage a virtual environment Python dependencies. When using pipenv, you end up with Pipfile and Pipfile.lock files. The lock file contains explicit versions of the packages previously installed.

    • Note that Pipfile.lock takes precedence over a Pipfile.

  • requirements.txt - install a Python environment using pip

    • This specifies a list of Python packages that should be installed in your environment.

  • setup.py - install Python packages

    • To install your repository like a Python package, you may include a setup.py file.

Julia

  • Project.toml - install a Julia environment

    • A Project.toml (or JuliaProject.toml) file can specify both the version of Julia to be used and a list of Julia packages to be installed. If a Manifest.toml is present, it will determine the exact versions of the Julia packages that are installed.

  • REQUIRE - install a Julia environment (legacy)

    • A REQUIRE file can specify both the version of Julia to be used and which Julia packages should be used. The use of REQUIRE is only recommended for pre-1.0 Julia versions. The recommended way of installing a Julia environment that uses Julia 1.0 or newer is to use a Project.toml file.

    • Note that if both a REQUIRE and a Project.toml file are detected, the REQUIRE file is ignored.

R language

  • install.R - install an R/RStudio environment

    • This is used to install R libraries pinned to a specific snapshot on MRAN. To set the date of the snapshot add a runtime.txt.

Debian packages

  • apt.txt - install Linux packages with apt-get

    • A list of Debian packages that should be installed.

General Linux packages

  • default.nix - the nix package manager

    • Specify packages to be installed by the nix package manager.

    • Note that when using this config file all other configuration files (like requirements.txt) that specify packages are ignored.

    • Also make sure to pin your nixpkgs to produce a reproducible environment.

Build Lifecycle Hooks

  • postBuild - run code after installing the environment

    • A script that can contain arbitrary commands to be run after the whole repository has been built. If you want this to be a shell script, make sure the first line is #!/bin/bash.

    • Note that by default the build will not be stopped if an error occurs inside a shell script. You should include set -e or the equivalent at the start of the script to avoid errors being silently ignored.

  • start - run code before the user session starts

    • A script that can contain simple commands to be run at runtime (as an ENTRYPOINT to the docker container). If you want this to be a shell script, make sure the first line is #!/bin/bash. The last line must be exec "$@" or equivalent.

    • Use this to set environment variables that software installed in your container expects to be set. This script is executed each time your binder is started and should at most take a few seconds to run.

    • If you only need to run things once during the build phase use postBuild instead.