kopia lustrzana https://github.com/jupyterhub/repo2docker
Merge pull request #1442 from rgaiacs/improve-documentation
Minor improvements to documentationpull/1401/head
Simon Li
GitHub
commit
09b056ede6
|
|
@ -60,7 +60,7 @@ release = version
|
|||
|
||||
from repo2docker.buildpacks.conda import CondaBuildPack
|
||||
|
||||
default_python = f"`Python {CondaBuildPack.major_pythons['3']}`"
|
||||
default_python = f"Python {CondaBuildPack.major_pythons['3']}"
|
||||
myst_substitutions = {
|
||||
"default_python": default_python,
|
||||
"default_python_version": default_python,
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ both kinds.
|
|||
|
||||
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)
|
||||
[example `requirements.txt` file](https://github.com/binder-examples/requirements/blob/HEAD/requirements.txt)
|
||||
on GitHub shows a typical requirements file.
|
||||
|
||||
(setup-py)=
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
(config-files)=
|
||||
|
||||
# Configuration files supported by repo2docker
|
||||
# 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
|
||||
|
|
@ -15,7 +15,7 @@ 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).
|
||||
can be found in the next sections.
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 2
|
||||
|
|
|
|||
|
|
@ -8,18 +8,18 @@
|
|||
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`.
|
||||
Rather, it updates a [pre-defined base conda environment](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. See [the `conda` environment management instructions](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-file-manually) for more information.
|
||||
You can install files from [PyPI](https://pypi.org/) in your `environment.yml` as well.
|
||||
For example, see the [example `environment.yml` file](https://github.com/binder-examples/python-conda_pip/blob/HEAD/environment.yml) file. See [the `conda` environment management instructions](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-file-manually) for more information.
|
||||
:::
|
||||
|
||||
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 the `environment.yml` of your Git repository.
|
||||
`conda` should support all versions of Python, though `repo2docker` support is best with `Python 3.7-3.11`.
|
||||
`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
|
||||
|
|
@ -28,7 +28,7 @@ If you include a Python version in a `runtime.txt` file in addition to your
|
|||
|
||||
(install-r)=
|
||||
|
||||
## `install.R` - Install packages with R/RStudio
|
||||
## `install.R` - Install R packages
|
||||
|
||||
This is used to install R libraries pinned to a specific snapshot on
|
||||
[Posit Package Manager](https://packagemanager.posit.co/).
|
||||
|
|
@ -38,7 +38,7 @@ To set the date of the snapshot, or to specify a specific version of R, add a [r
|
|||
|
||||
(description)=
|
||||
|
||||
## `DESCRIPTION` - Install an R package
|
||||
## `DESCRIPTION` - Install as 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())`.
|
||||
|
|
|
|||
|
|
@ -2,20 +2,23 @@
|
|||
|
||||
(apt-txt)=
|
||||
|
||||
## `apt.txt` - Install packages with apt-get
|
||||
## `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.
|
||||
A list of packages in the [`.deb`](<https://en.wikipedia.org/wiki/Deb_(file_format)>) format that should be installed. The `.deb` files are downloaded from the server configured in the Docker base image.
|
||||
|
||||
```{note}
|
||||
If a `Dockerfile` is not used to change the Docker base image, the base image is [Ubuntu](https://ubuntu.com/) [22.04 LTS (Jammy Jellyfish)](https://releases.ubuntu.com/jammy/). All `.deb` files availables are listed in [Ubuntu Packages](https://packages.ubuntu.com/jammy/).
|
||||
```
|
||||
|
||||
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).
|
||||
[example `apt.txt` file 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`.
|
||||
For these cases, we have a special `runtime.txt` file.
|
||||
|
||||
:::{warning}
|
||||
`runtime.txt` is only supported when used with environment specifications
|
||||
|
|
@ -25,23 +28,34 @@ that do not already support specifying the runtime
|
|||
|
||||
### Set the Python version
|
||||
|
||||
Add the line `python-x.y` in `runtime.txt` to run the repository with Python version x.y.
|
||||
Add the line `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).
|
||||
|
||||
### Set the R version
|
||||
|
||||
Add the line `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 the [Posit Package Manager](https://packagemanager.posit.co/client/#/repos/2/overview).
|
||||
Add the line `r-x.y-YYYY-MM-DD` in `runtime.txt` to run the repository with R version `x.y` and libraries from a `YYYY-MM-DD` snapshot of the [Posit Package Manager](https://packagemanager.posit.co/client/#/repos/2/overview).
|
||||
|
||||
The version of R, i.e. `x.y`, can be set to
|
||||
|
||||
- `4.4`
|
||||
- `4.3`
|
||||
- `4.2`
|
||||
- `4.1`
|
||||
- `4.0`
|
||||
- `3.6`
|
||||
- `3.5`
|
||||
- `3.4`
|
||||
- `3.3`
|
||||
|
||||
`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.
|
||||
|
||||
See our [R example repository](https://github.com/binder-examples/r/blob/HEAD/runtime.txt).
|
||||
|
||||
(default-nix)=
|
||||
|
||||
## `default.nix` - the nix package manager
|
||||
## `default.nix` - the `nix` package manager
|
||||
|
||||
Specify packages to be installed by the [nix package manager](https://github.com/NixOS/nixpkgs).
|
||||
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
|
||||
|
|
@ -54,7 +68,7 @@ a `nix` expression written in a `default.nix` file. Make sure to
|
|||
to produce a reproducible environment.
|
||||
|
||||
To see an example repository visit
|
||||
[nix binder example](https://github.com/binder-examples/nix).
|
||||
[nix example repository](https://github.com/binder-examples/nix).
|
||||
|
||||
(dockerfile)=
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
# User guide
|
||||
|
||||
Short, actionable guides that cover specific topics with repo2docker.
|
||||
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,
|
||||
Information about configuring your repository to work with `repo2docker`,
|
||||
and controlling elements of the built environment using configuration files.
|
||||
|
||||
```{toctree}
|
||||
|
|
|
|||
|
|
@ -41,21 +41,21 @@ This is not the same thing as forking the repository for the community image, mo
|
|||
:::{grid-item-card} Benefits
|
||||
|
||||
- Only need to maintain the changes you make
|
||||
- Update the FROM tag to keep up with upstream changes
|
||||
- You must manage a GH repo
|
||||
- Works well with mybinder.org
|
||||
- Update the `FROM` tag to keep up with upstream changes
|
||||
- You must manage a Git repository
|
||||
- Works well with [mybinder.org]
|
||||
:::
|
||||
:::{grid-item-card} Drawbacks
|
||||
- Need to understand how upstream image is built so you can customize
|
||||
- Documentation for this method currently sucks (but can be fixed!)
|
||||
- Removing existing packages might break things
|
||||
- You must manage a GH repo
|
||||
- You must manage a Git repository
|
||||
:::
|
||||
::::
|
||||
|
||||
See [](./extend-community-image.md) for a how-to guide.
|
||||
|
||||
## 3. Use repo2docker to build your environment image
|
||||
## 3. Use `repo2docker` to build your environment image
|
||||
|
||||
If your needs differ far enough from the community-maintained images that you find, you can use `repo2docker` to build your environment image using [supported configuration files](#config-files).
|
||||
To learn how to do this, follow the [getting started with repo2docker guide](../start.md) and look at the [list of supported configuration files](#config-files).
|
||||
|
|
@ -64,7 +64,7 @@ Check out the other sections under "Image building basics" for more useful how-t
|
|||
::::{grid} 2
|
||||
:::{grid-item-card} Benefits
|
||||
|
||||
- Works well with mybinder.org
|
||||
- Works well with [mybinder.org]
|
||||
- No need to learn Dockerfile syntax
|
||||
- Use language specific, well understood file formats
|
||||
- Only get whatever packages you want
|
||||
|
|
@ -79,7 +79,7 @@ Check out the other sections under "Image building basics" for more useful how-t
|
|||
|
||||
## 4. Use a full fledged custom Dockerfile
|
||||
|
||||
If you need full control over the entire computational environment, you can always create your own `Dockerfile` from scratch, and repo2docker will build an image out of it.
|
||||
If you need full control over the entire computational environment, you can always create your own `Dockerfile` from scratch, and `repo2docker` will build an image out of it.
|
||||
|
||||
This is for advanced users only that know what they're doing - full guidance on how to use `Dockerfiles` is out of scope for this tutorial.
|
||||
|
||||
|
|
@ -90,13 +90,15 @@ This is for advanced users only that know what they're doing - full guidance on
|
|||
|
||||
- Get exactly what you want
|
||||
- Can be optimized for small image size & fast build times
|
||||
- Lots of existing documentation in the SRE world on how to use these
|
||||
- Lots of existing documentation in the site reliability engineer world on how to use these
|
||||
|
||||
:::
|
||||
:::{grid-item-card} Drawbacks
|
||||
|
||||
- Requires a lot of knowledge for ongoing maintenance
|
||||
- Might have to solve problems yourself that were solved in upstream images / repo2docker
|
||||
- Need to adapt existing documentation from the SRE use case to interactive computing use case
|
||||
- Need to adapt existing documentation from the site reliability engineer use case to interactive computing use case
|
||||
:::
|
||||
::::
|
||||
|
||||
[mybinder.org]: https://mybinder.org
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue