.. _config-files:

Supported configuration files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Below is a list of supported configuration files (roughly in the order of build priority).

.. contents::
   :local:
   :depth: 1

``Dockerfile``
^^^^^^^^^^^^^^

This will be treated as a regular Dockerfile and a regular Docker build will be performed.
The presence of a Dockerfile takes priority over and ignores all other build behavior
specified in other configuration files.

In the majority of cases, providing your own Dockerfile is not necessary as the base
images provide core functionality, compact image sizes, and efficient builds. We recommend
trying the other configuration files before deciding to use your own Dockerfile.

See the `Binder Documentation <https://mybinder.readthedocs.io/en/latest/dockerfile.html>`_ for
best-practices with Dockerfiles.

``environment.yml``
^^^^^^^^^^^^^^^^^^^

This is a conda environment specification, that lets you install packages with conda.

Example Contents
````````````````
::

  channels:
    - conda-forge
    - defaults
  dependencies:
    - matplotlib
    - pip:
      - sphinx-gallery

``requirements.txt``
^^^^^^^^^^^^^^^^^^^^

This specifies a list of Python packages that should be installed in a virtualenv (or conda environment).

Example Contents
````````````````
::

   numpy==1.7
   matplotlib==2.1

``REQUIRE``
^^^^^^^^^^^

This specifies a list of Julia packages.

.. note::

   Using a ``REQUIRE`` file also requires that the repository contain an
   ``environment.yml`` file.

Example Contents
````````````````
::

  PyPlot
  Stats

``apt.txt``
^^^^^^^^^^^

A list of Debian packages that should be installed. The base image used is usually the latest released
version of Ubuntu.

Example Contents
````````````````
::

   cowsay
   fortune

``postBuild``
^^^^^^^^^^^^^

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`.

Example Contents
````````````````
::

   wget <url-to-dataset>
   python myfile.py

.. note::

   This file must be executable to be used with ``repo2docker``. To do this,
   run the following::

     chmod +x postBuild

``runtime.txt``
^^^^^^^^^^^^^^^

This allows you to control the runtime of Python. To use Python 2,
put the line ``python-2.7`` in the file. A Python 2 kernel will be installed
alongside Python 3.

Example Contents
````````````````
::

   python-2.7