kopia lustrzana https://github.com/jupyterhub/repo2docker
Revamp our documentation
choldgraf
rodzic
5d3a946b24
commit
63026f55a5
|
|
@ -6,6 +6,7 @@ version: 2
|
|||
|
||||
sphinx:
|
||||
configuration: docs/source/conf.py
|
||||
builder: dirhtml
|
||||
|
||||
build:
|
||||
os: ubuntu-22.04
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
myst-parser>=0.18
|
||||
pydata-sphinx-theme>=0.11
|
||||
myst-parser<4
|
||||
pydata-sphinx-theme
|
||||
sphinx-autobuild
|
||||
sphinx-copybutton
|
||||
sphinxcontrib-autoprogram>=0.1.7
|
||||
|
|
|
|||
Plik binarny nie jest wyświetlany.
|
Po Szerokość: | Wysokość: | Rozmiar: 9.5 KiB |
Plik binarny nie jest wyświetlany.
|
Przed Szerokość: | Wysokość: | Rozmiar: 13 KiB Po Szerokość: | Wysokość: | Rozmiar: 9.9 KiB |
|
|
@ -0,0 +1,89 @@
|
|||
# Command-line usage and API
|
||||
|
||||
`repo2docker` is called with this command:
|
||||
|
||||
```
|
||||
jupyter-repo2docker <source-repository>
|
||||
```
|
||||
|
||||
where `<source-repository>` is a repository in one of [the supported repository providers](#repository-providers).
|
||||
|
||||
For example, the following command will build an image of Peter Norvig's
|
||||
[Pytudes] repository:
|
||||
|
||||
```
|
||||
jupyter-repo2docker https://github.com/norvig/pytudes
|
||||
```
|
||||
|
||||
Building the image may take a few minutes.
|
||||
|
||||
[Pytudes] uses a [requirements.txt file](https://github.com/norvig/pytudes/blob/HEAD/requirements.txt) to specify its Python environment. Because of this, `repo2docker` will use `pip` to install dependencies listed in this `requirement.txt` file, and these will be present in the generated Docker image. To learn more about configuration files in `repo2docker` visit [](#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
|
||||
```
|
||||
|
||||
Pasting the URL into your browser will open Jupyter Notebook with the
|
||||
dependencies and contents of the source repository in the built image.
|
||||
|
||||
## Debug repo2docker with `--debug` and `--no-build`
|
||||
|
||||
To debug the docker image being built, pass the `--debug` parameter:
|
||||
|
||||
> ```bash
|
||||
> jupyter-repo2docker --debug https://github.com/norvig/pytudes
|
||||
> ```
|
||||
|
||||
This will print the generated `Dockerfile`, build it, and run it.
|
||||
|
||||
To see the generated `Dockerfile` without actually building it,
|
||||
pass `--no-build` to the commandline. This `Dockerfile` output
|
||||
is for **debugging purposes** of `repo2docker` only - it can not
|
||||
be used by docker directly.
|
||||
|
||||
> ```bash
|
||||
> jupyter-repo2docker --no-build --debug https://github.com/norvig/pytudes
|
||||
> ```
|
||||
|
||||
## Build from a branch, commit or tag
|
||||
|
||||
To build a particular branch and commit, use the argument `--ref` and
|
||||
specify the `branch-name` or `commit-hash`. For example:
|
||||
|
||||
```
|
||||
jupyter-repo2docker --ref 9ced85dd9a84859d0767369e58f33912a214a3cf https://github.com/norvig/pytudes
|
||||
```
|
||||
|
||||
:::{tip}
|
||||
For reproducible builds, we recommend specifying a commit-hash to
|
||||
deterministically build a fixed version of a repository. Not specifying a
|
||||
commit-hash will result in the latest commit of the repository being built.
|
||||
:::
|
||||
|
||||
## Set environment variables during builds
|
||||
|
||||
When running repo2docker locally you can use the `-e` or `--env` command-line
|
||||
flag for each variable that you want to define.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
jupyter-repo2docker -e VAR1=val1 -e VAR2=val2 ...
|
||||
```
|
||||
|
||||
You can also configure environment variables for all users of a repository using the
|
||||
[](#start) configuration file.
|
||||
|
||||
(command-line-api)=
|
||||
|
||||
## Command-line API
|
||||
|
||||
```{autoprogram} repo2docker.__main__:argparser
|
||||
:prog: jupyter-repo2docker
|
||||
```
|
||||
|
||||
[pytudes]: https://github.com/norvig/pytudes
|
||||
|
|
@ -73,12 +73,20 @@ html_logo = "_static/images/logo.png"
|
|||
html_favicon = "_static/images/favicon.ico"
|
||||
html_static_path = ["_static"]
|
||||
html_css_files = ["custom.css"]
|
||||
html_sidebars = {
|
||||
"changelog": [],
|
||||
"start": [],
|
||||
}
|
||||
|
||||
# pydata_sphinx_theme reference: https://pydata-sphinx-theme.readthedocs.io/en/latest/
|
||||
html_theme = "pydata_sphinx_theme"
|
||||
html_theme_options = {
|
||||
"use_edit_page_button": True,
|
||||
"github_url": "https://github.com/jupyterhub/repo2docker",
|
||||
"logo": {
|
||||
"image_dark": "_static/images/logo-dark.png",
|
||||
"image_light": "_static/images/logo.png",
|
||||
},
|
||||
}
|
||||
html_context = {
|
||||
"github_user": "jupyterhub",
|
||||
|
|
|
|||
|
|
@ -1,245 +0,0 @@
|
|||
.. _config-files:
|
||||
|
||||
===================
|
||||
Configuration Files
|
||||
===================
|
||||
|
||||
``repo2docker`` looks for configuration files in the repository being built
|
||||
to determine how to build it. In general, ``repo2docker`` uses the same
|
||||
configuration files as other software installation tools,
|
||||
rather than creating new custom configuration files.
|
||||
|
||||
A number of ``repo2docker`` configuration files can be combined to compose more
|
||||
complex setups.
|
||||
|
||||
The `binder examples <https://github.com/binder-examples>`_ organization on
|
||||
GitHub contains a list of sample repositories for common configurations
|
||||
that ``repo2docker`` can build with various configuration files such as
|
||||
Python and R installation in a repository.
|
||||
|
||||
A list of supported configuration files (roughly in the order of build priority)
|
||||
can be found on this page (and to the right).
|
||||
|
||||
.. _environment.yml:
|
||||
|
||||
``environment.yml`` - Install a conda environment
|
||||
=================================================
|
||||
|
||||
``environment.yml`` is the standard configuration file used by `conda <https://conda.io>`_
|
||||
that lets you install any kind of package,
|
||||
including Python, R, and C/C++ packages.
|
||||
``repo2docker`` does not use your ``environment.yml`` to create and activate a new conda environment.
|
||||
Rather, it updates a base conda environment `defined here <https://github.com/jupyterhub/repo2docker/blob/HEAD/repo2docker/buildpacks/conda/environment.yml>`_ with the packages listed in your ``environment.yml``.
|
||||
This means that the environment will always have the same default name, not the name
|
||||
specified in your ``environment.yml``.
|
||||
|
||||
.. note::
|
||||
|
||||
You can install files from pip in your ``environment.yml`` as well.
|
||||
For example, see the `binder-examples environment.yml
|
||||
<https://github.com/binder-examples/python-conda_pip/blob/HEAD/environment.yml>`_
|
||||
file.
|
||||
|
||||
You can also specify which Python version to install in your built environment
|
||||
with ``environment.yml``. By default, ``repo2docker`` installs
|
||||
|default_python| with your ``environment.yml`` unless you include the version of
|
||||
Python in this file. ``conda`` Should support all versions of Python,
|
||||
though ``repo2docker`` support is best with Python 3.7-3.11.
|
||||
|
||||
.. warning::
|
||||
If you include a Python version in a ``runtime.txt`` file in addition to your
|
||||
``environment.yml``, your ``runtime.txt`` will be ignored.
|
||||
|
||||
.. _Pipfile:
|
||||
|
||||
``Pipfile`` and/or ``Pipfile.lock`` - Install a Python environment
|
||||
==================================================================
|
||||
|
||||
`pipenv <https://github.com/pypa/pipenv/>`_ allows you to manage a virtual
|
||||
environment Python dependencies. When using ``pipenv``, you end up with
|
||||
``Pipfile`` and ``Pipfile.lock`` files. The lock file contains explicit details
|
||||
about the packages that has been installed that met the criteria within the
|
||||
``Pipfile``.
|
||||
|
||||
If both ``Pipfile`` and ``Pipfile.lock`` are found by repo2docker, the former
|
||||
will be ignored in favor of the lock file. Also note that these files
|
||||
distinguish packages and development packages and that repo2docker will install
|
||||
both kinds.
|
||||
|
||||
.. _requirements.txt:
|
||||
|
||||
``requirements.txt`` - Install a Python environment
|
||||
===================================================
|
||||
|
||||
This specifies a list of Python packages that should be installed in your
|
||||
environment. Our
|
||||
`requirements.txt example <https://github.com/binder-examples/requirements/blob/HEAD/requirements.txt>`_
|
||||
on GitHub shows a typical requirements file.
|
||||
|
||||
|
||||
.. _setup.py:
|
||||
|
||||
``setup.py`` - Install Python packages
|
||||
======================================
|
||||
|
||||
To install your repository like a Python package, you may include a
|
||||
``setup.py`` file. repo2docker installs ``setup.py`` files by running
|
||||
``pip install -e .``.
|
||||
|
||||
.. _Project.toml:
|
||||
|
||||
``Project.toml`` - Install a Julia environment
|
||||
==============================================
|
||||
|
||||
A ``Project.toml`` (or ``JuliaProject.toml``) file can specify both the
|
||||
version of Julia to be used and a list of Julia packages to be installed.
|
||||
If a ``Manifest.toml`` is present, it will determine the exact versions
|
||||
of the Julia packages that are installed.
|
||||
|
||||
|
||||
.. _REQUIRE:
|
||||
|
||||
``REQUIRE`` - Install a Julia environment (legacy)
|
||||
==================================================
|
||||
|
||||
``REQUIRE`` files no longer work, and are no longer supported.
|
||||
The recommended way of installing a Julia environment is to use a ``Project.toml`` file.
|
||||
|
||||
|
||||
.. _install.R:
|
||||
|
||||
``install.R`` - Install an R/RStudio environment
|
||||
================================================
|
||||
|
||||
This is used to install R libraries pinned to a specific snapshot on
|
||||
`Posit Package Manager <https://packagemanager.posit.co/>`_.
|
||||
To set the date of the snapshot add a runtime.txt_.
|
||||
For an example ``install.R`` file, visit our `example install.R file <https://github.com/binder-examples/r/blob/HEAD/install.R>`_.
|
||||
|
||||
|
||||
.. _apt.txt:
|
||||
|
||||
``apt.txt`` - Install packages with apt-get
|
||||
===========================================
|
||||
|
||||
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/HEAD/apt.txt>`_.
|
||||
|
||||
|
||||
.. _DESCRIPTION:
|
||||
|
||||
``DESCRIPTION`` - Install an R package
|
||||
======================================
|
||||
|
||||
To install your repository like an R package, you may include a
|
||||
``DESCRIPTION`` file. repo2docker installs the package and dependencies
|
||||
from the ``DESCRIPTION`` by running ``devtools::install_local(getwd())``.
|
||||
|
||||
You can also have have a ``runtime.txt`` file that is formatted as
|
||||
``r-<YYYY>-<MM>-<DD>``, where YYYY-MM-DD is a snapshot of CRAN that will be used
|
||||
for your R installation. If ``runtime.txt`` isn't provided in this case, a
|
||||
recent date will be used.
|
||||
|
||||
|
||||
.. _postBuild:
|
||||
|
||||
``postBuild`` - Run code after installing the environment
|
||||
=========================================================
|
||||
|
||||
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 that by default the build will not be stopped if an error occurs inside a shell script.
|
||||
You should include ``set -e`` or the equivalent at the start of the script to avoid errors being silently ignored.
|
||||
|
||||
An example use-case 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/HEAD/.binder/postBuild>`_.
|
||||
|
||||
|
||||
.. _start:
|
||||
|
||||
``start`` - Run code before the user sessions starts
|
||||
====================================================
|
||||
|
||||
A script that can contain simple commands to be run at runtime (as an
|
||||
`ENTRYPOINT <https://docs.docker.com/engine/reference/builder/#entrypoint>`_
|
||||
to the docker container). If you want this to be a shell script, make sure the
|
||||
first line is ``#!/bin/bash``. The last line must be ``exec "$@"``
|
||||
or equivalent.
|
||||
|
||||
Use this to set environment variables that software installed in your container
|
||||
expects to be set. This script is executed each time your binder is started and
|
||||
should at most take a few seconds to run.
|
||||
|
||||
If you only need to run things once during the build phase use :ref:`postBuild`.
|
||||
|
||||
|
||||
.. TODO: Discuss runtime limits, best practices, etc.
|
||||
|
||||
.. _runtime.txt:
|
||||
|
||||
``runtime.txt`` - Specifying runtimes
|
||||
=====================================
|
||||
|
||||
Sometimes you want to specify the version of the runtime
|
||||
(e.g. the version of Python or R),
|
||||
but the environment specification format will not let you specify this information
|
||||
(e.g. requirements.txt or install.R).
|
||||
For these cases, we have a special file, ``runtime.txt``.
|
||||
|
||||
.. note::
|
||||
|
||||
``runtime.txt`` is only supported when used with environment specifications
|
||||
that do not already support specifying the runtime
|
||||
(when using ``environment.yml`` for conda or ``Project.toml`` for Julia,
|
||||
``runtime.txt`` will be ignored).
|
||||
|
||||
Have ``python-x.y`` in ``runtime.txt`` to run the repository with Python version x.y.
|
||||
See our `Python2 example repository <https://github.com/binder-examples/python2_runtime/blob/HEAD/runtime.txt>`_.
|
||||
|
||||
Have ``r-<RVERSION>-<YYYY>-<MM>-<DD>`` in ``runtime.txt`` to run the repository with R version RVERSION and libraries from a YYYY-MM-DD snapshot of `Posit Package Manager <https://packagemanager.posit.co/client/#/repos/2/overview>`__.
|
||||
RVERSION can be set to 3.4, 3.5, 3.6, or to patch releases for the 3.5 and 3.6 series.
|
||||
If you do not specify a version, the latest release will be used (currently R 3.6).
|
||||
See our `R example repository <https://github.com/binder-examples/r/blob/HEAD/runtime.txt>`_.
|
||||
|
||||
.. _default.nix:
|
||||
|
||||
``default.nix`` - the nix package manager
|
||||
=========================================
|
||||
|
||||
Specify packages to be installed by the `nix package manager <https://github.com/NixOS/nixpkgs>`_.
|
||||
When you use this config file all other configuration files (like ``requirements.txt``)
|
||||
that specify packages are ignored. When using ``nix`` you have to specify all
|
||||
packages and dependencies explicitly, including the Jupyter notebook package that
|
||||
repo2docker expects to be installed. If you do not install Jupyter explicitly
|
||||
repo2docker will no be able to start your container.
|
||||
|
||||
`nix-shell <https://nixos.org/nix/manual/#sec-nix-shell>`_ is used to evaluate
|
||||
a ``nix`` expression written in a ``default.nix`` file. Make sure to
|
||||
`pin your nixpkgs <https://discourse.nixos.org/t/nixops-pinning-nixpkgs/734>`_
|
||||
to produce a reproducible environment.
|
||||
|
||||
To see an example repository visit
|
||||
`nix binder example <https://github.com/binder-examples/nix>`_.
|
||||
|
||||
|
||||
.. _dockerfile:
|
||||
|
||||
``Dockerfile`` - Advanced environments
|
||||
======================================
|
||||
|
||||
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.
|
||||
|
||||
With Dockerfiles, a regular Docker build will be performed.
|
||||
|
||||
.. note::
|
||||
If a Dockerfile is present, all other configuration files will be ignored.
|
||||
|
||||
See the `Advanced Binder Documentation <https://mybinder.readthedocs.io/en/latest/tutorials/dockerfile.html>`_ for
|
||||
best-practices with Dockerfiles.
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
# Configuration files for post-build actions
|
||||
|
||||
(postbuild)=
|
||||
|
||||
## `postBuild` - Run code after installing the environment
|
||||
|
||||
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 that by default the build will not be stopped if an error occurs inside a shell script.
|
||||
You should include `set -e` or the equivalent at the start of the script to avoid errors being silently ignored.
|
||||
|
||||
An example use-case 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/HEAD/.binder/postBuild).
|
||||
|
||||
(start)=
|
||||
|
||||
## `start` - Run code before the user sessions starts
|
||||
|
||||
A script that can contain simple commands to be run at runtime (as an
|
||||
[ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint)
|
||||
to the docker container). If you want this to be a shell script, make sure the
|
||||
first line is `#!/bin/bash`. The last line must be `exec "$@"`
|
||||
or equivalent.
|
||||
|
||||
Use this to set environment variables that software installed in your container
|
||||
expects to be set. This script is executed each time your binder is started and
|
||||
should at most take a few seconds to run.
|
||||
|
||||
If you only need to run things once during the build phase use {ref}`postBuild`.
|
||||
|
||||
% TODO: Discuss runtime limits, best practices, etc.
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
# Configuration for datascience workflows
|
||||
|
||||
|
||||
(environment-yml)=
|
||||
|
||||
## `environment.yml` - Install a conda environment
|
||||
|
||||
`environment.yml` is the standard configuration file used by [conda](https://conda.io)
|
||||
that lets you install any kind of package,
|
||||
including Python, R, and C/C++ packages.
|
||||
`repo2docker` does not use your `environment.yml` to create and activate a new conda environment.
|
||||
Rather, it updates a base conda environment [defined here](https://github.com/jupyterhub/repo2docker/blob/HEAD/repo2docker/buildpacks/conda/environment.yml) with the packages listed in your `environment.yml`.
|
||||
This means that the environment will always have the same default name, not the name
|
||||
specified in your `environment.yml`.
|
||||
|
||||
:::{note}
|
||||
You can install files from pip in your `environment.yml` as well.
|
||||
For example, see the [binder-examples environment.yml](https://github.com/binder-examples/python-conda_pip/blob/HEAD/environment.yml)
|
||||
file.
|
||||
:::
|
||||
|
||||
You can also specify which Python version to install in your built environment
|
||||
with `environment.yml`. By default, `repo2docker` installs
|
||||
{{ default_python }} with your `environment.yml` unless you include the version of
|
||||
Python in this file. `conda` Should support all versions of Python,
|
||||
though `repo2docker` support is best with Python 3.7-3.11.
|
||||
|
||||
:::{warning}
|
||||
If you include a Python version in a `runtime.txt` file in addition to your
|
||||
`environment.yml`, your `runtime.txt` will be ignored.
|
||||
:::
|
||||
|
||||
|
||||
(require)=
|
||||
|
||||
## `REQUIRE` - Install a Julia environment (legacy)
|
||||
|
||||
`REQUIRE` files no longer work, and are no longer supported.
|
||||
The recommended way of installing a Julia environment is to use a `Project.toml` file.
|
||||
|
||||
(install-r)=
|
||||
|
||||
## `install.R` - Install an R/RStudio environment
|
||||
|
||||
This is used to install R libraries pinned to a specific snapshot on
|
||||
[Posit Package Manager](https://packagemanager.posit.co/).
|
||||
To set the date of the snapshot add a [runtime.txt].
|
||||
For an example `install.R` file, visit our [example install.R file](https://github.com/binder-examples/r/blob/HEAD/install.R).
|
||||
|
||||
|
||||
|
||||
(description)=
|
||||
|
||||
## `DESCRIPTION` - Install an R package
|
||||
|
||||
To install your repository like an R package, you may include a
|
||||
`DESCRIPTION` file. repo2docker installs the package and dependencies
|
||||
from the `DESCRIPTION` by running `devtools::install_local(getwd())`.
|
||||
|
||||
You can also have have a `runtime.txt` file that is formatted as
|
||||
`r-<YYYY>-<MM>-<DD>`, where YYYY-MM-DD is a snapshot of CRAN that will be used
|
||||
for your R installation. If `runtime.txt` isn't provided in this case, a
|
||||
recent date will be used.
|
||||
|
|
@ -0,0 +1,42 @@
|
|||
# Configuration files for software development workflows
|
||||
|
||||
(pipfile)=
|
||||
|
||||
## `Pipfile` and/or `Pipfile.lock` - Install a Python environment
|
||||
|
||||
[pipenv](https://github.com/pypa/pipenv/) allows you to manage a virtual
|
||||
environment Python dependencies. When using `pipenv`, you end up with
|
||||
`Pipfile` and `Pipfile.lock` files. The lock file contains explicit details
|
||||
about the packages that has been installed that met the criteria within the
|
||||
`Pipfile`.
|
||||
|
||||
If both `Pipfile` and `Pipfile.lock` are found by repo2docker, the former
|
||||
will be ignored in favor of the lock file. Also note that these files
|
||||
distinguish packages and development packages and that repo2docker will install
|
||||
both kinds.
|
||||
|
||||
(requirements-txt)=
|
||||
|
||||
## `requirements.txt` - Install a Python environment
|
||||
|
||||
This specifies a list of Python packages that should be installed in your
|
||||
environment. Our
|
||||
[requirements.txt example](https://github.com/binder-examples/requirements/blob/HEAD/requirements.txt)
|
||||
on GitHub shows a typical requirements file.
|
||||
|
||||
(setup-py)=
|
||||
|
||||
## `setup.py` - Install Python packages
|
||||
|
||||
To install your repository like a Python package, you may include a
|
||||
`setup.py` file. repo2docker installs `setup.py` files by running
|
||||
`pip install -e .`.
|
||||
|
||||
(project-toml)=
|
||||
|
||||
## `Project.toml` - Install a Julia environment
|
||||
|
||||
A `Project.toml` (or `JuliaProject.toml`) file can specify both the
|
||||
version of Julia to be used and a list of Julia packages to be installed.
|
||||
If a `Manifest.toml` is present, it will determine the exact versions
|
||||
of the Julia packages that are installed.
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
(config-files)=
|
||||
|
||||
# Configuration files supported by repo2docker
|
||||
|
||||
`repo2docker` looks for configuration files in the repository being built
|
||||
to determine how to build it. In general, `repo2docker` uses the same
|
||||
configuration files as other software installation tools,
|
||||
rather than creating new custom configuration files.
|
||||
|
||||
A number of `repo2docker` configuration files can be combined to compose more
|
||||
complex setups.
|
||||
|
||||
:::{seealso}
|
||||
The [binder examples](https://github.com/binder-examples) organization on
|
||||
GitHub contains a list of sample repositories for common configurations
|
||||
that `repo2docker` can build with various configuration files such as
|
||||
Python and R installation in a repository.
|
||||
:::
|
||||
|
||||
A list of supported configuration files (roughly in the order of build priority)
|
||||
can be found on this page (and to the right).
|
||||
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 2
|
||||
./datascience
|
||||
./development
|
||||
./system
|
||||
./actions
|
||||
```
|
||||
|
|
@ -1,15 +0,0 @@
|
|||
===========================
|
||||
Configuring your repository
|
||||
===========================
|
||||
|
||||
Information about configuring your repository to work with repo2docker,
|
||||
and controlling elements of the built environment using configuration files.
|
||||
|
||||
For information on where to put your configuration files see :ref:`usage-config-file-location`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Complete list of configuration files
|
||||
|
||||
../config_files
|
||||
../specification
|
||||
|
|
@ -0,0 +1,75 @@
|
|||
# System-wide configuration
|
||||
|
||||
|
||||
(apt-txt)=
|
||||
|
||||
## `apt.txt` - Install packages with apt-get
|
||||
|
||||
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/HEAD/apt.txt).
|
||||
|
||||
|
||||
|
||||
(runtime-txt)=
|
||||
|
||||
## `runtime.txt` - Specifying runtimes
|
||||
|
||||
Sometimes you want to specify the version of the runtime
|
||||
(e.g. the version of Python or R),
|
||||
but the environment specification format will not let you specify this information
|
||||
(e.g. requirements.txt or install.R).
|
||||
For these cases, we have a special file, `runtime.txt`.
|
||||
|
||||
:::{note}
|
||||
`runtime.txt` is only supported when used with environment specifications
|
||||
that do not already support specifying the runtime
|
||||
(when using `environment.yml` for conda or `Project.toml` for Julia,
|
||||
`runtime.txt` will be ignored).
|
||||
:::
|
||||
|
||||
Have `python-x.y` in `runtime.txt` to run the repository with Python version x.y.
|
||||
See our [Python2 example repository](https://github.com/binder-examples/python2_runtime/blob/HEAD/runtime.txt).
|
||||
|
||||
Have `r-<RVERSION>-<YYYY>-<MM>-<DD>` in `runtime.txt` to run the repository with R version RVERSION and libraries from a YYYY-MM-DD snapshot of [Posit Package Manager](https://packagemanager.posit.co/client/#/repos/2/overview).
|
||||
RVERSION can be set to 3.4, 3.5, 3.6, or to patch releases for the 3.5 and 3.6 series.
|
||||
If you do not specify a version, the latest release will be used (currently R 3.6).
|
||||
See our [R example repository](https://github.com/binder-examples/r/blob/HEAD/runtime.txt).
|
||||
|
||||
(default-nix)=
|
||||
|
||||
## `default.nix` - the nix package manager
|
||||
|
||||
Specify packages to be installed by the [nix package manager](https://github.com/NixOS/nixpkgs).
|
||||
When you use this config file all other configuration files (like `requirements.txt`)
|
||||
that specify packages are ignored. When using `nix` you have to specify all
|
||||
packages and dependencies explicitly, including the Jupyter notebook package that
|
||||
repo2docker expects to be installed. If you do not install Jupyter explicitly
|
||||
repo2docker will no be able to start your container.
|
||||
|
||||
[nix-shell](https://nixos.org/nix/manual/#sec-nix-shell) is used to evaluate
|
||||
a `nix` expression written in a `default.nix` file. Make sure to
|
||||
[pin your nixpkgs](https://discourse.nixos.org/t/nixops-pinning-nixpkgs/734)
|
||||
to produce a reproducible environment.
|
||||
|
||||
To see an example repository visit
|
||||
[nix binder example](https://github.com/binder-examples/nix).
|
||||
|
||||
(dockerfile)=
|
||||
|
||||
## `Dockerfile` - Advanced environments
|
||||
|
||||
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.
|
||||
|
||||
With Dockerfiles, a regular Docker build will be performed.
|
||||
|
||||
:::{note}
|
||||
If a Dockerfile is present, all other configuration files will be ignored.
|
||||
:::
|
||||
|
||||
See the [Advanced Binder Documentation](https://mybinder.readthedocs.io/en/latest/tutorials/dockerfile.html) for
|
||||
best-practices with Dockerfiles.
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
============
|
||||
Contributing
|
||||
============
|
||||
=================
|
||||
Contributor guide
|
||||
=================
|
||||
|
||||
The repo2docker community is welcoming of all kinds of help and
|
||||
participation from others. Below are a few ways that you can get involved,
|
||||
|
|
@ -8,11 +8,16 @@ as well as resources for understanding the structure and design of the
|
|||
repo2docker package.
|
||||
|
||||
.. toctree::
|
||||
:caption: Contributing to repo2docker
|
||||
|
||||
contributing
|
||||
roadmap
|
||||
tasks
|
||||
|
||||
.. toctree::
|
||||
:caption: Developer guide
|
||||
|
||||
../architecture
|
||||
../design
|
||||
tasks
|
||||
buildpack
|
||||
contentprovider
|
||||
|
|
@ -0,0 +1,111 @@
|
|||
(faq)=
|
||||
|
||||
# Frequently Asked Questions (FAQ)
|
||||
|
||||
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!
|
||||
|
||||
## Why is my repository failing to build with `ResolvePackageNotFound` ?
|
||||
|
||||
If you used `conda env export` to generate your `environment.yml` it will
|
||||
generate a list of packages and versions of packages that is pinned to platform
|
||||
specific versions. These very specific versions are not available in the linux
|
||||
docker image used by `repo2docker`. A typical error message will look like
|
||||
the following:
|
||||
|
||||
```
|
||||
Step 39/44 : RUN conda env update -n root -f "environment.yml" && conda clean -tipsy && conda list -n root
|
||||
---> Running in ebe9a67762e4
|
||||
Solving environment: ...working... failed
|
||||
|
||||
ResolvePackageNotFound:
|
||||
- jsonschema==2.6.0=py36hb385e00_0
|
||||
- libedit==3.1.20181209=hb402a30_0
|
||||
- tornado==5.1.1=py36h1de35cc_0
|
||||
...
|
||||
```
|
||||
|
||||
We recommend to use `conda env export --no-builds -f environment.yml` to export
|
||||
your environment and then edit the file by hand to remove platform specific
|
||||
packages like `appnope`.
|
||||
|
||||
See {ref}`export-environment` for a recipe on how to create strict exports of
|
||||
your environment that will work with `repo2docker`.
|
||||
|
||||
## Can I add executable files to the user's PATH?
|
||||
|
||||
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.)
|
||||
|
||||
## Can I use repo2docker to bootstrap my own Dockerfile?
|
||||
|
||||
No, you can't.
|
||||
|
||||
If you pass the `--debug` flag to `repo2docker`, it outputs the
|
||||
intermediate Dockerfile that is used to build the docker image. While
|
||||
it is tempting to copy this as a base for your own Dockerfile, that is
|
||||
not supported & in most cases will not work. The `--debug` output is
|
||||
just our intermediate generated Dockerfile, and is meant to be built
|
||||
in a very specific way. 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 repositories you can copy & modify for your own use!
|
||||
|
||||
## Can I use repo2docker to edit a local host repository within a Docker environment?
|
||||
|
||||
Yes: use the `--editable` or `-E` flag (don't confuse this with
|
||||
the `-e` flag for environment variables), and run repo2docker on a
|
||||
local repository:
|
||||
|
||||
```
|
||||
repo2docker -E my-repository/
|
||||
```
|
||||
|
||||
This builds a Docker container from the files in that repository
|
||||
(using, for example, a `requirements.txt` or `install.R` file),
|
||||
then runs that container, while connecting the working directory
|
||||
inside the container to the local repository outside the
|
||||
container. For example, in case there is a notebook file (`.ipynb`),
|
||||
this will open in a local web browser, and one can edit it and save
|
||||
it. The resulting notebook is updated in both the Docker container and
|
||||
the local repository. Once the container is exited, the changed file
|
||||
will still be in the local repository.
|
||||
|
||||
This allows for easy testing of the container while debugging some
|
||||
items, as well as using a fully customizable container to edit
|
||||
notebooks (among others).
|
||||
|
||||
:::{note}
|
||||
Editable mode is a convenience option that will bind the
|
||||
repository to the container working directory (usually
|
||||
`$HOME`). If you need to mount to a different location in
|
||||
the container, use the `--volumes` option instead. Similarly,
|
||||
for a fully customized user Dockerfile, this option is not
|
||||
guaranteed to work.
|
||||
:::
|
||||
|
||||
## Why is my R shiny app not launching?
|
||||
|
||||
If you are trying to run an R shiny app using the `/shiny/folder_containing_shiny`
|
||||
url option, but the launch returns "The application exited during initialization.",
|
||||
there might be something wrong with the specification of the app. One way of debugging
|
||||
the app in the container is by running the `rstudio` url, open either the ui or
|
||||
server file for the app, and run the app in the container rstudio. This way you can
|
||||
see the rstudio logs as it tries to initialise the shiny app. If you a missing a
|
||||
package or other dependency for the container, this will be obvious at this stage.
|
||||
|
||||
## Why does repo2docker need to exist? Why not use tool like source2image?
|
||||
|
||||
The Jupyter community believes strongly in building on top of pre-existing tools whenever
|
||||
possible (this is why repo2docker buildpacks largely build off of patterns that already
|
||||
exist in the data analytics community). We try to perform due-diligence and search for
|
||||
other communities to leverage and help, but sometimes it makes the most sense to build
|
||||
our own new tool. In the case of repo2docker, we spent time integrating with a pre-existing
|
||||
tool called [source2image](https://github.com/openshift/source-to-image/).
|
||||
This is an excellent open tool for containerization, but we
|
||||
ultimately decided that it did not fit the use-case we wanted to address. For more information,
|
||||
[here](https://github.com/yuvipanda/words/blob/fd096dd49d87e624acd8bdf6d13c0cecb930bb3f/content/post/why-not-s2i.md) is a short blog post about the decision and the reasoning behind it.
|
||||
|
|
@ -1,192 +0,0 @@
|
|||
.. _faq:
|
||||
|
||||
Frequently Asked Questions (FAQ)
|
||||
================================
|
||||
|
||||
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?
|
||||
-----------------------------------------------
|
||||
|
||||
One can specify a Python version in the ``environment.yml`` file of a repository
|
||||
or ``runtime.txt`` file if using ``requirements.txt`` instead of ``environment.yml``.
|
||||
|
||||
What versions of Python (or R or Julia...) are supported?
|
||||
---------------------------------------------------------
|
||||
|
||||
Python
|
||||
~~~~~~
|
||||
|
||||
Repo2docker officially supports the following versions of Python
|
||||
(specified in your :ref:`environment.yml <environment.yml>` or
|
||||
:ref:`runtime.txt <runtime.txt>` file):
|
||||
|
||||
- 3.11 (added in 2023)
|
||||
- 3.10 (added in 2022, default in 2023)
|
||||
- 3.9 (added in 2021)
|
||||
- 3.8 (added in 0.11)
|
||||
- 3.7 (added in 0.7, default in 0.8)
|
||||
- 3.6 (default in 0.7 and earlier)
|
||||
- 3.5
|
||||
- 2.7
|
||||
|
||||
Additional versions may work, as long as the
|
||||
`base environment <https://github.com/jupyterhub/repo2docker/blob/HEAD/repo2docker/buildpacks/conda/environment.yml>`_
|
||||
can be installed for your version of Python.
|
||||
The most likely source of incompatibility is if one of the packages
|
||||
in the base environment is not packaged for your Python,
|
||||
either because the version of the package is too new and your chosen Python is too old,
|
||||
or vice versa.
|
||||
|
||||
If an old version of Python is specified (3.6 or earlier in 2023), a separate environment for the kernel will be installed with your requested Python version.
|
||||
The notebook server will run in the default |default_python| environment.
|
||||
That is, your _notebooks_ will run with Python 3.6, while your notebook _server_ will run with |default_python|.
|
||||
|
||||
These two environments can be distinguished with ``$NB_PYTHON_PREFIX/bin/python`` for the server and ``$KERNEL_PYTHON_PREFIX/bin/python`` for the kernel.
|
||||
Both of these environment variables area always defined, even when they are the same.
|
||||
|
||||
Starting in 2023, the default version of Python used when Python version is unspecified will be updated more often.
|
||||
Python itself releases a new version every year now, and repo2docker will follow, with the default Python version generally trailing the latest stable version of Python itself by 1-2 versions.
|
||||
|
||||
If you choose not to specify a Python version, your repository is _guaranteed_ to stop working, eventually.
|
||||
We **strongly** recommend specifying a Python version (in environment.yml, runtime.txt, Pipfile, etc.)
|
||||
|
||||
Julia
|
||||
~~~~~
|
||||
|
||||
All Julia versions since Julia 1.3 are supported via a :ref:`Project.toml <Project.toml>`
|
||||
file, and this is the recommended way to install Julia environments.
|
||||
|
||||
Julia < 1.3 and the older Julia REQUIRE file is no longer supported because required infrastructure has been removed.
|
||||
|
||||
R
|
||||
~
|
||||
|
||||
The default version of R is currently R 4.2. You can select the version of
|
||||
R you want to use by specifying it in the :ref:`runtime.txt <runtime.txt>`
|
||||
file.
|
||||
|
||||
We support R versions 3.4, 3.5, 3.6, 4.0, 4.1 and 4.2.
|
||||
|
||||
|
||||
Why is my repository failing to build with ``ResolvePackageNotFound`` ?
|
||||
--------------------------------------------------------------------------
|
||||
|
||||
If you used ``conda env export`` to generate your ``environment.yml`` it will
|
||||
generate a list of packages and versions of packages that is pinned to platform
|
||||
specific versions. These very specific versions are not available in the linux
|
||||
docker image used by ``repo2docker``. A typical error message will look like
|
||||
the following::
|
||||
|
||||
Step 39/44 : RUN conda env update -n root -f "environment.yml" && conda clean -tipsy && conda list -n root
|
||||
---> Running in ebe9a67762e4
|
||||
Solving environment: ...working... failed
|
||||
|
||||
ResolvePackageNotFound:
|
||||
- jsonschema==2.6.0=py36hb385e00_0
|
||||
- libedit==3.1.20181209=hb402a30_0
|
||||
- tornado==5.1.1=py36h1de35cc_0
|
||||
...
|
||||
|
||||
We recommend to use ``conda env export --no-builds -f environment.yml`` to export
|
||||
your environment and then edit the file by hand to remove platform specific
|
||||
packages like ``appnope``.
|
||||
|
||||
See :ref:`export-environment` for a recipe on how to create strict exports of
|
||||
your environment that will work with ``repo2docker``.
|
||||
|
||||
|
||||
Can I add executable files to the user's PATH?
|
||||
----------------------------------------------
|
||||
|
||||
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.)
|
||||
|
||||
How do I set environment variables?
|
||||
-----------------------------------
|
||||
|
||||
To configure environment variables for all users of a repository use the
|
||||
:ref:`start <start>` configuration file.
|
||||
|
||||
When running repo2docker locally you can use the ``-e`` or ``--env`` command-line
|
||||
flag for each variable that you want to define.
|
||||
|
||||
For example ``jupyter-repo2docker -e VAR1=val1 -e VAR2=val2 ...``
|
||||
|
||||
Can I use repo2docker to bootstrap my own Dockerfile?
|
||||
-----------------------------------------------------
|
||||
|
||||
No, you can't.
|
||||
|
||||
If you pass the ``--debug`` flag to ``repo2docker``, it outputs the
|
||||
intermediate Dockerfile that is used to build the docker image. While
|
||||
it is tempting to copy this as a base for your own Dockerfile, that is
|
||||
not supported & in most cases will not work. The ``--debug`` output is
|
||||
just our intermediate generated Dockerfile, and is meant to be built
|
||||
in a very specific way. 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 repositories you can copy & modify for your own use!
|
||||
|
||||
Can I use repo2docker to edit a local host repository within a Docker environment?
|
||||
----------------------------------------------------------------------------------
|
||||
|
||||
Yes: use the ``--editable`` or ``-E`` flag (don't confuse this with
|
||||
the ``-e`` flag for environment variables), and run repo2docker on a
|
||||
local repository::
|
||||
|
||||
repo2docker -E my-repository/
|
||||
|
||||
This builds a Docker container from the files in that repository
|
||||
(using, for example, a ``requirements.txt`` or ``install.R`` file),
|
||||
then runs that container, while connecting the working directory
|
||||
inside the container to the local repository outside the
|
||||
container. For example, in case there is a notebook file (``.ipynb``),
|
||||
this will open in a local web browser, and one can edit it and save
|
||||
it. The resulting notebook is updated in both the Docker container and
|
||||
the local repository. Once the container is exited, the changed file
|
||||
will still be in the local repository.
|
||||
|
||||
This allows for easy testing of the container while debugging some
|
||||
items, as well as using a fully customizable container to edit
|
||||
notebooks (among others).
|
||||
|
||||
.. note::
|
||||
|
||||
Editable mode is a convenience option that will bind the
|
||||
repository to the container working directory (usually
|
||||
``$HOME``). If you need to mount to a different location in
|
||||
the container, use the ``--volumes`` option instead. Similarly,
|
||||
for a fully customized user Dockerfile, this option is not
|
||||
guaranteed to work.
|
||||
|
||||
|
||||
Why is my R shiny app not launching?
|
||||
----------------------------------------------------------------------------------
|
||||
|
||||
If you are trying to run an R shiny app using the ``/shiny/folder_containing_shiny``
|
||||
url option, but the launch returns "The application exited during initialization.",
|
||||
there might be something wrong with the specification of the app. One way of debugging
|
||||
the app in the container is by running the ``rstudio`` url, open either the ui or
|
||||
server file for the app, and run the app in the container rstudio. This way you can
|
||||
see the rstudio logs as it tries to initialise the shiny app. If you a missing a
|
||||
package or other dependency for the container, this will be obvious at this stage.
|
||||
|
||||
|
||||
Why does repo2docker need to exist? Why not use tool like source2image?
|
||||
-----------------------------------------------------------------------
|
||||
|
||||
The Jupyter community believes strongly in building on top of pre-existing tools whenever
|
||||
possible (this is why repo2docker buildpacks largely build off of patterns that already
|
||||
exist in the data analytics community). We try to perform due-diligence and search for
|
||||
other communities to leverage and help, but sometimes it makes the most sense to build
|
||||
our own new tool. In the case of repo2docker, we spent time integrating with a pre-existing
|
||||
tool called `source2image <https://github.com/openshift/source-to-image/>`_.
|
||||
This is an excellent open tool for containerization, but we
|
||||
ultimately decided that it did not fit the use-case we wanted to address. For more information,
|
||||
`here <https://github.com/yuvipanda/words/blob/fd096dd49d87e624acd8bdf6d13c0cecb930bb3f/content/post/why-not-s2i.md>`_ is a short blog post about the decision and the reasoning behind it.
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
===============
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
Instructions and information on how to get started with repo2docker
|
||||
on your own machine. Select from the pages listed below to begin.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
../install
|
||||
../usage
|
||||
../faq
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
.. _export-environment:
|
||||
|
||||
=============================================================================
|
||||
How to automatically create a ``environment.yml`` that works with repo2docker
|
||||
=============================================================================
|
||||
============================================================================
|
||||
Export your environment to a ``environment.yml`` that works with repo2docker
|
||||
============================================================================
|
||||
|
||||
This how-to explains how to create a ``environment.yml`` that specifies all
|
||||
installed packages and their precise versions from your environment.
|
||||
|
|
|
|||
|
|
@ -1,19 +0,0 @@
|
|||
=============
|
||||
How-to Guides
|
||||
=============
|
||||
|
||||
Short, actionable guides that cover specific topics with repo2docker.
|
||||
Select from the pages listed below to get started.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: How-To guides
|
||||
|
||||
user_interface
|
||||
languages
|
||||
export_environment
|
||||
lab_workspaces
|
||||
breaking_changes
|
||||
jupyterhub_images
|
||||
deploy
|
||||
base_image
|
||||
|
|
@ -0,0 +1,138 @@
|
|||
(languages)=
|
||||
|
||||
# Choose languages for your environment
|
||||
|
||||
You can define many different languages in your configuration files. This
|
||||
page describes how to use some of the more common ones.
|
||||
|
||||
## Python
|
||||
|
||||
Your environment will have Python (and specified dependencies) installed when
|
||||
you use one of the following configuration files:
|
||||
|
||||
- `requirements.txt`
|
||||
- `environment.yml`
|
||||
|
||||
By default, the environment will have {{ default_python }}.
|
||||
|
||||
### Specify a version of Python
|
||||
|
||||
To specify a specific version of Python, you have two options:
|
||||
|
||||
- Use [environment.yml](#environment-yml). Conda environments let you define
|
||||
the Python version in `environment.yml`.
|
||||
To do so, add `python=X.X` to your dependencies section, like so:
|
||||
|
||||
```
|
||||
name: python 2.7
|
||||
dependencies:
|
||||
- python=2.7
|
||||
- numpy
|
||||
```
|
||||
|
||||
- Use [runtime.txt](#runtime-txt) with [requirements.txt](#requirements-txt).
|
||||
If you are using `requirements.txt` instead of `environment.yml`,
|
||||
you can specify the Python runtime version in a separate file called `runtime.txt`.
|
||||
This file contains a single line of the following form:
|
||||
|
||||
```
|
||||
python-X.X
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
python-3.6
|
||||
```
|
||||
|
||||
### Supported versions of Python
|
||||
|
||||
Repo2docker officially supports the following versions of Python:
|
||||
|
||||
- 3.11 (added in 2023)
|
||||
- 3.10 (added in 2022, default in 2023)
|
||||
- 3.9 (added in 2021)
|
||||
- 3.8 (added in 0.11)
|
||||
- 3.7 (added in 0.7, default in 0.8)
|
||||
- 3.6 (default in 0.7 and earlier)
|
||||
- 3.5
|
||||
- 2.7
|
||||
|
||||
Additional versions may work, as long as the [base environment](https://github.com/jupyterhub/repo2docker/blob/HEAD/repo2docker/buildpacks/conda/environment.yml) can be installed for your version of Python.
|
||||
The most likely source of incompatibility is if one of the packages in the base environment is not packaged for your Python, either because the version of the package is too new and your chosen Python is too old, or vice versa.
|
||||
|
||||
If an old version of Python is specified (3.6 or earlier in 2023), a separate environment for the kernel will be installed with your requested Python version.
|
||||
The notebook server will run in the default {{ default_python }} environment.
|
||||
That is, your _notebooks_ will run with Python 3.6, while your notebook _server_ will run with {{ default_python }}.
|
||||
|
||||
These two environments can be distinguished with `$NB_PYTHON_PREFIX/bin/python` for the server and `$KERNEL_PYTHON_PREFIX/bin/python` for the kernel.
|
||||
Both of these environment variables area always defined, even when they are the same.
|
||||
|
||||
Starting in 2023, the default version of Python used when Python version is unspecified will be updated more often.
|
||||
Python itself releases a new version every year now, and repo2docker will follow, with the default Python version generally trailing the latest stable version of Python itself by 1-2 versions.
|
||||
|
||||
If you choose not to specify a Python version, your repository is _guaranteed_ to stop working, eventually.
|
||||
We **strongly** recommend specifying a Python version (in environment.yml, runtime.txt, Pipfile, etc.)
|
||||
|
||||
|
||||
## The R Language
|
||||
|
||||
repo2docker supports R, the open source [RStudio IDE](https://www.rstudio.com/) as well
|
||||
as Jupyter support for R with the [IRKernel](https://irkernel.github.io/). To set it up,
|
||||
you need to create a `runtime.txt` file with the following format:
|
||||
|
||||
> r-\<version>-\<YYYY>-\<MM>-\<DD>
|
||||
|
||||
This will provide you R of given version (such as 4.1, 3.6, etc), and a CRAN snapshot
|
||||
to install libraries from on the given date. You can install more R packages from CRAN
|
||||
by adding a [install.R](#install-R) file to your repo. RStudio and IRKernel are
|
||||
installed by default for all R versions.
|
||||
|
||||
[packagemanager.posit.co](https://packagemanager.posit.co/client/#/)
|
||||
will be used to provide much faster installations via [binary packages](https://www.rstudio.com/blog/package-manager-v1-1-no-interruptions/).
|
||||
For *some* packages, this might require you install underlying system libraries
|
||||
using [apt.txt](#apt-txt) - look at the page for the CRAN package you are interested in at
|
||||
[packagemanager.posit.co](https://packagemanager.posit.co/client/#/) to find
|
||||
a list.
|
||||
|
||||
repo2docker stopped using the Microsoft mirror MRAN for older R versions after its shutdown in July, 2023.
|
||||
|
||||
### Supported versions of R
|
||||
|
||||
The default version of R is currently R 4.2. You can select the version of
|
||||
R you want to use by specifying it in the [runtime.txt](#runtime-txt)
|
||||
file.
|
||||
|
||||
We support R versions 3.4, 3.5, 3.6, 4.0, 4.1 and 4.2.
|
||||
|
||||
|
||||
## Julia
|
||||
|
||||
To build an environment with Julia, include a configuration file called
|
||||
`Project.toml`. The format of this file is documented at
|
||||
[the Julia Pkg.jl documentation](https://julialang.github.io/Pkg.jl/v1/).
|
||||
To specify a specific version of Julia to install, put a Julia version in the
|
||||
`[compat]` section of the `Project.toml` file, as described
|
||||
here: <https://julialang.github.io/Pkg.jl/v1/compatibility/>.
|
||||
|
||||
### Supported versions of Julia
|
||||
|
||||
All Julia versions since Julia 1.3 are supported via a [Project.toml](project-toml)
|
||||
file, and this is the recommended way to install Julia environments.
|
||||
|
||||
Julia < 1.3 and the older Julia REQUIRE file is no longer supported because required infrastructure has been removed.
|
||||
|
||||
|
||||
## Languages not covered here
|
||||
|
||||
If a language is not "officially" supported by a build pack, it can often be
|
||||
installed with a `postBuild` script. This will run arbitrary `bash` commands,
|
||||
and can be used to download / install a language.
|
||||
|
||||
## Using multiple languages at once
|
||||
|
||||
It may also be possible to combine multiple languages in a single environment.
|
||||
The details on how to accomplish this with all possible combinations are outside
|
||||
the scope of this guide. However we recommend that you take a look at the
|
||||
[Multi-Language Demo](https://github.com/binder-examples/multi-language-demo)
|
||||
repository for some inspiration.
|
||||
|
|
@ -1,102 +0,0 @@
|
|||
.. _languages:
|
||||
|
||||
=====================================
|
||||
Choose languages for your environment
|
||||
=====================================
|
||||
|
||||
You can define many different languages in your configuration files. This
|
||||
page describes how to use some of the more common ones.
|
||||
|
||||
Python
|
||||
======
|
||||
|
||||
Your environment will have Python (and specified dependencies) installed when
|
||||
you use one of the following configuration files:
|
||||
|
||||
* ``requirements.txt``
|
||||
* ``environment.yml``
|
||||
|
||||
.. note::
|
||||
|
||||
By default, the environment will have |default_python|.
|
||||
|
||||
.. versionchanged:: 0.8
|
||||
|
||||
Upgraded default Python from 3.6 to 3.7.
|
||||
|
||||
|
||||
Specifying a version of Python
|
||||
------------------------------
|
||||
|
||||
To specify a specific version of Python, you have two options:
|
||||
|
||||
* Use :ref:`environment.yml <environment.yml>`. Conda environments let you define
|
||||
the Python version in ``environment.yml``.
|
||||
To do so, add ``python=X.X`` to your dependencies section, like so::
|
||||
|
||||
name: python 2.7
|
||||
dependencies:
|
||||
- python=2.7
|
||||
- numpy
|
||||
|
||||
* Use :ref:`runtime.txt <runtime.txt>` with :ref:`requirements.txt <requirements.txt>`.
|
||||
If you are using ``requirements.txt`` instead of ``environment.yml``,
|
||||
you can specify the Python runtime version in a separate file called ``runtime.txt``.
|
||||
This file contains a single line of the following form::
|
||||
|
||||
python-X.X
|
||||
|
||||
For example::
|
||||
|
||||
python-3.6
|
||||
|
||||
|
||||
The R Language
|
||||
==============
|
||||
|
||||
repo2docker supports R, the open source `RStudio IDE <https://www.rstudio.com/>`_ as well
|
||||
as Jupyter support for R with the `IRKernel <https://irkernel.github.io/>`_. To set it up,
|
||||
you need to create a ``runtime.txt`` file with the following format:
|
||||
|
||||
r-<version>-<YYYY>-<MM>-<DD>
|
||||
|
||||
This will provide you R of given version (such as 4.1, 3.6, etc), and a CRAN snapshot
|
||||
to install libraries from on the given date. You can install more R packages from CRAN
|
||||
by adding a :ref:`install.R<install.R>` file to your repo. RStudio and IRKernel are
|
||||
installed by default for all R versions.
|
||||
|
||||
`packagemanager.posit.co <https://packagemanager.posit.co/client/#/>`_
|
||||
will be used to provide much faster installations via `binary packages <https://www.rstudio.com/blog/package-manager-v1-1-no-interruptions/>`_.
|
||||
For *some* packages, this might require you install underlying system libraries
|
||||
using :ref:`apt.txt` - look at the page for the CRAN package you are interested in at
|
||||
`packagemanager.posit.co <https://packagemanager.posit.co/client/#/>`_ to find
|
||||
a list.
|
||||
|
||||
repo2docker stopped using the Microsoft mirror MRAN for older R versions after its shutdown in July, 2023.
|
||||
|
||||
|
||||
Julia
|
||||
=====
|
||||
|
||||
To build an environment with Julia, include a configuration file called
|
||||
``Project.toml``. The format of this file is documented at
|
||||
`the Julia Pkg.jl documentation <https://julialang.github.io/Pkg.jl/v1/>`_.
|
||||
To specify a specific version of Julia to install, put a Julia version in the
|
||||
``[compat]`` section of the ``Project.toml`` file, as described
|
||||
here: https://julialang.github.io/Pkg.jl/v1/compatibility/.
|
||||
|
||||
Languages not covered here
|
||||
==========================
|
||||
|
||||
If a language is not "officially" supported by a build pack, it can often be
|
||||
installed with a ``postBuild`` script. This will run arbitrary ``bash`` commands,
|
||||
and can be used to download / install a language.
|
||||
|
||||
Using multiple languages at once
|
||||
================================
|
||||
|
||||
It may also be possible to combine multiple languages in a single environment.
|
||||
The details on how to accomplish this with all possible combinations are outside
|
||||
the scope of this guide. However we recommend that you take a look at the
|
||||
`Multi-Language Demo <https://github.com/binder-examples/multi-language-demo>`_
|
||||
repository for some inspiration.
|
||||
|
|
@ -0,0 +1,72 @@
|
|||
# Welcome to `repo2docker`'s documentation
|
||||
|
||||
`repo2docker` lets you **build, run, and push Docker images for data science from source code repositories**.
|
||||
|
||||
`repo2docker` can be used to explore a repository locally by building and executing the
|
||||
constructed image of the repository, or as a means of building images that
|
||||
are pushed to a Docker registry.
|
||||
|
||||
`repo2docker` can build a reproducible computational environment for any repository that
|
||||
follows the [Reproducible Executable Environment Specification](./specification.md). Repositories can be pulled from a number of repository providers, such as the URL of a Git repository, a [DOI](https://en.wikipedia.org/wiki/Digital_object_identifier) from Zenodo or Figshare, a [Handle](https://en.wikipedia.org/wiki/Handle_System) or DOI from a Dataverse installation, a [SWHID] of a directory of a revision archived in the
|
||||
[Software Heritage Archive](https://archive.softwareheritage.org), or a path to a local directory.
|
||||
|
||||
`repo2docker` is the tool used by [BinderHub](https://binderhub.readthedocs.io)
|
||||
to build images on demand.
|
||||
|
||||
## How `repo2docker` works
|
||||
|
||||
When you call `repo2docker` like so:
|
||||
|
||||
```
|
||||
jupyter-repo2docker <URL of repository>
|
||||
```
|
||||
|
||||
It performs these steps:
|
||||
|
||||
1. Inspects the repository for [configuration files](#config-files). These will be used to build the environment needed to run the repository.
|
||||
2. Builds a Docker image with an environment specified in these [configuration files](#config-files).
|
||||
3. Runs the image to let you explore the repository interactively via Jupyter notebooks, RStudio, or many other interfaces (this is optional)
|
||||
4. Pushes the images to a Docker registry so that it may be accessed remotely (this is optional)
|
||||
|
||||
[swhid]: https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html
|
||||
|
||||
Please report [Bugs](https://github.com/jupyterhub/repo2docker/issues),
|
||||
[ask questions](https://gitter.im/jupyterhub/binder) or
|
||||
[contribute to the project](https://github.com/jupyterhub/repo2docker/blob/HEAD/CONTRIBUTING.md).
|
||||
|
||||
## Get started with repo2docker
|
||||
|
||||
This tutorial walks you setting up repo2docker, building your first environment image, and running it locally with Docker.
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 2
|
||||
|
||||
start
|
||||
```
|
||||
|
||||
## Learn how to use repo2docker
|
||||
|
||||
Our user guide provides all of the information you need to configure and deploy the environment image you want.
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 2
|
||||
use/index
|
||||
```
|
||||
|
||||
## Contribute to repo2docker
|
||||
|
||||
Our contirbutor guide describes how you can follow along with the project, learn how to collaborate with our open team, and learn developer workflows and information.
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 2
|
||||
|
||||
contribute/index
|
||||
```
|
||||
|
||||
```{toctree}
|
||||
:caption: Changelog
|
||||
:maxdepth: 2
|
||||
:hidden: true
|
||||
|
||||
changelog
|
||||
```
|
||||
|
|
@ -1,42 +0,0 @@
|
|||
jupyter-repo2docker
|
||||
===================
|
||||
|
||||
``jupyter-repo2docker`` is a tool to **build, run, and push Docker
|
||||
images from source code repositories**.
|
||||
|
||||
``repo2docker`` fetches a repository
|
||||
(from GitHub, GitLab, Zenodo, Figshare, Dataverse installations, a Git repository or a local directory)
|
||||
and builds a container image in which the code can be executed.
|
||||
The image build process is based on the configuration files found in the repository.
|
||||
|
||||
``repo2docker`` can be
|
||||
used to explore a repository locally by building and executing the
|
||||
constructed image of the repository, or as a means of building images that
|
||||
are pushed to a Docker registry.
|
||||
|
||||
``repo2docker`` is the tool used by `BinderHub <https://binderhub.readthedocs.io>`_
|
||||
to build images on demand.
|
||||
|
||||
Please report `Bugs <https://github.com/jupyterhub/repo2docker/issues>`_,
|
||||
`ask questions <https://gitter.im/jupyterhub/binder>`_ or
|
||||
`contribute to the project <https://github.com/jupyterhub/repo2docker/blob/HEAD/CONTRIBUTING.md>`_.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Getting started with repo2docker
|
||||
|
||||
getting-started/index
|
||||
howto/index
|
||||
configuration/index
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contribute to repo2docker
|
||||
|
||||
contributing/index
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Changelog
|
||||
|
||||
changelog
|
||||
|
|
@ -1,79 +0,0 @@
|
|||
.. _install:
|
||||
|
||||
Installing ``repo2docker``
|
||||
==========================
|
||||
|
||||
repo2docker requires Python 3.6 or 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. The
|
||||
`Community Edition <https://docs.docker.com/install/>`_,
|
||||
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/HEAD/helm-chart/binderhub/values.yaml#L167>`_
|
||||
for more details.
|
||||
|
||||
Optional: Mercurial
|
||||
-------------------
|
||||
|
||||
For `Mercurial <https://www.mercurial-scm.org>`_ repositories, Mercurial and
|
||||
`hg-evolve <https://www.mercurial-scm.org/doc/evolution/>`_ need to be
|
||||
installed. For example, on Debian based distributions, one can do::
|
||||
|
||||
sudo apt install mercurial
|
||||
$(hg debuginstall --template "{pythonexe}") -m pip install hg-evolve --user
|
||||
|
||||
To install Mercurial on other systems, see `here
|
||||
<https://www.mercurial-scm.org/download>`_.
|
||||
|
||||
Note that for old Mercurial versions, you may need to specify a version for
|
||||
hg-evolve. For example, ``hg-evolve==9.2`` for hg 4.5 (which is installed with
|
||||
`apt` on Ubuntu 18.4).
|
||||
|
||||
Installing with ``pip``
|
||||
-----------------------
|
||||
|
||||
We recommend installing ``repo2docker`` with the ``pip`` tool::
|
||||
|
||||
python3 -m pip install jupyter-repo2docker
|
||||
|
||||
for the latest release. To install the most recent code from the upstream repository, run::
|
||||
|
||||
python3 -m pip install https://github.com/jupyterhub/repo2docker/archive/main.zip
|
||||
|
||||
For information on using ``repo2docker``, see :ref:`usage`.
|
||||
|
||||
Installing from source code
|
||||
---------------------------
|
||||
|
||||
Alternatively, you can install repo2docker from a local source tree,
|
||||
e.g. in case you are contributing back to this project::
|
||||
|
||||
git clone https://github.com/jupyterhub/repo2docker.git
|
||||
cd repo2docker
|
||||
python3 -m pip install -e .
|
||||
|
||||
That's it! For information on using ``repo2docker``, see
|
||||
:ref:`usage`.
|
||||
|
||||
.. _windows:
|
||||
|
||||
Windows support
|
||||
---------------
|
||||
|
||||
Windows support for ``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
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
(specification)=
|
||||
|
||||
# The Reproducible Execution Environment Specification
|
||||
|
||||
repo2docker scans a repository for particular {ref}`config-files`, such
|
||||
as `requirements.txt` or `Project.toml`. The collection of files, their contents,
|
||||
and the resulting actions that repo2docker takes is known
|
||||
as the **Reproducible Execution Environment Specification** (or REES).
|
||||
|
||||
The goal of the REES is to automate and encourage existing community best practices
|
||||
for reproducible computational environments. This includes installing packages using
|
||||
community-standard specification files and their corresponding tools,
|
||||
such as `requirements.txt` (with `pip`), `Project.toml` (with Julia), or
|
||||
`apt.txt` (with `apt`). While repo2docker automates the
|
||||
creation of the environment, a human should be able to look at a REES-compliant
|
||||
repository and reproduce the environment using common, clear steps without
|
||||
repo2docker software.
|
||||
|
||||
Currently, the definition of the REE Specification is the following:
|
||||
|
||||
> Any directory containing zero or more files from the {ref}`config-files` list is a
|
||||
> valid reproducible execution environment as defined by the REES. The
|
||||
> configuration files have to all be placed either in the root of the
|
||||
> directory, in a `binder/` sub-directory or a `.binder/` sub-directory.
|
||||
|
||||
For example, the REES recognises `requirements.txt` as a valid config file.
|
||||
The file format is as defined by the `requirements.txt` standard of the Python
|
||||
community. A REES-compliant tool will install a Python interpreter (of unspecified version)
|
||||
and perform the equivalent action of `pip install -r requirements.txt` so that the
|
||||
user can afterwards run python and use the packages installed.
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
.. _specification:
|
||||
|
||||
====================================================
|
||||
The Reproducible Execution Environment Specification
|
||||
====================================================
|
||||
|
||||
repo2docker scans a repository for particular :ref:`config-files`, such
|
||||
as ``requirements.txt`` or ``Project.toml``. The collection of files, their contents,
|
||||
and the resulting actions that repo2docker takes is known
|
||||
as the **Reproducible Execution Environment Specification** (or REES).
|
||||
|
||||
The goal of the REES is to automate and encourage existing community best practices
|
||||
for reproducible computational environments. This includes installing packages using
|
||||
community-standard specification files and their corresponding tools,
|
||||
such as ``requirements.txt`` (with ``pip``), ``Project.toml`` (with Julia), or
|
||||
``apt.txt`` (with ``apt``). While repo2docker automates the
|
||||
creation of the environment, a human should be able to look at a REES-compliant
|
||||
repository and reproduce the environment using common, clear steps without
|
||||
repo2docker software.
|
||||
|
||||
Currently, the definition of the REE Specification is the following:
|
||||
|
||||
Any directory containing zero or more files from the :ref:`config-files` list is a
|
||||
valid reproducible execution environment as defined by the REES. The
|
||||
configuration files have to all be placed either in the root of the
|
||||
directory, in a ``binder/`` sub-directory or a ``.binder/`` sub-directory.
|
||||
|
||||
For example, the REES recognises ``requirements.txt`` as a valid config file.
|
||||
The file format is as defined by the ``requirements.txt`` standard of the Python
|
||||
community. A REES-compliant tool will install a Python interpreter (of unspecified version)
|
||||
and perform the equivalent action of ``pip install -r requirements.txt`` so that the
|
||||
user can afterwards run python and use the packages installed.
|
||||
|
|
@ -0,0 +1,62 @@
|
|||
# Get started
|
||||
|
||||
This tutorial guides you through installing `repo2docker` and building your first environment image.
|
||||
|
||||
(install)=
|
||||
|
||||
## Install `repo2docker`
|
||||
|
||||
repo2docker requires Python 3.6 or above on Linux and macOS.
|
||||
|
||||
:::{admonition} Windows support is experimental
|
||||
|
||||
This [article about using Windows and the WSL](https://nickjanetakis.com/blog/setting-up-docker-for-windows-and-wsl-to-work-flawlessly) (Windows Subsytem for Linux or
|
||||
Bash on Windows) provides additional information about Windows and Docker.
|
||||
:::
|
||||
|
||||
### Prerequisite: Install Docker
|
||||
|
||||
Install [Docker](https://www.docker.com), as it is required to build Docker images.
|
||||
The [Community Edition](https://docs.docker.com/install/) is available for free.
|
||||
|
||||
Recent versions of Docker are recommended.
|
||||
|
||||
### Install `repo2docker` with `pip`
|
||||
|
||||
We recommend installing `repo2docker` with the `pip` tool:
|
||||
|
||||
```
|
||||
python3 -m pip install jupyter-repo2docker
|
||||
```
|
||||
|
||||
(usage)=
|
||||
|
||||
## Build a repository with `repo2docker`
|
||||
|
||||
Now that you've installed Docker and `repo2docker`, we can build a repository.
|
||||
To do so, follow these steps.
|
||||
|
||||
### Start Docker
|
||||
|
||||
Follow the [instructions for starting Docker](https://docs.docker.com/engine/daemon/start/) to start a Docker process.
|
||||
|
||||
### Build an image from a URL
|
||||
|
||||
Next we'll build a reproducible image from a URL. We'll use the [Binder `requirements.txt` example](https://github.com/binder-examples/requirements), which installs a simple Python environment. Run the following command:
|
||||
|
||||
```bash
|
||||
jupyter-repo2docker https://github.com/binder-examples/requirements
|
||||
```
|
||||
|
||||
You'll see `repo2docker` take the following actions:
|
||||
|
||||
1. Inspect the repository for [configuration files](#config-files). It will detect the `requirements.txt` file in the repository.
|
||||
2. Build a Docker image using the configuration files. In this case, the `requirements.txt` file will correspond to a Python environment.
|
||||
3. Run the image to let you explore the repository interactively.
|
||||
|
||||
Click the link provided and you'll be taken to an interactive Jupyter Notebook interface where you can run commands interactively inside the environment.
|
||||
|
||||
## Learn more
|
||||
|
||||
This is a simple example building an environment image for your repository.
|
||||
To learn more about the kinds of source repositories, environments, and use-cases that repo2docker supports, see [the `repo2docker` user guide](./use/index.md).
|
||||
|
|
@ -1,140 +0,0 @@
|
|||
.. _usage:
|
||||
|
||||
=====================
|
||||
Using ``repo2docker``
|
||||
=====================
|
||||
|
||||
.. note::
|
||||
|
||||
`Docker <https://docs.docker.com/>`_ **must be running** in
|
||||
order to run ``repo2docker``. For more information on installing
|
||||
``repo2docker``, see :ref:`install`.
|
||||
|
||||
``repo2docker`` can build a reproducible computational environment for any repository that
|
||||
follows :ref:`specification`. repo2docker is called with the URL of a Git repository,
|
||||
a `DOI <https://en.wikipedia.org/wiki/Digital_object_identifier>`_ from Zenodo or Figshare,
|
||||
a `Handle <https://en.wikipedia.org/wiki/Handle_System>`_ or DOI from a Dataverse installation,
|
||||
a `SWHID`_ of a directory of a revision archived in the
|
||||
`Software Heritage Archive <https://archive.softwareheritage.org>`_,
|
||||
or a path to a local directory.
|
||||
|
||||
It then performs these steps:
|
||||
|
||||
1. Inspects the repository for :ref:`configuration files <config-files>`. These will be used to build
|
||||
the environment needed to run the repository.
|
||||
2. Builds a Docker image with an environment specified in these :ref:`configuration files <config-files>`.
|
||||
3. Launches the image to let you explore the
|
||||
repository interactively via Jupyter notebooks, RStudio, or many other interfaces (optional)
|
||||
4. Pushes the images to a Docker registry so that it may be accessed remotely
|
||||
(optional)
|
||||
|
||||
Calling repo2docker
|
||||
===================
|
||||
|
||||
repo2docker is called with this command::
|
||||
|
||||
jupyter-repo2docker <source-repository>
|
||||
|
||||
where ``<source-repository>`` is:
|
||||
|
||||
* a URL of a Git repository (``https://github.com/binder-examples/requirements``),
|
||||
* a Zenodo DOI (``10.5281/zenodo.1211089``),
|
||||
* a SWHID_ (``swh:1:rev:999dd06c7f679a2714dfe5199bdca09522a29649``),
|
||||
* a URL of a CKAN_ dataset (``https://demo.ckan.org/dataset/sample-dataset-1``), or
|
||||
* a path to a local directory (``a/local/directory``)
|
||||
|
||||
of the source repository you want to build.
|
||||
|
||||
For example, the following command will build an image of Peter Norvig's
|
||||
Pytudes_ repository::
|
||||
|
||||
jupyter-repo2docker https://github.com/norvig/pytudes
|
||||
|
||||
Building the image may take a few minutes.
|
||||
|
||||
Pytudes_
|
||||
uses a `requirements.txt file <https://github.com/norvig/pytudes/blob/HEAD/requirements.txt>`_
|
||||
to specify its Python environment. Because of this, ``repo2docker`` will use
|
||||
``pip`` to install dependencies listed in this ``requirement.txt`` file, and
|
||||
these will be present in the generated Docker 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
|
||||
|
||||
Pasting the URL into your browser will open Jupyter Notebook with the
|
||||
dependencies and contents of the source repository in the built image.
|
||||
|
||||
|
||||
Building a specific branch, commit or tag
|
||||
=========================================
|
||||
|
||||
To build a particular branch and commit, use the argument ``--ref`` and
|
||||
specify the ``branch-name`` or ``commit-hash``. For example::
|
||||
|
||||
jupyter-repo2docker --ref 9ced85dd9a84859d0767369e58f33912a214a3cf https://github.com/norvig/pytudes
|
||||
|
||||
.. tip::
|
||||
For reproducible builds, we recommend specifying a commit-hash to
|
||||
deterministically build a fixed version of a repository. Not specifying a
|
||||
commit-hash will result in the latest commit of the repository being built.
|
||||
|
||||
|
||||
.. _usage-config-file-location:
|
||||
|
||||
Where to put configuration files
|
||||
================================
|
||||
|
||||
``repo2docker`` will look for configuration files in:
|
||||
|
||||
* A folder named ``binder/`` in the root of the repository.
|
||||
* A folder named ``.binder/`` in the root of the repository.
|
||||
* The root directory of the repository.
|
||||
|
||||
Having both ``binder/`` and ``.binder/`` folders is not allowed.
|
||||
If one of these folders exists, only configuration files in that folder are considered, configuration in the root directory will be ignored.
|
||||
|
||||
Check the complete list of :ref:`configuration files <config-files>` supported
|
||||
by ``repo2docker`` to see how to configure the build process.
|
||||
|
||||
.. note::
|
||||
|
||||
``repo2docker`` builds an environment with Python 3.7 by default. If you'd
|
||||
like a different version, you can specify this in your
|
||||
:ref:`configuration files <config-files>`.
|
||||
|
||||
|
||||
Debugging repo2docker with ``--debug`` and ``--no-build``
|
||||
=========================================================
|
||||
|
||||
To debug the docker image being built, pass the ``--debug`` parameter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
jupyter-repo2docker --debug https://github.com/norvig/pytudes
|
||||
|
||||
This will print the generated ``Dockerfile``, build it, and run it.
|
||||
|
||||
To see the generated ``Dockerfile`` without actually building it,
|
||||
pass ``--no-build`` to the commandline. This ``Dockerfile`` output
|
||||
is for **debugging purposes** of ``repo2docker`` only - it can not
|
||||
be used by docker directly.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
jupyter-repo2docker --no-build --debug https://github.com/norvig/pytudes
|
||||
|
||||
|
||||
Command line API
|
||||
================
|
||||
|
||||
.. autoprogram:: repo2docker.__main__:argparser
|
||||
:prog: jupyter-repo2docker
|
||||
|
||||
|
||||
.. _Pytudes: https://github.com/norvig/pytudes
|
||||
.. _SWHID: https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html
|
||||
.. _CKAN: https://ckan.org
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
# User guide
|
||||
|
||||
Short, actionable guides that cover specific topics with repo2docker.
|
||||
Select from the pages listed below to get started.
|
||||
|
||||
Information about configuring your repository to work with repo2docker,
|
||||
and controlling elements of the built environment using configuration files.
|
||||
|
||||
```{toctree}
|
||||
:caption: Configuration basics
|
||||
:maxdepth: 1
|
||||
../configuration/index
|
||||
repository
|
||||
../cli
|
||||
```
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
:caption: Customize your environment
|
||||
|
||||
../howto/user_interface
|
||||
../howto/languages
|
||||
../howto/lab_workspaces
|
||||
../howto/export_environment
|
||||
../howto/base_image
|
||||
```
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
:caption: Deploy into production
|
||||
|
||||
../howto/deploy
|
||||
../howto/jupyterhub_images
|
||||
../howto/breaking_changes
|
||||
```
|
||||
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 2
|
||||
:caption: Learn about repo2docker
|
||||
|
||||
../faq
|
||||
../specification
|
||||
```
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
# Using source repositories
|
||||
|
||||
(usage-config-file-location)=
|
||||
|
||||
## Where to put configuration files in a repository
|
||||
|
||||
`repo2docker` will look for configuration files in the following order:
|
||||
|
||||
* The root directory of the repository.
|
||||
* A folder named `binder/` or `.binder/` in the root of the repository.
|
||||
|
||||
If one of these folders exists, only configuration files in that folder are considered, configuration in the root directory will be ignored.
|
||||
Having both `binder/` and `.binder/` folders is not allowed.
|
||||
|
||||
Check the complete list of [configuration files](#config-files) supported
|
||||
by `repo2docker` to see how to configure the build process.
|
||||
|
||||
(repository-providers)=
|
||||
## Supported repository providers
|
||||
|
||||
repo2docker can fetch repositories from a number of repositories. Here are the ones we support:
|
||||
|
||||
- A URL of a Git repository (`https://github.com/binder-examples/requirements`),
|
||||
- A Zenodo DOI (`10.5281/zenodo.1211089`),
|
||||
- A [SWHID] (`swh:1:rev:999dd06c7f679a2714dfe5199bdca09522a29649`),
|
||||
- A URL of a [CKAN] dataset (`https://demo.ckan.org/dataset/sample-dataset-1`)
|
||||
- A path to a local directory (`a/local/directory`)
|
||||
|
||||
[swhid]: https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html
|
||||
[ckan]: https://ckan.org
|
||||
|
||||
In each case you can build from these repository sources like so:
|
||||
|
||||
```bash
|
||||
jupyter-repo2docker <URL-ID-or-path>
|
||||
```
|
||||
|
||||
|
||||
## Supported version control systems
|
||||
|
||||
These Version Control Systems are supported by `repo2docker`.
|
||||
|
||||
### Git
|
||||
|
||||
Any `git` repository is supported with `repo2docker`.
|
||||
These are generally stored in [a git repository provider](#repository-providers) like [GitHub](https://github.com).
|
||||
|
||||
### Mercurial
|
||||
|
||||
For [Mercurial](https://www.mercurial-scm.org) repositories, Mercurial and
|
||||
[hg-evolve](https://www.mercurial-scm.org/doc/evolution/) need to be
|
||||
installed. For example, on Debian based distributions, one can do:
|
||||
|
||||
```
|
||||
sudo apt install mercurial
|
||||
$(hg debuginstall --template "{pythonexe}") -m pip install hg-evolve --user
|
||||
```
|
||||
|
||||
To install Mercurial on other systems, see [here](https://www.mercurial-scm.org/download).
|
||||
|
||||
Note that for old Mercurial versions, you may need to specify a version for
|
||||
hg-evolve. For example, `hg-evolve==9.2` for hg 4.5 (which is installed with
|
||||
`apt` on Ubuntu 18.4).
|
||||
Ładowanie…
Reference in New Issue