mirror
/
repo2docker
kopia lustrzana https://github.com/jupyterhub/repo2docker
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

reorganized to close #332 and closes #333

pull/338/head
J. Forde 2018-07-01 17:27:39 -07:00
rodzic 9803f9f0cf
commit 29762f4de0
5 zmienionych plików z 117 dodań i 118 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

33
docs/source/config_files.rst
Wyświetl plik

@ -1,9 +1,32 @@
.. _config-files:
Supported configuration files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configuration Files
~~~~~~~~~~~~~~~~~~~
Below is a list of supported configuration files (roughly in the order of build priority).
``repo2docker`` looks for configuration files in the repository being built
to determine how to build it. It is philosophically similar to
`Heroku Build Packs <https://devcenter.heroku.com/articles/buildpacks>`_.
In general, ``repo2docker`` uses the same configuration files as other software
installation tools, rather than creating new custom configuration files.
These files are described in :ref:`config-files`.
``repo2docker`` configuration files are **composable**- you can use any number
of them in the same repository.
``repo2docker`` will look for configuration files in either:
* A folder named ``binder`` in the root of the repository.
* The root of the repository.
If the folder ``binder`` is located at the top level of the repository,
**only configuration files in the** ``binder`` **folder will be considered**.
`binder examples <https://github.com/binder-examples>`_ contains a list of
example repositories that can be built with ``repo2docker`` with various
configuration files.
Below is a list of supported configuration files (roughly in the order of build priority):
.. contents::
:local:
@ -22,6 +45,8 @@ With Dockerfiles, a regular Docker build will be performed.
See the `Binder Documentation <https://mybinder.readthedocs.io/en/latest/dockerfile.html>`_ for
best-practices with Dockerfiles.
.. _environment-yml:
``environment.yml``
^^^^^^^^^^^^^^^^^^^
@ -75,6 +100,8 @@ While one can specify dependencies in ``setup.py``,
repo2docker **requires configuration files such as** ``environment.yml`` or
``requirements.txt`` to install dependencies during the build process.
.. _postBuild:
``postBuild``
^^^^^^^^^^^^^

12
docs/source/faq.md
Wyświetl plik

@ -1,17 +1,15 @@
# Frequently Asked Questions (FAQ)
A collection of frequently asked questions with answers!
If you have a question & have found an answer, send a PR to add it here!
A collection of frequently asked questions with answers. If you have a question
and have found an answer, send a PR to add it here!
## How should I specify another version of Python 3?
Currently the best way to do this is by using a conda ``environment.yml``
file and setting the language to whichever version of Python you like.
One can specify a Python version in the ``environment.yml`` file of a repo.
## Can I add executable files to the user's PATH?
Yes! Using a ``postBuild`` file, you can place any files that should be called
Yes! With a :ref:`postBuild` file, you can place any files that should be called
from the command line in the folder ``~/.local/``. This folder will be
available in a user's PATH, and can be run from the command line (or as
a subsequent build step.)
@ -36,4 +34,4 @@ Hence the output of `--debug` can not be built with a normal `docker build -t .`
or similar traditional docker command.
Check out the [binder-examples](http://github.com/binder-examples/) github
organization for example Dockerfiles you can copy & modify for your own use!
organization for example repositories you can copy & modify for your own use!

7
docs/source/index.rst
Wyświetl plik

@ -2,8 +2,11 @@ jupyter-repo2docker
===================
**jupyter-repo2docker** is a tool to build, run, and push Docker
images from source code repositories. See the list below for various
ways in which you can use ``repo2docker``.
images from source code repositories. repo2docker fetches a repo
(e.g., from GitHub or other locations) and builds a container image based
on the specifications found in the repo.
Optionally, it can launch a local
Jupyter Notebook which you can use to explore it.
Please report `Bugs <https://github.com/jupyter/repo2docker/issues>`_,
`ask questions <https://gitter.im/jupyterhub/binder>`_ or

32
docs/source/install.rst
Wyświetl plik

@ -3,10 +3,24 @@
Installing ``repo2docker``
==========================
repo2docker requires Python 3.4 and above on Linux and macOS. See
:ref:`below <windows>` for more information about Windows support.
Prerequisite: docker
--------------------
Install `Docker <https://www.docker.com>`_ as it is required to build Docker images.
Install `Docker <https://www.docker.com>`_ as it is required
to build Docker images. The
`Community Edition <https://www.docker.com/community-edition>`_,
is available for free.
Recent versions of Docker are recommended.
The latest version of Docker, ``18.03``, successfully builds repositories from
`binder-examples <https://github.com/binder-examples>`_.
The `BinderHub <https://binderhub.readthedocs.io/>`_ helm chart uses version
``17.11.0-ce-dind``. See the
`helm chart <https://github.com/jupyterhub/binderhub/blob/master/helm-chart/binderhub/values.yaml#L167>`_
for more details.
Installing with ``pip``
-----------------------
@ -30,13 +44,23 @@ i.e. if you are contributing back to this project::
That's it! For information on using ``repo2docker``, see
:ref:`usage`.
Note about Windows support
--------------------------
.. _windows:
Windows support by ``repo2docker`` is still in the experimental stage.
Windows support
---------------
Windows support by ``repo2docker`` is still in the experimental stage.
An article about `using Windows and the WSL`_ (Windows Subsytem for Linux or
Bash on Windows) provides additional information about Windows and docker.
.. _using Windows and the WSL: https://nickjanetakis.com/blog/setting-up-docker-for-windows-and-wsl-to-work-flawlessly
JupyterHub-ready images
-----------------------
To build `JupyterHub <https://github.com/jupyterhub/jupyterhub>`_-ready
Docker images with ``repo2docker``, the version of your JupterHub deployment
must be included in the ``environment.yml`` or ``requiements.txt`` of the
git repositories you build.

151
docs/source/usage.rst
Wyświetl plik

@ -3,108 +3,74 @@
Using ``repo2docker``
=====================
The core functionality of repo2docker is to fetch a repo (e.g., from GitHub or
other locations) and build a container image based on the specifications found in the
repo. Optionally, it can launch a local Jupyter Notebook which you can use to explore it.
`Docker <https://docs.docker.com/>`_ **must be running ** in
order to run ``repo2docker``. For more information on installing
``repo2docker``, see :ref:`install`.
This section describes the general ways in which you can use
``repo2docker``, including:
.. contents::
:depth: 1
:local:
See the `Frequently Asked Questions <faq.html>`_ for additional information.
Preparing your repository
-------------------------
``repo2docker`` looks for configuration files in the repository being built
to determine how to build it. It is philosophically similar to
`Heroku Build Packs <https://devcenter.heroku.com/articles/buildpacks>`_.
In general, ``repo2docker`` uses the same configuration files as other software
installation tools, rather than creating new custom configuration files.
These files are described in :ref:`config-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:
* 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:
* If the folder ``binder`` is located at the top level of the repository,
**only configuration files in the** ``binder`` **folder will be considered**.
* 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`_.
For a list of repositories demonstrating various configurations, see
`binder examples <https://github.com/binder-examples>`_.
Preparing a repo to build JupyterHub-ready images
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is possible to use ``repo2docker`` to build JupyterHub-ready
Docker images. For this to work properly, the version of the ``jupyterhub``
package in your git repository must match the version in your JupyterHub
deployment. For example, if your JupyterHub deployment runs ``jupyterhub==0.8``,
you should put the following in ``requirements.txt`` or ``environment.yml``::
jupyterhub==0.8.*
Running ``repo2docker`` locally
-------------------------------
`Docker <https://docs.docker.com/>`_ **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:
``repo2docker`` performs two steps:
1. builds a Docker image from a git repo
2. runs a Jupyter server within the image
2. runs a Jupyter server within the image to explore the repo
This two step process enables you to build an image and run it so you can
explore the repository's contents.
To ensure you can run the software in your repository, you must
The **command** used is::
repo2docker is called with a simple command::
jupyter-repo2docker <URL-or-path to repo>
where ``<URL-or-path to repo>`` provides a URL or path to the source repository.
where ``<URL-or-path to repo>`` is a URL or path to the source repository.
For example, use the following to build an image and launch a Jupyter Notebook
server::
For example, use the following to build an image of the
`Python Data Scinece Handbook <https://github.com/jakevdp/PythonDataScienceHandbook>`_::
jupyter-repo2docker https://github.com/jakevdp/PythonDataScienceHandbook
When the example completes building (which may take a few minutes), a message will
be output to your terminal::
To build a particular branch and commit, we use the argument ``--ref`` to
specify the ``branch-name/commit-hash``::
jupyter-repo2docker https://github.com/jakevdp/PythonDataScienceHandbook --ref master/599aa0fe3f882c0001670e676e5a8d43b92c35fc
Building the image may take a few minutes.
During building, ``repo2docker``
clones the repository to obtain its contents and inspects the repo for
:ref:`configuration files <config-files>`.
`Python Data Scinece Handbook <https://github.com/jakevdp/PythonDataScienceHandbook>`_
uses a `requirements.txt file <https://github.com/jakevdp/PythonDataScienceHandbook/blob/master/requirements.txt>`_
to specify its Python environment. ``repo2docker`` uses ``pip`` to install
dependencies listed in the ``requirement.txt`` in image. To learn more about
configuration files in ``repo2docker`` visit :ref:`config-files`.
When the image is built, a message will be output to your terminal::
Copy/paste this URL into your browser when you connect for the first time,
to login with a token:
http://0.0.0.0:36511/?token=f94f8fabb92e22f5bfab116c382b4707fc2cade56ad1ace0
If you copy/paste that URL into your browser you will see a Jupyter Notebook with the
contents of the source repository which you have just built.
Pasting the URL into your browser will open Jupyter Notebook with the
dependencies and contents of the source repository in the built image.
Using the ``--debug`` and ``--no-build`` parameters
---------------------------------------------------
Because JupyterLab is a server extension of the classic Jupyter Notebook server,
you can launch JupyterLab by opening Jupyter Notebook and visiting the
```/lab`` to the end of the URL:
If you want to debug and understand the details of the docker image being built,
you can pass the ``debug`` parameter to the commandline:
.. code-block:: none
http(s)://<server:port>/<lab-location>/lab
To switch back to the classic notebook, add ``/tree`` to the URL:
.. code-block:: none
http(s)://<server:port>/<lab-location>/tree
To learn more about URLs in JupyterLab and Jupyter Notebook, visit
`starting JupyterLab <http://jupyterlab.readthedocs.io/en/latest/getting_started/starting.html>`_.
``--debug`` and ``--no-build``
------------------------------
To debug the docker image being built, pass the ``--debug`` parameter:
.. code-block:: bash
@ -120,22 +86,3 @@ be used by docker directly.
.. code-block:: bash
jupyter-repo2docker --no-build --debug https://github.com/jakevdp/PythonDataScienceHandbook
Setting environment variables
-----------------------------
If you want to define environment variables, you can pass the ``--env`` or ``-e`` parameter to the commandline:
.. code-block:: bash
jupyter-repo2docker -e VAR1=val1 -e VAR2=val2 ...
Accessing help from the command line
------------------------------------
For a list of all the build configurations at your disposal, see the
CLI help::
jupyter-repo2docker -h
.. _conda documentation: https://conda.io/docs/user-guide/tasks/manage-environments.html#creating-an-environment-file-manually