diff --git a/docs/source/config_files.rst b/docs/source/config_files.rst new file mode 100644 index 00000000..394cf801 --- /dev/null +++ b/docs/source/config_files.rst @@ -0,0 +1,107 @@ +.. _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 `_ for +best-practices with Dockerfiles or +`our Dockerfile-rstudio example `_ +for using repo2docker to set up RStudio. + +``environment.yml`` +^^^^^^^^^^^^^^^^^^^ + +This is a conda environment specification, that lets you install packages with conda. +You can also install files from pip in your ``environment.yml`` as well. +Our example `enviornment.yml `_ +shows how one can specify a conda enviornment for repo2docker. + +``requirements.txt`` +^^^^^^^^^^^^^^^^^^^^ + +This specifies a list of Python packages that should be installed in a +virtualenv (or conda environment). Our `requirements.txt example `_ +on GitHub shows a typical requirements file. + +``REQUIRE`` +^^^^^^^^^^^ + +This specifies a list of Julia packages. Repositories with a ``REQUIRE`` file +**must also contain an** ``environment.yml`` **file**. To see an example of a +Julia repository with ``REQUIRE`` and ``environment.yml``, +visit `binder-examples/julia-python `_. + +``install.R`` +^^^^^^^^^^^^^ + +This is used to install R libraries pinned to a specific snapshot on +`MRAN `_. +To see an example, visit our `example install.R file `_. + +``apt.txt`` +^^^^^^^^^^^ + +A list of Debian packages that should be installed. The base image used is usually the latest released +version of Ubuntu. + +We use ``apt.txt``, for example, to install LaTeX in our +`example apt.txt for LaTeX `_. + + +``setup.py`` +^^^^^^^^^^^^ + +To install your repository like a Python file, you may include a +``setup.py`` file. While one can specify dependencies in ``setup.py``, +repo2docker **requires configuration files such as** ``environment.yml`` or +``requirements.txt`` + +``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`. +This file **must be executable** to be used with ``repo2docker``. To do this, +run the following:: + + chmod +x postBuild + +An example usecase of ``postBuild`` file is JupyterLab's demo on mybinder.org. +It uses a ``postBuild`` file in a folder called ``binder`` to `prepare +their demo for binder `_. + +``runtime.txt`` +^^^^^^^^^^^^^^^ + +This allows you to control the runtime of Python or R. + +To use Python 2, put the line ``python-2.7`` in the file. +A Python 2 kernel will be installed alongside Python 3. To see a full example +repository, visit our +`Python2 example in binder-examples `_. + +repo2docker uses R libraries pinned to a specific snapshot on +`MRAN `_. +You need to have a runtime.txt file that is formatted as +``r---
``, where YYYY-MM-DD is a snapshot at MRAN that will be +used for installing libraries. + +To see an example R repository, visit our `R +example in binder-examples `_. diff --git a/docs/source/config_files.txt b/docs/source/config_files.txt deleted file mode 100644 index 94c6f9c3..00000000 --- a/docs/source/config_files.txt +++ /dev/null @@ -1,116 +0,0 @@ -.. _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 `_ 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 - 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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 9ad490fe..7e8eb38d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,12 +13,12 @@ Please report `Bugs `_, Site Contents ------------- .. toctree:: - :maxdepth: 2 + :maxdepth: 1 install usage + config_files faq - samples design architecture dev_newbuildpack diff --git a/docs/source/samples.rst b/docs/source/samples.rst deleted file mode 100644 index ad86543a..00000000 --- a/docs/source/samples.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _samples: - -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. - -.. include:: test_file_text.txt diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 9b1f1433..d9c5d251 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -24,41 +24,33 @@ Preparing your repository to determine how to build it. It is philosophically similar to `Heroku Build Packs `_. +In general, ``repo2docker`` uses configuration files that are already part of +various data science workflows (e.g., ``requirements.txt``), rather than +creating new custom configuration files. + +``repo2docker`` configuration files are all **composable** - you can use any number +of them in the same repository. + Locating and composing configuration files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -``repo2docker`` will look for configuration files **located** in two places: +``repo2docker`` will look for configuration files located in two places: -* A folder called ``binder`` in the root of the repository. -* The root of the repository. (If a folder called ``binder`` exists in the root - of the repository, configuration files outside of that folder will be ignored.) - -.. note:: - - In general, ``repo2docker`` uses configuration files that are already part of - various data science workflows (e.g., ``requirements.txt``), rather than - creating new custom configuration files. - -``repo2docker`` configuration files are all **composable** - you can use any number -of them in the same repository. +* A folder named ``binder`` in the root of the repository. +* The root of the repository. There are a few notable rules for composition precedence and build priority: -* ``Dockerfile``: If a Dockerfile is present in a repository, it will take precedence - over all other configuration files (which will be ignored). -* ``environment.yml`` with ``requirements.txt``: If both of these files are - present, then ``environment.yml`` will be used to build the image, **not** - ``requirements.txt``. If you wish to ``pip install`` packages using an - ``environment.yml`` file, you should do so with the +* If the folder ``binder`` is the root + directory, **configuration files in the root directory will be ignored**. +* If a Dockerfile is present, **all other files will be ignored**. +* ``environment.yml`` **takes precedent over** + ``requirements.txt``. If you wish to install ``pip`` packages + with ``environment.yml``, please use the ``pip:`` key as described in the `conda documentation`_. - .. note:: - - For a list of repositories demonstrating various configurations, - see :ref:`samples`. - -.. *** List of all configuration files *** -.. include:: config_files.txt +For a list of repositories demonstrating various configurations, see +`binder examples `_. Preparing a repo to build JupyterHub-ready images ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -74,12 +66,10 @@ you should put the following in ``requirements.txt`` or ``environment.yml``:: Running ``repo2docker`` locally ------------------------------- -For information on installing ``repo2docker``, see :ref:`install`. - -.. note:: - - Docker must be running on your machine in order to build images +Docker **must be running on your machine** in order to build images with ``repo2docker``. + For more information on installing ``repo2docker``, see :ref:`install`. + The simplest invocation of ``repo2docker`` performs two steps: