kopia lustrzana https://github.com/jupyterhub/repo2docker
J. Forde
rodzic
0f0ce8a950
commit
2d6f32e588
|
|
@ -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 <https://mybinder.readthedocs.io/en/latest/dockerfile.html>`_ for
|
||||
best-practices with Dockerfiles or
|
||||
`our Dockerfile-rstudio example <https://github.com/binder-examples/dockerfile-rstudio>`_
|
||||
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 <https://github.com/binder-examples/python-conda_pip/blob/master/environment.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 <https://github.com/binder-examples/requirements/blob/master/requirements.txt>`_
|
||||
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 <https://github.com/binder-examples/julia-python>`_.
|
||||
|
||||
``install.R``
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
This is used to install R libraries pinned to a specific snapshot on
|
||||
`MRAN <https://mran.microsoft.com/documents/rro/reproducibility>`_.
|
||||
To see an example, visit our `example install.R file <https://github.com/binder-examples/r/blob/master/install.R>`_.
|
||||
|
||||
``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 <https://github.com/binder-examples/latex/blob/master/apt.txt>`_.
|
||||
|
||||
|
||||
``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 <https://github.com/jupyterlab/jupyterlab-demo/blob/master/binder/postBuild>`_.
|
||||
|
||||
``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 <https://github.com/binder-examples/python2_runtime/blob/master/runtime.txt>`_.
|
||||
|
||||
repo2docker uses R libraries pinned to a specific snapshot on
|
||||
`MRAN <https://mran.microsoft.com/documents/rro/reproducibility>`_.
|
||||
You need to have a runtime.txt file that is formatted as
|
||||
``r-<YYYY>-<MM>-<DD>``, 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 <https://github.com/binder-examples/r/blob/master/runtime.txt>`_.
|
||||
|
|
@ -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 <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
|
||||
|
|
@ -13,12 +13,12 @@ Please report `Bugs <https://github.com/jupyter/repo2docker/issues>`_,
|
|||
Site Contents
|
||||
-------------
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 1
|
||||
|
||||
install
|
||||
usage
|
||||
config_files
|
||||
faq
|
||||
samples
|
||||
design
|
||||
architecture
|
||||
dev_newbuildpack
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -24,41 +24,33 @@ Preparing your repository
|
|||
to determine how to build it. It is philosophically similar to
|
||||
`Heroku Build Packs <https://devcenter.heroku.com/articles/buildpacks>`_.
|
||||
|
||||
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 <https://github.com/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:
|
||||
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue