diff --git a/README.md b/README.md index dcfb5f5d..36f55cd0 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,11 @@ [![Build Status](https://travis-ci.org/jupyter/repo2docker.svg?branch=master)](https://travis-ci.org/jupyter/repo2docker) [![Documentation Status](https://readthedocs.org/projects/repo2docker/badge/?version=latest)](http://repo2docker.readthedocs.io/en/latest/?badge=latest) - -**jupyter-repo2docker** is a tool to build, run and push docker images from source code repositories. +**jupyter-repo2docker** is a tool to build, run and push Docker images from source code repositories. + +See the [repo2docker documentation](http://repo2docker.readthedocs.io) +for more information. ## Pre-requisites @@ -55,49 +57,13 @@ After building (it might take a while!), it should output in your terminal somet If you copy paste that URL into your browser you will see a Jupyter Notebook with the contents of the repository you had just built! -### Displaying the image Dockerfile -Repo2Docker will generate a Dockerfile that composes the created Docker image. -To see the contents of this Dockerfile without building the image use `--debug` and `--no-build` -flags like so: - -```bash -jupyter-repo2docker --debug --no-build https://github.com/jakevdp/PythonDataScienceHandbook -``` +For more information on how to use ``repo2docker``, see the +[usage guide](http://repo2docker.readthedocs.io/en/latest/usage.html). ## Repository specifications -Repo2Docker looks for various files in the repository being built to figure out how to build it. +Repo2Docker looks for configuration files in the repository being built to figure out how to build it. It is philosophically similar to [Heroku Build Packs](https://devcenter.heroku.com/articles/buildpacks). -It currently looks for the following files. They are all composable - you can use any number of them -in the same repository (except for Dockerfiles, which take precedence over everything else). - -### `requirements.txt` - -This specifies a list of python packages that would be installed in a virtualenv (or conda environment). - -### `environment.yml` - -This is a conda environment specification, that lets you install packages with conda. Note that you must -leave the name of the environment empty for this to work out of the box. - -### `apt.txt` - -A list of debian packages that should be installed. The base image used is usually the latest released -version of Ubuntu (currently Zesty.) - -### `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 have the -executable bit set (`chmod +x postBuild`) to be considered. - -### `REQUIRE` - -This specifies a list of Julia packages! Currently only version 0.6 of Julia is supported, but more will -be as they are released. - -### `Dockerfile` - -This will be treated as a regular Dockerfile and a regular Docker build will be performed. The presence -of a Dockerfile will cause all other building behavior to not be triggered. +For a list of the configuration files that ``repo2docker`` can use, +see the [usage guide](http://repo2docker.readthedocs.io/en/latest/usage.html). diff --git a/docs/source/faq.md b/docs/source/faq.md index c97ad3ca..cc0ea916 100644 --- a/docs/source/faq.md +++ b/docs/source/faq.md @@ -4,6 +4,11 @@ A collection of frequently asked questions with answers! If you have a question & 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 an ``environment.yaml`` +file and setting the language to whichever version of Python you like. + ## Can I use repo2docker to bootstrap my own Dockerfile? No, you can't. diff --git a/docs/source/index.rst b/docs/source/index.rst index 93f0bb99..9be75157 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,6 +10,8 @@ Site Contents .. toctree:: :maxdepth: 2 + install + usage design faq samples diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 00000000..c4b58991 --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,22 @@ +.. _install: + +Installing ``repo2docker`` +========================== + +Installing ``repo2docker`` is easiest using the python +packaging index. In addition, you need to install +`Docker `_ as it is required in +order to build images. + +To install ``repo2docker`` from pypi, the python packaging index:: + + pip install jupyter-repo2docker + +To install from source and start contributing:: + + git clone https://github.com/jupyter/repo2docker.git + cd repo2docker + pip install -e . + +That's it! For information on using ``repo2docker``, see +:ref:`usage`. diff --git a/docs/source/samples.rst b/docs/source/samples.rst index 367ef044..ad86543a 100644 --- a/docs/source/samples.rst +++ b/docs/source/samples.rst @@ -1,5 +1,7 @@ -Sample build files -================== +.. _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. diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 00000000..708eccac --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,164 @@ +.. _usage: + +Using ``repo2docker`` +===================== + +The core feature of repo2docker is to fetch a repo (from github or locally), +build a container image based on the specifications found in the +repo & optionally launch a local Jupyter Notebook you can use to explore it. + +This section describes the general ways in which you can use +``repo2docker``. It covers basics in how to prepare your +repository for building, as well as how to use ``repo2docker`` +to build repositories on your own. + +See the `Frequently Asked Questions `_ for more info. + +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 `_. +``repo2docker`` will look for files in two places: + +* The root of the repository. +* A folder called ``binder`` in the root of the repository (if this folder + exists, configuration files in the root of the repository 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. + +``repodocker`` configuration files are all composable - you can use any number +of them in the same repository, with a few notable exceptions: + +* ``Dockerfile``: if a Dockerfile is present in a repository, it will take precedence + over all other configuration files (which will be ignored). +* ``environment.yaml`` with ``requirements.txt``: If both of these files are + present, then ``environment.yaml`` will be used to build the image, **not** + ``requirements.txt``. If you wish to ``pip install`` packages using an + ``environment.yaml`` file, `you should do so with the + *pip:* key `_. + + .. note:: + + For a list of sample repositories, see :ref:`samples`. + +Supported configuration files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Below is a list of supported configuration files. + +``requirements.txt`` +^^^^^^^^^^^^^^^^^^^^ + +This specifies a list of python packages that would be installed in a virtualenv (or conda environment). + +``environment.yml`` +^^^^^^^^^^^^^^^^^^^ + +This is a conda environment specification, that lets you install packages with conda. + +.. note:: + + You must leave the name of the environment empty for this to work out of the box. + +``apt.txt`` +^^^^^^^^^^^ + +A list of debian packages that should be installed. The base image used is usually the latest released +version of Ubuntu (currently Zesty.) + +``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`. + +.. note:: + + This file must be executable to be used with ``repo2docker``. To do this, + run the following:: + + chmod +x postBuild + +``REQUIRE`` +^^^^^^^^^^^ + +This specifies a list of Julia packages! Currently only version 0.6 of Julia is supported, but more will +be as they are released. + +.. note:: + + Using a ``REQUIRE`` file also requires that the repository contain an + ``environment.yaml`` file. + +``Dockerfile`` +^^^^^^^^^^^^^^ + +This will be treated as a regular Dockerfile and a regular Docker build will be performed. The presence +of a Dockerfile will cause all other building behavior to not be triggered. + +Using ``repo2docker`` with a JupyterHub +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible to use ``repo2docker`` in order to build JupyterHub-ready +Docker images. In order 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.yaml``:: + + jupyterhub==0.8.* + +Running ``repo2docker`` locally +------------------------------- + +For information on installing ``repo2docker``, see :ref:`install`. + +.. note:: + + Docker must be running on your machine in order to build images + with ``repo2docker``. + +Building an image +~~~~~~~~~~~~~~~~~ + +The simplest invocation of ``repo2docker`` builds a Docker image +from a git repo, then runs a Jupyter server within the image +so you can explore the repository's contents. +You can do this with the following command:: + + jupyter-repo2docker https://github.com/jakevdp/PythonDataScienceHandbook + +After building (it might take a while!), it should output in your terminal +something like:: + + 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 repository you have just built! + +Displaying the image Dockerfile +------------------------------- + +``repo2docker`` will generate a Dockerfile that composes the created Docker image. +To see the contents of this Dockerfile without building the image use +the ``--debug`` and ``--no-build`` flags like so:: + + jupyter-repo2docker --debug --no-build https://github.com/jakevdp/PythonDataScienceHandbook + +This will output the contents of the Dockerfile in your console. Note that it +will **not** build the image. + +Other build configurations +-------------------------- + +For a list of all the build configurations at your disposal, see the +CLI help:: + + jupyter-repo2docker -h