kopia lustrzana https://github.com/jupyterhub/repo2docker
Change FAQ format to reStructuredText
- allows for admonition - fixes reST/Sphinx directive used in Markdown - removes dead linkpull/425/head
Evert Rol
rodzic
754edd01c4
commit
0adfed437b
|
|
@ -1,100 +0,0 @@
|
|||
# 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.
|
||||
|
||||
## What versions of Python (or R or Julia...) are supported?
|
||||
|
||||
### Python
|
||||
|
||||
Repo2docker officially supports the following versions of Python (specified in environment.yml or runtime.txt):
|
||||
|
||||
- 3.7 (added in 0.7)
|
||||
- 3.6 (default)
|
||||
- 3.5
|
||||
|
||||
Additional versions may work, as long as the
|
||||
[base environment](https://github.com/jupyter/repo2docker/blob/master/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.
|
||||
|
||||
Additionally, if Python 2.7 is specified,
|
||||
a separate environment for the kernel will be installed with Python 2.
|
||||
The notebook server will run in the default Python 3.6 environment.
|
||||
|
||||
### Julia
|
||||
|
||||
The following versions of Julia are supported (specified in REQUIRE):
|
||||
|
||||
- 1.0 (added in 0.7)
|
||||
- 0.7 (added in 0.7)
|
||||
- 0.6 (default)
|
||||
|
||||
### R
|
||||
|
||||
Only R 3.4.4 is currently supported, which is installed via `apt` from the
|
||||
[ubuntu bionic repository](https://packages.ubuntu.com/bionic/r-base).
|
||||
|
||||
## 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?
|
||||
|
||||
Use the `-e` or `--env` 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](https://github.com/jupyter/repo2docker/blob/master/repo2docker/detectors.py#L381).
|
||||
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 repository within a Docker environment?
|
||||
|
||||
Yes: use the `--editable` or `-E` flag (don't confuse it 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` file or `Dockerfile`), then
|
||||
runs that container, while connecting the home 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
|
||||
webbrowser, 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, for
|
||||
example, notebooks.
|
||||
|
||||
**note**
|
||||
|
||||
Editable mode is a convenience option that will mount the repository
|
||||
to container working directory (usually `/home/$USER`). 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.
|
||||
|
|
@ -0,0 +1,115 @@
|
|||
.. _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.
|
||||
|
||||
What versions of Python (or R or Julia...) are supported?
|
||||
---------------------------------------------------------
|
||||
|
||||
Python
|
||||
~~~~~~
|
||||
|
||||
Repo2docker officially supports the following versions of Python (specified in environment.yml or runtime.txt):
|
||||
|
||||
- 3.7 (added in 0.7)
|
||||
- 3.6 (default)
|
||||
- 3.5
|
||||
|
||||
Additional versions may work, as long as the
|
||||
`base environment <https://github.com/jupyter/repo2docker/blob/master/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.
|
||||
|
||||
Additionally, if Python 2.7 is specified,
|
||||
a separate environment for the kernel will be installed with Python 2.
|
||||
The notebook server will run in the default Python 3.6 environment.
|
||||
|
||||
Julia
|
||||
~~~~~
|
||||
|
||||
The following versions of Julia are supported (specified in REQUIRE):
|
||||
|
||||
- 1.0 (added in 0.7)
|
||||
- 0.7 (added in 0.7)
|
||||
- 0.6 (default)
|
||||
|
||||
R
|
||||
~
|
||||
|
||||
Only R 3.4.4 is currently supported, which is installed via ``apt`` from the
|
||||
`ubuntu bionic repository <https://packages.ubuntu.com/bionic/r-base>`_.
|
||||
|
||||
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?
|
||||
-----------------------------------
|
||||
|
||||
Use the ``-e`` or ``--env`` 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 webbrowser, 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.
|
||||
Ładowanie…
Reference in New Issue