From 63026f55a51d296aafe189a2f05f797b0c58acf3 Mon Sep 17 00:00:00 2001 From: choldgraf Date: Fri, 25 Jul 2025 15:39:04 -0700 Subject: [PATCH 01/12] Revamp our documentation --- .readthedocs.yaml | 1 + docs/requirements.txt | 4 +- docs/source/_static/images/logo-dark.png | Bin 0 -> 9766 bytes docs/source/_static/images/logo.png | Bin 13493 -> 10111 bytes docs/source/cli.md | 89 +++++++ docs/source/conf.py | 8 + docs/source/config_files.rst | 245 ------------------ docs/source/configuration/actions.md | 33 +++ docs/source/configuration/datascience.md | 63 +++++ docs/source/configuration/development.md | 42 +++ docs/source/configuration/index.md | 30 +++ docs/source/configuration/index.rst | 15 -- docs/source/configuration/system.md | 75 ++++++ .../{contributing => contribute}/buildpack.md | 0 .../contentprovider.rst | 0 .../contributing.md | 0 .../{contributing => contribute}/index.rst | 13 +- .../{contributing => contribute}/roadmap.md | 0 .../{contributing => contribute}/tasks.md | 0 docs/source/faq.md | 111 ++++++++ docs/source/faq.rst | 192 -------------- docs/source/getting-started/index.rst | 13 - docs/source/howto/export_environment.rst | 6 +- docs/source/howto/index.rst | 19 -- docs/source/howto/languages.md | 138 ++++++++++ docs/source/howto/languages.rst | 102 -------- docs/source/index.md | 72 +++++ docs/source/index.rst | 42 --- docs/source/install.rst | 79 ------ docs/source/specification.md | 30 +++ docs/source/specification.rst | 32 --- docs/source/start.md | 62 +++++ docs/source/usage.rst | 140 ---------- docs/source/use/index.md | 44 ++++ docs/source/use/repository.md | 63 +++++ 35 files changed, 875 insertions(+), 888 deletions(-) create mode 100644 docs/source/_static/images/logo-dark.png create mode 100644 docs/source/cli.md delete mode 100644 docs/source/config_files.rst create mode 100644 docs/source/configuration/actions.md create mode 100644 docs/source/configuration/datascience.md create mode 100644 docs/source/configuration/development.md create mode 100644 docs/source/configuration/index.md delete mode 100644 docs/source/configuration/index.rst create mode 100644 docs/source/configuration/system.md rename docs/source/{contributing => contribute}/buildpack.md (100%) rename docs/source/{contributing => contribute}/contentprovider.rst (100%) rename docs/source/{contributing => contribute}/contributing.md (100%) rename docs/source/{contributing => contribute}/index.rst (71%) rename docs/source/{contributing => contribute}/roadmap.md (100%) rename docs/source/{contributing => contribute}/tasks.md (100%) create mode 100644 docs/source/faq.md delete mode 100644 docs/source/faq.rst delete mode 100644 docs/source/getting-started/index.rst delete mode 100644 docs/source/howto/index.rst create mode 100644 docs/source/howto/languages.md delete mode 100644 docs/source/howto/languages.rst create mode 100644 docs/source/index.md delete mode 100644 docs/source/index.rst delete mode 100644 docs/source/install.rst create mode 100644 docs/source/specification.md delete mode 100644 docs/source/specification.rst create mode 100644 docs/source/start.md delete mode 100644 docs/source/usage.rst create mode 100644 docs/source/use/index.md create mode 100644 docs/source/use/repository.md diff --git a/.readthedocs.yaml b/.readthedocs.yaml index dde32e62f..7bb04d170 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,6 +6,7 @@ version: 2 sphinx: configuration: docs/source/conf.py + builder: dirhtml build: os: ubuntu-22.04 diff --git a/docs/requirements.txt b/docs/requirements.txt index 5c38c561a..534bac560 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -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 diff --git a/docs/source/_static/images/logo-dark.png b/docs/source/_static/images/logo-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..36c9868044fdb182da3621e91f99a196a7afc2e6 GIT binary patch literal 9766 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 A82|tP literal 0 HcmV?d00001 diff --git a/docs/source/_static/images/logo.png b/docs/source/_static/images/logo.png index 9e03007d007cb9af935f0a5042cc448826843d44..c3a4979840ecdf74e0f56fd58f78a322b403286c 100644 GIT binary patch literal 10111 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 +``` + +where `` 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 diff --git a/docs/source/conf.py b/docs/source/conf.py index 2dcb08615..dec065cb4 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -73,12 +73,20 @@ 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", diff --git a/docs/source/config_files.rst b/docs/source/config_files.rst deleted file mode 100644 index 975f82c85..000000000 --- a/docs/source/config_files.rst +++ /dev/null @@ -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 `_ 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 `_ -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 `_ 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 - `_ - 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 `_ 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 `_ -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 `_. -To set the date of the snapshot add a runtime.txt_. -For an example ``install.R`` file, visit our `example install.R file `_. - - -.. _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 `_. - - -.. _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---
``, 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 `_. - - -.. _start: - -``start`` - Run code before the user sessions starts -==================================================== - -A script that can contain simple commands to be run at runtime (as an -`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 `_. - -Have ``r----
`` in ``runtime.txt`` to run the repository with R version RVERSION and libraries from a YYYY-MM-DD snapshot of `Posit Package Manager `__. -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 `_. - -.. _default.nix: - -``default.nix`` - the nix package manager -========================================= - -Specify packages to be installed by the `nix package manager `_. -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 `_ is used to evaluate -a ``nix`` expression written in a ``default.nix`` file. Make sure to -`pin your nixpkgs `_ -to produce a reproducible environment. - -To see an example repository visit -`nix binder example `_. - - -.. _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 `_ for -best-practices with Dockerfiles. diff --git a/docs/source/configuration/actions.md b/docs/source/configuration/actions.md new file mode 100644 index 000000000..8a25a319a --- /dev/null +++ b/docs/source/configuration/actions.md @@ -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. \ No newline at end of file diff --git a/docs/source/configuration/datascience.md b/docs/source/configuration/datascience.md new file mode 100644 index 000000000..750b75714 --- /dev/null +++ b/docs/source/configuration/datascience.md @@ -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---
`, 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. diff --git a/docs/source/configuration/development.md b/docs/source/configuration/development.md new file mode 100644 index 000000000..e661635b3 --- /dev/null +++ b/docs/source/configuration/development.md @@ -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. diff --git a/docs/source/configuration/index.md b/docs/source/configuration/index.md new file mode 100644 index 000000000..e70edc08a --- /dev/null +++ b/docs/source/configuration/index.md @@ -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 +``` \ No newline at end of file diff --git a/docs/source/configuration/index.rst b/docs/source/configuration/index.rst deleted file mode 100644 index de8e579e3..000000000 --- a/docs/source/configuration/index.rst +++ /dev/null @@ -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 diff --git a/docs/source/configuration/system.md b/docs/source/configuration/system.md new file mode 100644 index 000000000..dbb1ae243 --- /dev/null +++ b/docs/source/configuration/system.md @@ -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----
` 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. diff --git a/docs/source/contributing/buildpack.md b/docs/source/contribute/buildpack.md similarity index 100% rename from docs/source/contributing/buildpack.md rename to docs/source/contribute/buildpack.md diff --git a/docs/source/contributing/contentprovider.rst b/docs/source/contribute/contentprovider.rst similarity index 100% rename from docs/source/contributing/contentprovider.rst rename to docs/source/contribute/contentprovider.rst diff --git a/docs/source/contributing/contributing.md b/docs/source/contribute/contributing.md similarity index 100% rename from docs/source/contributing/contributing.md rename to docs/source/contribute/contributing.md diff --git a/docs/source/contributing/index.rst b/docs/source/contribute/index.rst similarity index 71% rename from docs/source/contributing/index.rst rename to docs/source/contribute/index.rst index 09939de58..75f2342da 100644 --- a/docs/source/contributing/index.rst +++ b/docs/source/contribute/index.rst @@ -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 diff --git a/docs/source/contributing/roadmap.md b/docs/source/contribute/roadmap.md similarity index 100% rename from docs/source/contributing/roadmap.md rename to docs/source/contribute/roadmap.md diff --git a/docs/source/contributing/tasks.md b/docs/source/contribute/tasks.md similarity index 100% rename from docs/source/contributing/tasks.md rename to docs/source/contribute/tasks.md diff --git a/docs/source/faq.md b/docs/source/faq.md new file mode 100644 index 000000000..4f48a2752 --- /dev/null +++ b/docs/source/faq.md @@ -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. diff --git a/docs/source/faq.rst b/docs/source/faq.rst deleted file mode 100644 index d643264b8..000000000 --- a/docs/source/faq.rst +++ /dev/null @@ -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 ` or -:ref:`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 `_ -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 ` -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 ` -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 ` 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 `_ 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 `_. -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 `_ is a short blog post about the decision and the reasoning behind it. diff --git a/docs/source/getting-started/index.rst b/docs/source/getting-started/index.rst deleted file mode 100644 index 96e5f2958..000000000 --- a/docs/source/getting-started/index.rst +++ /dev/null @@ -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 \ No newline at end of file diff --git a/docs/source/howto/export_environment.rst b/docs/source/howto/export_environment.rst index 4aa87f980..c61010aa6 100644 --- a/docs/source/howto/export_environment.rst +++ b/docs/source/howto/export_environment.rst @@ -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. diff --git a/docs/source/howto/index.rst b/docs/source/howto/index.rst deleted file mode 100644 index 12ce3595c..000000000 --- a/docs/source/howto/index.rst +++ /dev/null @@ -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 diff --git a/docs/source/howto/languages.md b/docs/source/howto/languages.md new file mode 100644 index 000000000..7c7f3a285 --- /dev/null +++ b/docs/source/howto/languages.md @@ -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-\-\-\-\
+ +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: . + +### 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. diff --git a/docs/source/howto/languages.rst b/docs/source/howto/languages.rst deleted file mode 100644 index af51a6fdf..000000000 --- a/docs/source/howto/languages.rst +++ /dev/null @@ -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 `. 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 ` with :ref:`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 `_ as well -as Jupyter support for R with the `IRKernel `_. To set it up, -you need to create a ``runtime.txt`` file with the following format: - - r----
- -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` file to your repo. RStudio and IRKernel are -installed by default for all R versions. - -`packagemanager.posit.co `_ -will be used to provide much faster installations via `binary packages `_. -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 `_ 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 `_. -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 `_ -repository for some inspiration. diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 000000000..fbf1a3311 --- /dev/null +++ b/docs/source/index.md @@ -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 +``` + +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 +``` diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 09be2503f..000000000 --- a/docs/source/index.rst +++ /dev/null @@ -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 `_ -to build images on demand. - -Please report `Bugs `_, -`ask questions `_ or -`contribute to the project `_. - -.. 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 diff --git a/docs/source/install.rst b/docs/source/install.rst deleted file mode 100644 index be9c91b23..000000000 --- a/docs/source/install.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. _install: - -Installing ``repo2docker`` -========================== - -repo2docker requires Python 3.6 or above on Linux and macOS. See -:ref:`below ` for more information about Windows support. - -Prerequisite: Docker --------------------- - -Install `Docker `_ as it is required -to build Docker images. The -`Community Edition `_, -is available for free. - -Recent versions of Docker are recommended. -The latest version of Docker, ``18.03``, successfully builds repositories from -`binder-examples `_. -The `BinderHub `_ helm chart uses version -``17.11.0-ce-dind``. See the -`helm chart `_ -for more details. - -Optional: Mercurial -------------------- - -For `Mercurial `_ repositories, Mercurial and -`hg-evolve `_ 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 -`_. - -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 diff --git a/docs/source/specification.md b/docs/source/specification.md new file mode 100644 index 000000000..fb7cc40c9 --- /dev/null +++ b/docs/source/specification.md @@ -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. diff --git a/docs/source/specification.rst b/docs/source/specification.rst deleted file mode 100644 index bd635b231..000000000 --- a/docs/source/specification.rst +++ /dev/null @@ -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. diff --git a/docs/source/start.md b/docs/source/start.md new file mode 100644 index 000000000..6329a6ae4 --- /dev/null +++ b/docs/source/start.md @@ -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). diff --git a/docs/source/usage.rst b/docs/source/usage.rst deleted file mode 100644 index e89eb8ff6..000000000 --- a/docs/source/usage.rst +++ /dev/null @@ -1,140 +0,0 @@ -.. _usage: - -===================== -Using ``repo2docker`` -===================== - -.. note:: - - `Docker `_ **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 `_ from Zenodo or Figshare, -a `Handle `_ or DOI from a Dataverse installation, -a `SWHID`_ of a directory of a revision archived in the -`Software Heritage Archive `_, -or a path to a local directory. - -It then performs these steps: - -1. Inspects the repository for :ref:`configuration 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 `. -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 - -where ```` 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 `_ -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 ` 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 `. - - -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 diff --git a/docs/source/use/index.md b/docs/source/use/index.md new file mode 100644 index 000000000..a350f5051 --- /dev/null +++ b/docs/source/use/index.md @@ -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 +``` diff --git a/docs/source/use/repository.md b/docs/source/use/repository.md new file mode 100644 index 000000000..5f8354b78 --- /dev/null +++ b/docs/source/use/repository.md @@ -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 +``` + + +## 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). From d689bfee282a85d8ca101d4476a66230ab8b69ea Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 25 Jul 2025 22:42:15 +0000 Subject: [PATCH 02/12] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/configuration/actions.md | 2 +- docs/source/configuration/datascience.md | 4 ---- docs/source/configuration/index.md | 3 +-- docs/source/configuration/system.md | 3 --- docs/source/contribute/tasks.md | 2 -- docs/source/howto/languages.md | 5 +---- docs/source/use/index.md | 1 - docs/source/use/repository.md | 6 +++--- 8 files changed, 6 insertions(+), 20 deletions(-) diff --git a/docs/source/configuration/actions.md b/docs/source/configuration/actions.md index 8a25a319a..3e3177e12 100644 --- a/docs/source/configuration/actions.md +++ b/docs/source/configuration/actions.md @@ -30,4 +30,4 @@ 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. \ No newline at end of file +% TODO: Discuss runtime limits, best practices, etc. diff --git a/docs/source/configuration/datascience.md b/docs/source/configuration/datascience.md index 750b75714..fa5ecbbdf 100644 --- a/docs/source/configuration/datascience.md +++ b/docs/source/configuration/datascience.md @@ -1,6 +1,5 @@ # Configuration for datascience workflows - (environment-yml)= ## `environment.yml` - Install a conda environment @@ -30,7 +29,6 @@ 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) @@ -47,8 +45,6 @@ This is used to install R libraries pinned to a specific snapshot on 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 diff --git a/docs/source/configuration/index.md b/docs/source/configuration/index.md index e70edc08a..571a008ad 100644 --- a/docs/source/configuration/index.md +++ b/docs/source/configuration/index.md @@ -20,11 +20,10 @@ 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 -``` \ No newline at end of file +``` diff --git a/docs/source/configuration/system.md b/docs/source/configuration/system.md index dbb1ae243..f80fd9c5e 100644 --- a/docs/source/configuration/system.md +++ b/docs/source/configuration/system.md @@ -1,6 +1,5 @@ # System-wide configuration - (apt-txt)= ## `apt.txt` - Install packages with apt-get @@ -11,8 +10,6 @@ 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 diff --git a/docs/source/contribute/tasks.md b/docs/source/contribute/tasks.md index 30be8c662..bdaf83107 100644 --- a/docs/source/contribute/tasks.md +++ b/docs/source/contribute/tasks.md @@ -39,7 +39,6 @@ Mercurial and hg-evolve), one can use the environment variable Some of the tests have non-python requirements for your development machine. They are: - `git-lfs` must be installed ([instructions](https://github.com/git-lfs/git-lfs)). It need not be activated -- there is no need to run the `git lfs install` command. It just needs to be available to the test suite. - - If your test failure messages include "`git-lfs filter-process: git-lfs: command not found`", this step should address the problem. - Minimum Docker Image size of 128GB is required. If you are not running docker on a linux OS, you may need to expand the runtime image size for your installation. See Docker's instructions for [macOS](https://docs.docker.com/docker-for-mac/space/) or [Windows 10](https://docs.docker.com/docker-for-windows/#resources) for more information. @@ -69,7 +68,6 @@ See the subsections below for more detailed instructions. ### Conda dependencies 1. There are two files related to conda dependencies. Edit as needed. - - `repo2docker/buildpacks/conda/environment.yml` Contains list of packages to install in Python3 conda environments, diff --git a/docs/source/howto/languages.md b/docs/source/howto/languages.md index 7c7f3a285..66560b941 100644 --- a/docs/source/howto/languages.md +++ b/docs/source/howto/languages.md @@ -74,7 +74,6 @@ Python itself releases a new version every year now, and repo2docker will follow 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 @@ -90,7 +89,7 @@ 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 +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. @@ -105,7 +104,6 @@ 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 @@ -122,7 +120,6 @@ 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 diff --git a/docs/source/use/index.md b/docs/source/use/index.md index a350f5051..31b5ca7d5 100644 --- a/docs/source/use/index.md +++ b/docs/source/use/index.md @@ -34,7 +34,6 @@ repository ../howto/breaking_changes ``` - ```{toctree} :maxdepth: 2 :caption: Learn about repo2docker diff --git a/docs/source/use/repository.md b/docs/source/use/repository.md index 5f8354b78..048de524e 100644 --- a/docs/source/use/repository.md +++ b/docs/source/use/repository.md @@ -6,8 +6,8 @@ `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. +- 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. @@ -16,6 +16,7 @@ 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: @@ -35,7 +36,6 @@ In each case you can build from these repository sources like so: jupyter-repo2docker ``` - ## Supported version control systems These Version Control Systems are supported by `repo2docker`. From b976d17cfd892a3a6c3d3526a333eae5406d93a3 Mon Sep 17 00:00:00 2001 From: choldgraf Date: Wed, 30 Jul 2025 18:11:13 -0700 Subject: [PATCH 03/12] Update documentation with new content --- docs/source/_static/images/whentouse.svg | 4 + docs/source/conf.py | 1 + docs/source/howto/breaking_changes.md | 6 +- docs/source/index.md | 34 ++++++-- docs/source/use/action.md | 7 ++ docs/source/use/community-image.md | 53 +++++++++++++ docs/source/use/extend-community-image.md | 85 ++++++++++++++++++++ docs/source/use/index.md | 8 +- docs/source/use/pathways.md | 96 +++++++++++++++++++++++ 9 files changed, 282 insertions(+), 12 deletions(-) create mode 100644 docs/source/_static/images/whentouse.svg create mode 100644 docs/source/use/action.md create mode 100644 docs/source/use/community-image.md create mode 100644 docs/source/use/extend-community-image.md create mode 100644 docs/source/use/pathways.md diff --git a/docs/source/_static/images/whentouse.svg b/docs/source/_static/images/whentouse.svg new file mode 100644 index 000000000..59fdc066f --- /dev/null +++ b/docs/source/_static/images/whentouse.svg @@ -0,0 +1,4 @@ + + +eyJ2ZXJzaW9uIjoiMSIsImVuY29kaW5nIjoiYnN0cmluZyIsImNvbXByZXNzZWQiOnRydWUsImVuY29kZWQiOiJ4nO2bWVfbRlx1MDAxNMff8yl03MeCMvvSNyBpwpKEhFx1MDAxNFx1MDAxMkpPjrBcdTAwMDdbxZZcdTAwMWNJZuvJd+9cdTAwMWRcdTAwMDHaLMsyOJQ0XHUwMDE4kmNGI2uWO//7u3fG/zxznE5yOTad35yOueh6Q79cdTAwMTd5551cdTAwMTVbfmai2Fx1MDAwZlx1MDAwM7hE0r/jcFx1MDAxMnXTmoMkXHUwMDE5x789f57f4XbD0fVdZmhGJkhiqPcn/O04/6T/w1x1MDAxNb9n7117w/jO9lx1MDAxYVx1MDAxNlx1MDAxZk9cdTAwMGZeXHUwMDFkXHUwMDBlxfEh61x1MDAxZaS3ppVuXHUwMDFik5iLJC+9gFwijFx1MDAxNXNcdKFcdTAwMDRTyjRGTGWXL+Hyqlx1MDAxMtjVlHBENcVKU5FdPvd7yVx1MDAwMKowhV1J4SVcdTAwMTlcIpRRybMqXHUwMDAz4/dcdTAwMDdcdNTRKCvzgv7QtiUviZMoPDVcdTAwMWLhMIxsXHUwMDFif8HG/uTNPPa6p/0onFx1MDAwNL2sTlx1MDAxMnlBPPZcIlx1MDAxOJK83ok/XHUwMDFj7iWX6ad3ulFcdTAwMTjHq1x1MDAwMy/pXHUwMDBlOpUnXHUwMDFk3DScVMqze+NcdTAwMTCGP79cdTAwMGJcdTAwMWXdXHUwMDFmXHUwMDA0JraDj7PScOx1/cSOXHUwMDExRnlfbDvHm710nv7KW1x1MDAxNnkjs2knKphcZodZsVx1MDAxZvSMnYPO8cZh6XFB7+ZxpeqxMb10xjSWmKHCVFx1MDAxNGyK0mrp2zBI7UspTKUmMr/Nj1+AXSXpp554w9jkQ27b8LJqc0W7K9ieXHUwMDEwW6/Wvm57Qm6cqk/ImGRr38/6U7I/L4rC80525dtK0+f+vbu7XHUwMDEz4v7WV8U/XHUwMDA3+2Nf72xw1O5zb97lMzBcdTAwMTn3vOuOYsmpJEhJpXk+XHUwMDE0Qz84rY73MOye1oxNuobgmcR1/oiNM1x1MDAxOYP1XHUwMDE4b+SMPD9I4J/pXHUwMDFkXHUwMDA1/sjrXHUwMDFi51dcdTAwMDds5Fx1MDAxNN7FXHUwMDA1I1xyg2TPv7KtLkygLf3dXHUwMDFi+UNrT7z0qLWh31x1MDAwZlKLhrkwUac4vYlcdTAwMGZKkVVIwnF+tVx1MDAxYl43Jpo2uzDy+37gXHI/3qsj3iRcdD+Y+LorSTQxxbE0r29XPnZcdH9WmOuKbqHXq3z9gkd0ncgv5/FaNzh9NWilW0ryVHaIXHUwMDEyjFGsZVm3uKYuI1x1MDAxOEtBmaSc5LJ2q1tEa1dcblx1MDAwNYKFMVx1MDAxNojhfDoy3WLMVVx1MDAxNEnJMFx1MDAxN5RzrZ9krFHGTHtcdTAwMTljRIJH0VxuXHUwMDE1XHL6RsWomCq9VTFcIsBRYVWYz0euYq+vXHUwMDA2X7snn99cdTAwMWbqMX45uPR0tE9Hy1MxJJkurrxFVYxdL/5cdTAwMTe2Vlx1MDAwNKZn6qWKu7DMXHUwMDA0TklAMalcdTAwMTeTrqE5Sb6DcDW0fTnq5Mnk05U+e/P2nJDJltnFgytx0UadXHUwMDA0iFx1MDAxM1x1MDAxN1xuK8U001x1MDAxMuVOOVx1MDAxNSfBkEuEZlxmWfFiitWIXHUwMDEzdZFcdTAwMTBCIY1cdTAwMTRBNF+wT0x107K5YnTSXozAW2iwb1W00Vx1MDAxYi3CZCZRUXBcdTAwMWXAU2LpWlx1MDAxNO9cYv5G+Fx1MDAxN13/41Dt7O2/29Wfj1x1MDAxZj9R3VeL8PV6hqBnNFx0wFx1MDAwZY6CXHUwMDFjRZyURJbBUd9JjFx1MDAxNmn8ctRpXHUwMDE1f7nE3d3BhVx1MDAxY+mteG3yYedqu13MR1x1MDAxMHOpRDYgwFxcXHUwMDEyko9UKk9cZiFcdTAwMTdzJIlcdTAwMDLpUUjkizqL+YhyXHRCXGJcdTAwMTOCQN0wqYn5WF72pE91+tRvr0+EXG74laxWoMRMgVx1MDAwMq7lXHUwMDFjSFkvPea7XHUwMDA31TQq1D2Ur4VCXHUwMDExWdT4OyhcdTAwMTS9XuSRXHUwMDE5h6SXYodjueNxx3fzXHUwMDFivVx1MDAxYz1qJujKvJVcdTAwMDVJSORCOM5BdDhcdTAwMDYgqlx1MDAwNHNcbnNcdTAwMTdTiMFcdTAwMTDnQnA9nYSigrmccsY11NKM50tcItMjgoUrMVx1MDAwMqdNkKZIyPwh8/XJgMhR/HPp06i9PmFcdTAwMDVcdTAwMTNHqMZ1OSmlZlx1MDAxM1x1MDAxNDghYOScf+8tT7Ver2CkYfT7l+39l95cdTAwMWIhklx1MDAwZpv0w8d+sE9cdTAwMTfPXHUwMDFjyeJcbmmrXCLj0K+2/c9CXHUwMDBiUbG5KHv/10pt7ZlcdTAwMTZ//7unV0r+cVPjM/TiZFx1MDAwM6DHT2CUdm1cdTAwMGanbCTxomRcdTAwMWRcZstcdTAwMGb6cC2frtus9maLXHUwMDE0diqi3YlcdTAwMWS9VdBcbsmo4lx1MDAxYahcdTAwMWQjXHUwMDBlf1x1MDAxNGr1vbGdq2LRiX+RN604XG7YRdA7wCGkXHUwMDE1cDzOc6PpILpcdTAwMWOu2JQ41kxcIsanRiHzZVx1MDAxZFx1MDAxM/Tm97A52VXoIXIpYFx1MDAxOUWKK2GTtlhMd5C7RFx1MDAwM59JaLWdKc7bdFx1MDAxOLpEiWaIXCLMbcqf8GKHYWBx8WWf39DndF7XrJpcdTAwMGaMNyUkMFwixWtV2TfD4/A8XSMlf5O2fM/0b1f5tCFtxntj0/W9Yc1cdTAwMDOr11x1MDAxYZxVvVx1MDAwZbSBZ42lXHUwMDBiQTnQXHUwMDE4+Fx1MDAwNE10Ltmpr8JIcFx1MDAxN8J+qTiDWZGF8DFcdTAwMGLuKbgzXGLuJShcbtxfSF1mzlxuzPrJOzV7p1dcdTAwMGKE90RrXCI0qss1Yj0712hcdTAwMDMljWBcdTAwMGXv4J9K7Zh2XCKgWupeKDpcbiOINidxXHUwMDEyjo6C7lx1MDAwMIzExM8jM1xuz6D6UVx1MDAxMEDPTa+WS1x1MDAwYrnTpXDpyO/1irm3MprOw8IqrTb2y6l2aznk2lx1MDAxY800kyuVLlx1MDAwN4ohXFxcdTAwMTNcdTAwMDJzW9k+pVxuuUhcbqooXHUwMDExXG5Nb0JQrV3KJJc2XHUwMDEzLlx1MDAxNM8tLZdcdTAwMDJBXYBihFx1MDAxNTxcdTAwMDFcXIF4UoZmZVx1MDAxOC/ArZozmFx1MDAxZVxcXHUwMDFiWEvKqqWZMiApYWpBIFx1MDAxZY5cXE/38Fr/pffCe3f8aW97XHUwMDFjcPz28KEydMsl11k2f/+7V6dcdTAwMTfLQ6BrcyaujK5cdTAwMThJ227BKKFEgv3dnV0xtcGIoExcYlxyLFxcZlfGXHUwMDA00oJcdTAwMGKpQHwgZFx1MDAxNlx1MDAwZkavq9hVlGJCXHUwMDAwMIGvhVJ37aPFVSm0XHUwMDEyQOFcYkGcKFdKI4DLL/J/hdX6pd9cdTAwMDZWlVx1MDAxMi5TXHUwMDFj2d1ronhlXHUwMDFmikFcdTAwMTTR6J1cdTAwMTBylbDbUFx1MDAxMmFcZitu2jvJRXahfkpvtL/I0Vx1MDAxZZgqWK9cdTAwMDVcZiiAaiFhVc3zQqBcdTAwMDFRKitsmz9cdTAwMWVQ3UhcdTAwMTnOOfZi4/TA4G3DY7s70oPCy2Ja8jHQ6lx1MDAxY1x1MDAxNKzS6l06t1x1MDAxY2ZtzpQ3MavCXHUwMDE2WbHdXlx1MDAwNl6FXHUwMDEwpyxcbpzxOZvT1J7401oyiVx1MDAwNIRPXHUwMDA011x1MDAwNbBcdTAwMDJcdTAwMWWClU2uMCpcdTAwMTjBT9TarFx1MDAxM9FcdTAwMDIyoVx1MDAwNJZcdTAwMDQmaIpPO+nJgdkyXHUwMDAx5GF/lrhhPY9a5aXeXl/T/Hj35UHPuzq7XHUwMDFhvP7w5kek1lLtaeuei60z18y8z/t+2Np8vKVAdNB0zlx1MDAxOJVcYlx1MDAwMVUjUpONbIlzoCacgZfTTGChysi6XHUwMDEwzrVcItbWWFx1MDAwZTE6YoVcdTAwMTdReUCY9bFVglx1MDAxNVx1MDAwML+M5UpcdTAwMTK8Ulx1MDAxZVx1MDAwMy2LL9JcdTAwMDTmPzS11i/9XHUwMDE21FxuXHUwMDBiXHUwMDFlwiRcdTAwMDaRXHUwMDFlk8BCsuKgXHUwMDE4ReBcdTAwMWGbjieAkbraXHUwMDFlSWeUI1x1MDAwZVxik3/CU4b1tmXzPdJcIuSqYE0jpWVcdTAwMWS5zj7NqZGdX8ru4pC+N7e+hZ45nlx1MDAxM/uj8dBEK0cwuWD4J35cdTAwMTfemcRcdE+aT3c/MLfOwcEqt1Y657To23KwtflcYlojtsKihjUoiFx1MDAwMoWFiDQ3+5szlXOxlWtcdTAwMTdpXGZ6QCl4IVlHrVx1MDAxMkPAS5H9lYyByDxpRKNGxO0lQnBe/s5FLlx1MDAxMEBcdTAwMDOzXHUwMDE0gllcdTAwMWZcdFwi/oCJ1nfJ3unm1lx1MDAxNTnf38Bn/qfN7fdfjvWPeESgVHt12rbnMuusXHUwMDA1M/fzXHUwMDFlXHUwMDAxs9osJLZpLUpcdTAwMTGxXHUwMDA3XHUwMDA19D2wVVNcIlx1MDAxNcWKUoFgXHUwMDFjSsdcdTAwMDRcdTAwMTbcNW9Frq3PQlTIlWKCp5Otrcm1clx1MDAxOIKrlcowXHUwMDE0wVX/b89cdTAwMDbUXHUwMDBiQFx1MDAxYnDFzCVcblxclOZcdTAwMTSULpe6m5NcdTAwMDHcXHUwMDFl7MjBNVx1MDAxN71cZlxcMXZtLl+DI1OEkZrtwKeE61x1MDAxY5eUtHdJXFxDrFx1MDAwNtNVdy6AzXRJilxiqe153EdcYq1bkzhJN8mdOFx1MDAxY5mjXHUwMDAwiiPvUYHqXHUwMDFjXHUwMDAwrIJq21x1MDAwZS2HTnXvvTo4/+Nd0P97jaNcdTAwMTdX+96Atfo6ooSFS0AzuaA28KeVXHUwMDAzrLD0qVx1MDAwYt5IXHUwMDEzoCBwmGz6XHUwMDA0K2ZcdTAwMWPWPlx1MDAxNXbXXGZ0XHUwMDFjnG5dzKpcXFx1MDAwZVxiXGYuXGJRLVx1MDAxMVtcdTAwMDRPf8Yj9mdcdTAwMGJEsEJI+5Wtulx1MDAwMJaomSdcdTAwMDEwJchurd3lXGLrXHUwMDFjMdBa4nt9Q/lgYFx1MDAwMsdcdTAwMGJ6ziA8d5LQmZRPgdeqgVx1MDAxMq5cIpxohlx1MDAwNbVfnpWlSv/ZXHUwMDE59tZdWVhcdTAwMDee3WBqx1x1MDAxYo/3XHUwMDEymIJcZss6Z745X59eJb+cpC9cdTAwMWJcdTAwMTGkKtK5Pk1cdTAwMGa3fXv27V9cdTAwMWZkQ/4ifQ==2. Use upstream maintainedimage + packages4. Use Dockerfile1. Use communitymaintained image3. Use repo2docker filesmore customchanges/removalsneededChange base decisionsmade by repo2dockerNeed a simpler,specificset of packagesJust need someextra packagesWhen and how to use repo2docker \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index dec065cb4..d4b2479d2 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -22,6 +22,7 @@ "sphinxcontrib.autoprogram", "sphinxext.opengraph", "sphinxext.rediraffe", + "sphinx_design", ] root_doc = "index" source_suffix = [".md", ".rst"] diff --git a/docs/source/howto/breaking_changes.md b/docs/source/howto/breaking_changes.md index 80ab1ed09..c51e4d686 100644 --- a/docs/source/howto/breaking_changes.md +++ b/docs/source/howto/breaking_changes.md @@ -6,13 +6,13 @@ Repo2docker occasionally has to make breaking changes in how repositories are bu The base image used by repo2docker was [upgraded from Ubuntu 18.04 to Ubuntu 22.04](https://github.com/jupyterhub/repo2docker/pull/1287) in version 2023.10.0 due to Ubuntu 18.04 going out of support. -This is unlikely to affect you unless you are using {ref}`apt.txt `. +This is unlikely to affect you unless you are using {ref}`apt.txt `. -{ref}`apt.txt ` installs packages from the official Ubuntu package repositories, and is intrinsically tied to the Ubuntu version. +{ref}`apt.txt ` installs packages from the official Ubuntu package repositories, and is intrinsically tied to the Ubuntu version. Many packages will be available in both Ubuntu 18.04 and Ubuntu 22.04, however some may be renamed (for example if multiple incompatible versions are available). Some packages may be removed, or may not be compatible with the previous version. -In this case you should see if your packages can be installed using a {ref}`Conda environment.yml file ` using either the default [conda-forge channel](https://conda-forge.org/feedstock-outputs/) or in one of the many [third-party channels](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/channels.html). +In this case you should see if your packages can be installed using a {ref}`Conda environment.yml file ` using either the default [conda-forge channel](https://conda-forge.org/feedstock-outputs/) or in one of the many [third-party channels](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/channels.html). Alternatively you can try installing the packages from source, using a {ref}`postBuild ` script. diff --git a/docs/source/index.md b/docs/source/index.md index fbf1a3311..a79112da0 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,17 +1,37 @@ # Welcome to `repo2docker`'s documentation -`repo2docker` lets you **build, run, and push Docker images for data science from source code repositories**. +`repo2docker` lets you **reproducibly build, run, and deploy user environment 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. +are pushed to a Docker registry. It is the tool used by [BinderHub](https://binderhub.readthedocs.io) to build images on demand. -`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. +::::{grid} +:::{grid-item-card} 🔧 Build reproducible data science environments from repositories +Build a reproducible data science environment as a Docker image and execute code interactively. Use many [configuration files](#config-files) to control language, tools, and setup instructions. +::: +:::{grid-item-card} 🚀 Deploy environments in JupyterHub or Binder +Push environment images to a Docker registry for re-use in data science environment services like [JupyterHub](https://jupyterhub.readthedocs.io) or [a Binder instance](https://mybinder.org), or for other communities to build upon your base environment. +::: +:::{grid-item-card} ☁️ Host repositories in many providers +Host repositories in a provider like GitHub, an open science repository like [Zenodo](https://zenodo.org) or [Figshare](https://figshare.com), a hosted data platform like a [Dataverse installation](https://dataverse.org/), an archive like the +[Software Heritage Archive](https://archive.softwareheritage.org). +::: +:::: + +## What is a user image and why would I build one with `repo2docker`? + +A **user image** contains the entire software environment that a user may access from an interactive data science session. For example, it might contain many **programming languages**, **software for data analysis**, or even **contenet files and datasets** available to anybody that accesses that environment. User images are built with [Docker](https://www.docker.com/), a standard open source tool for defining, building, and deploying images. + +Many data science platforms and services like [JupyterHub](https://jupyterhub.readthedocs.io) and [Binder](https://mybinder.org) launch interactive data science sessions **with a user image attached**, meaning that the user gains access to whatever is in the image. In short, this allows somebody to define and build the user image one time, in a way that users can reproducibly re-use many times. + +Dockerfiles are the standard way that Docker images are defined[^use-dockerfile]. +However, **building images with Dockerfiles takes expertise and time** that is outside the scope of a data scientist or researcher. `repo2docker` makes this workflow more accessible by using community-standard configuration files for computational reproducibility to build user images. + +In short, `repo2docker` is a tool to reproducibly build, run, and deploy these user environment Docker images for data science from source code repositories. + +[^use-dockerfile]: That said, you can still use a Dockerfile if you really want to! ## How `repo2docker` works diff --git a/docs/source/use/action.md b/docs/source/use/action.md new file mode 100644 index 000000000..2e2d81900 --- /dev/null +++ b/docs/source/use/action.md @@ -0,0 +1,7 @@ +(github-action)= +# Use GitHub Actions to build environment images + +The [`repo2docker` GitHub Action](https://github.com/jupyterhub/repo2docker-action) allows you to use `repo2docker` in your GitHub CI/CD to build environment images and push them to a registry. It is a useful way to automate building and pushing images to reduce deployment toil. + +See [the `repo2docker` GitHub Action README](https://github.com/jupyterhub/repo2docker-action) for documentation about how to use this tool. + diff --git a/docs/source/use/community-image.md b/docs/source/use/community-image.md new file mode 100644 index 000000000..e24c7b7be --- /dev/null +++ b/docs/source/use/community-image.md @@ -0,0 +1,53 @@ +# Use a community-maintained image in a JupyterHub + +The simplest way to deploy environment images to a JupyterHub or BinderHub is to *find and re-use a pre-existing image maintained by a community*. In this case, you won't have to maintain anything - you'll simply use a community's image and contribute upstream if you wish. + +Here are some steps to follow. + +## First, find a community-maintained image for your workflow + +Many communities define their own user envionment images for re-use. Here are a few to look into. + +1. [jupyter docker-stacks](https://jupyter-docker-stacks.readthedocs.io/) has a number of user images for general data science workflows. +2. [pangeo docker-stacks](https://github.com/pangeo-data/pangeo-docker-images) has images for geospatial workflows in the cloud +3. [rocker](https://rocker-project.org/) has images meant for reproducibility with the R computing language. + +For example, the [Jupyter Docker Stacks images](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html#core-stacks) define images for several core datascience workflows. Each one points to a **hosted version of the image** on an image repository (such as [quay.io](https://quay.io)). + +## Pick a tag for the image + +Tags are a way to checkpoint an image so that you know exactly what is inside. They are similar to released versions of software. Tags will be listed in the image provider used by the community. For example: + +[Here's the list of tags for the `docker-stacks-foundation` image](https://quay.io/repository/jupyter/docker-stacks-foundation?tab=tags). + +:::{admonition} Don't use the `latest` tag +:class: warning +`latest` is a special tag for "the latest tag to be released". This is generally a bad idea when using environment images for your interactive data science sessions. Here are a few reasons why: + +- The environment may regularly change without warning as new versions of the image are released. +- The `JUPYTER_IMAGE` environment variable will not be useful because it's a generic `latest` variable. +- If you use tools that _themselves_ use Docker, you might have different images on your interactive environment vs. the images the tools use, because they haven't all updated at once. + +Instead, we recommend periodically manually updating the tag you use over time. +::: + +## Configure JupyterHub to use the tag + +Once you have an image and a tag, you can configure your JupyterHub to use it. + +Here's sample configuration if you're using the [Zero to JupyterHub for Kubernetes distribution](https://z2jh.jupyter.org). + +```yaml +singleuser: + image: + name: pangeo/pangeo-notebook + tag: 2023.04.15 +``` + +Here's sample configuration if you're using the [Dockerspawner for JupyterHub spawner](https://jupyterhub-dockerspawner.readthedocs.io/en/latest/). + +```python +c.DockerSpawner.image = 'pangeo/pangeo-notebook:2023.04.15' +``` + +When you re-deploy your JupyterHub application, it should now spawn user environments from the image you've configured. \ No newline at end of file diff --git a/docs/source/use/extend-community-image.md b/docs/source/use/extend-community-image.md new file mode 100644 index 000000000..9a1b14b13 --- /dev/null +++ b/docs/source/use/extend-community-image.md @@ -0,0 +1,85 @@ +# Extend a community image with your own packages + +If [using a community image alone](./community-image.md) doesn't provide the environment you need, you might get away with just installing one or two extra things on top of it. + +To do this, you should define a `Dockerfile` that "inherits" the community image, and "extend" it to add a few extra things. + +[Here's a repository that demonstrates how to do this using the `repo2docker` github action](https://github.com/2i2c-org/example-inherit-from-community-image). Below is a summary of the most important parts. + +An [`environment.yml` file](https://github.com/2i2c-org/example-inherit-from-community-image/blob/main/environment.yml) defines **only the extra things to install** in addition to the upstream image. + +```{code-block} +:caption: environment.yml +channels: + - conda-forge + +dependencies: + - jupyterhub-singleuser>=3.0,<4.0 + + # Everyone wants to use nbgitpuller for everything, so let's do that + - nbgitpuller=1.1.* + # Install packages from pip + - pip + - pip: + - otter-grader +``` + +A repository `Dockerfile` inherits from the upstream image. For example, the following inherits the scipy-notebook image with the `2023-05-01` tag, and copies + +```{code-block} Dockerfile +:caption: Dockerfile +FROM jupyter/scipy-notebook:2023-05-01 +COPY environment.yml /tmp/environment.yml +RUN mamba env update --prefix ${CONDA_DIR} --file /tmp/environment.yml +COPY image-tests image-tests +RUN ls +``` + +A [github workflow](https://github.com/2i2c-org/example-inherit-from-community-image/blob/main/.github/workflows/build.yaml) uses the [`repo2docker` GitHub action](#github-action) to build and push a Docker image using repo2docker. Here's an example of what the GitHub workflow looks like: + +````{dropdown} Example GitHub workflow code +```{code-block} yaml +:caption: .github/workflows/build.yaml +name: Build and push container image + +on: + push: + branches: + - main + +jobs: + build-and-push: + runs-on: ubuntu-latest + steps: + + # For biggish images, github actions runs out of disk space. + # So we cleanup some unwanted things in the disk image, and reclaim that space for our docker use + # https://github.com/actions/virtual-environments/issues/2606#issuecomment-772683150 + # and https://github.com/easimon/maximize-build-space/blob/b4d02c14493a9653fe7af06cc89ca5298071c66e/action.yml#L104 + # This gives us a total of about 52G of free space, which should be enough for now + - name: cleanup disk space + run: | + sudo rm -rf /usr/local/lib/android /usr/share/dotnet /opt/ghc + df -h + + - name: Checkout files in repo + uses: actions/checkout@main + + - name: Build and push the image to quay.io + uses: jupyterhub/repo2docker-action@master + with: + # Make sure username & password/token pair matches your registry credentials + DOCKER_USERNAME: ${{ secrets.QUAY_USERNAME }} + DOCKER_PASSWORD: ${{ secrets.QUAY_PASSWORD }} + DOCKER_REGISTRY: "quay.io" + # Disable pushing a 'latest' tag, as this often just causes confusion + LATEST_TAG_OFF: true + # + # Uncomment and modify the following line with your image name, otherwise no push will happen + IMAGE_NAME: "yuvipanda/example-inherit-from-community-image" + + # Lets us monitor disks getting full as images get bigger over time + - name: Show how much disk space is left + run: df -h +``` +```` \ No newline at end of file diff --git a/docs/source/use/index.md b/docs/source/use/index.md index 31b5ca7d5..7f8a953e0 100644 --- a/docs/source/use/index.md +++ b/docs/source/use/index.md @@ -7,8 +7,9 @@ Information about configuring your repository to work with repo2docker, and controlling elements of the built environment using configuration files. ```{toctree} -:caption: Configuration basics +:caption: Image building basics :maxdepth: 1 +pathways ../configuration/index repository ../cli @@ -27,10 +28,13 @@ repository ```{toctree} :maxdepth: 1 -:caption: Deploy into production +:caption: Deploy images into production ../howto/deploy +./community-image +./extend-community-image ../howto/jupyterhub_images +./action ../howto/breaking_changes ``` diff --git a/docs/source/use/pathways.md b/docs/source/use/pathways.md new file mode 100644 index 000000000..8e1d2c475 --- /dev/null +++ b/docs/source/use/pathways.md @@ -0,0 +1,96 @@ +# Four ways to use `repo2docker` images in a JupyterHub + +Many users of `repo2docker` primarily wish to define the environment for a Binder or a JupyterHub. Here are four ways to accomplish this, from least-to-most work. + +```{figure} ../_static/images/whentouse.svg +A decision tree for the recommended way to get your reproducible user environment using `repo2docker` or a community image built with `repo2docker`. +``` + +## 1. Use a community maintained image + +The simplest thing to do is check whether another community already maintains and offers an image that you can simply re-use. This reduces the burden on you to keep the image up-to-date, and gives you an opportunity to collaborate and make contributions rather than building something yourself from scratch. + +See [](./community-maintained.md) for a brief how-to on using a community maintained image. + +::::{grid} 2 +:::{grid-item-card} Benefits +- A community of experts maintains the image with you! +- Don’t struggle alone with your problems, drag others along! +- Good choices (base image, how python is installed, etc) made on your behalf +- Updates happen without you needing to do much +::: +:::{grid-item-card} Drawbacks +- Might have lots of stuff you don’t need +- Large image sizes, slower pulling +- Might get you 98% of the way there, but that ain’t 100% +- Architectural choices made might not fit your use case +- Updates are not on your schedule +::: +:::: + + +## 2. Inherit from a community maintained image and add a few extras + +Sometimes a community-maintained environment image has **almost** what you need, but there are a few extra packages you'd like to install yourself. In this case, it's easiest to **inherit and extend the community image**. + +This is not the same thing as forking the repository for the community image, modifying it, and re-building it from scratch. It's similar to depending on an upstream piece of software and then building upon it in your own tool. + +::::{grid} 2 +:::{grid-item-card} Benefits of inheriting and adding to community images +- 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 +::: +:::{grid-item-card} Drawbacks of inheriting and adding to community images +- 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 +::: +:::: + +See [](./extend-community-image.md) for a how-to guide. + +## 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). +Check out the other sections under "Image building basics" for more useful how-tos. + +::::{grid} 2 +:::{grid-item-card} Benefits +- Works well with mybinder.org +- No need to learn Dockerfile syntax +- Use language specific, well understood file formats +- Only get whatever packages you want +- Good defaults chosen by the community +::: +:::{grid-item-card} Drawbacks community-maintained images +- Build time is slower +- Images may be bigger +- Might not support 100% of what you want, and at some point you might have to take the ramp-off to a Dockerfile +::: +:::: + +## 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. + +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. + +[Here's an example repository that uses a `Dockerfile` to build with repo2docker]. + +::::{grid} 2 +:::{grid-item-card} Benefits of community-maintained images +- 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 + +::: +:::{grid-item-card} Drawbacks of community-maintained images +- 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 +::: +:::: \ No newline at end of file From 94029669a88b482b158249badbc9b049b7438fd8 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 31 Jul 2025 01:12:08 +0000 Subject: [PATCH 04/12] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/index.md | 1 - docs/source/use/action.md | 2 +- docs/source/use/community-image.md | 4 +-- docs/source/use/extend-community-image.md | 2 +- docs/source/use/pathways.md | 36 +++++++++++++---------- 5 files changed, 24 insertions(+), 21 deletions(-) diff --git a/docs/source/index.md b/docs/source/index.md index a79112da0..cedb33ed5 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -6,7 +6,6 @@ constructed image of the repository, or as a means of building images that are pushed to a Docker registry. It is the tool used by [BinderHub](https://binderhub.readthedocs.io) to build images on demand. - ::::{grid} :::{grid-item-card} 🔧 Build reproducible data science environments from repositories Build a reproducible data science environment as a Docker image and execute code interactively. Use many [configuration files](#config-files) to control language, tools, and setup instructions. diff --git a/docs/source/use/action.md b/docs/source/use/action.md index 2e2d81900..ec2df5649 100644 --- a/docs/source/use/action.md +++ b/docs/source/use/action.md @@ -1,7 +1,7 @@ (github-action)= + # Use GitHub Actions to build environment images The [`repo2docker` GitHub Action](https://github.com/jupyterhub/repo2docker-action) allows you to use `repo2docker` in your GitHub CI/CD to build environment images and push them to a registry. It is a useful way to automate building and pushing images to reduce deployment toil. See [the `repo2docker` GitHub Action README](https://github.com/jupyterhub/repo2docker-action) for documentation about how to use this tool. - diff --git a/docs/source/use/community-image.md b/docs/source/use/community-image.md index e24c7b7be..cfe89469d 100644 --- a/docs/source/use/community-image.md +++ b/docs/source/use/community-image.md @@ -1,6 +1,6 @@ # Use a community-maintained image in a JupyterHub -The simplest way to deploy environment images to a JupyterHub or BinderHub is to *find and re-use a pre-existing image maintained by a community*. In this case, you won't have to maintain anything - you'll simply use a community's image and contribute upstream if you wish. +The simplest way to deploy environment images to a JupyterHub or BinderHub is to _find and re-use a pre-existing image maintained by a community_. In this case, you won't have to maintain anything - you'll simply use a community's image and contribute upstream if you wish. Here are some steps to follow. @@ -50,4 +50,4 @@ Here's sample configuration if you're using the [Dockerspawner for JupyterHub sp c.DockerSpawner.image = 'pangeo/pangeo-notebook:2023.04.15' ``` -When you re-deploy your JupyterHub application, it should now spawn user environments from the image you've configured. \ No newline at end of file +When you re-deploy your JupyterHub application, it should now spawn user environments from the image you've configured. diff --git a/docs/source/use/extend-community-image.md b/docs/source/use/extend-community-image.md index 9a1b14b13..22f5a7831 100644 --- a/docs/source/use/extend-community-image.md +++ b/docs/source/use/extend-community-image.md @@ -82,4 +82,4 @@ jobs: - name: Show how much disk space is left run: df -h ``` -```` \ No newline at end of file +```` diff --git a/docs/source/use/pathways.md b/docs/source/use/pathways.md index 8e1d2c475..65f963ba2 100644 --- a/docs/source/use/pathways.md +++ b/docs/source/use/pathways.md @@ -14,20 +14,20 @@ See [](./community-maintained.md) for a brief how-to on using a community mainta ::::{grid} 2 :::{grid-item-card} Benefits + - A community of experts maintains the image with you! - Don’t struggle alone with your problems, drag others along! - Good choices (base image, how python is installed, etc) made on your behalf - Updates happen without you needing to do much -::: -:::{grid-item-card} Drawbacks + ::: + :::{grid-item-card} Drawbacks - Might have lots of stuff you don’t need - Large image sizes, slower pulling - Might get you 98% of the way there, but that ain’t 100% - Architectural choices made might not fit your use case - Updates are not on your schedule -::: -:::: - + ::: + :::: ## 2. Inherit from a community maintained image and add a few extras @@ -37,41 +37,43 @@ This is not the same thing as forking the repository for the community image, mo ::::{grid} 2 :::{grid-item-card} Benefits of inheriting and adding to community images + - 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 -::: -:::{grid-item-card} Drawbacks of inheriting and adding to community images + ::: + :::{grid-item-card} Drawbacks of inheriting and adding to community images - 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 -::: -:::: + ::: + :::: See [](./extend-community-image.md) for a how-to guide. ## 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). +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). Check out the other sections under "Image building basics" for more useful how-tos. ::::{grid} 2 :::{grid-item-card} Benefits + - Works well with mybinder.org - No need to learn Dockerfile syntax - Use language specific, well understood file formats - Only get whatever packages you want - Good defaults chosen by the community -::: -:::{grid-item-card} Drawbacks community-maintained images + ::: + :::{grid-item-card} Drawbacks community-maintained images - Build time is slower - Images may be bigger - Might not support 100% of what you want, and at some point you might have to take the ramp-off to a Dockerfile -::: -:::: + ::: + :::: ## 4. Use a full fledged custom Dockerfile @@ -83,14 +85,16 @@ This is for advanced users only that know what they're doing - full guidance on ::::{grid} 2 :::{grid-item-card} Benefits of community-maintained images + - 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 ::: :::{grid-item-card} Drawbacks of community-maintained images + - 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 -::: -:::: \ No newline at end of file + ::: + :::: From eeb8a1cc53a0dec714e534ec1de012beebe74efc Mon Sep 17 00:00:00 2001 From: choldgraf Date: Wed, 30 Jul 2025 18:13:45 -0700 Subject: [PATCH 05/12] Sphinx design --- docs/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/requirements.txt b/docs/requirements.txt index 534bac560..2e0c7627c 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,6 +2,7 @@ myst-parser<4 pydata-sphinx-theme sphinx-autobuild sphinx-copybutton +sphinx-design sphinxcontrib-autoprogram>=0.1.7 sphinxext-opengraph sphinxext-rediraffe From 732a6478cba82f3599b0ea18e663df5c7fae8929 Mon Sep 17 00:00:00 2001 From: choldgraf Date: Thu, 31 Jul 2025 15:32:36 -0700 Subject: [PATCH 06/12] Address comments --- docs/source/architecture.md | 22 ++++---- docs/source/changelog.md | 14 ++--- docs/source/cli.md | 12 ++--- docs/source/conf.py | 8 ++- docs/source/configuration/actions.md | 20 ++++--- docs/source/configuration/datascience.md | 59 -------------------- docs/source/configuration/development.md | 15 ++---- docs/source/configuration/index.md | 5 +- docs/source/configuration/research.md | 66 +++++++++++++++++++++++ docs/source/configuration/system.md | 36 ++++++------- docs/source/contribute/contributing.md | 2 +- docs/source/contribute/tasks.md | 2 +- docs/source/design.md | 4 +- docs/source/faq.md | 12 ++--- docs/source/howto/export_environment.rst | 10 ++-- docs/source/use/community-image.md | 6 +-- docs/source/use/extend-community-image.md | 2 +- docs/source/use/pathways.md | 2 +- 18 files changed, 150 insertions(+), 147 deletions(-) delete mode 100644 docs/source/configuration/datascience.md create mode 100644 docs/source/configuration/research.md diff --git a/docs/source/architecture.md b/docs/source/architecture.md index 2d14daf36..915e5cd3e 100644 --- a/docs/source/architecture.md +++ b/docs/source/architecture.md @@ -20,11 +20,11 @@ with explicit **versions** is all that is needed. In repo2docker, a Buildpack does the following things: 1. **Detect** if it can handle a given repository -2. **Build** a base language environment in the docker image -3. **Copy** the contents of the repository into the docker image -4. **Assemble** a specific environment in the docker image based on repository contents -5. **Push** the built docker image to a specific docker registry (optional) -6. **Run** the build docker image as a docker container (optional) +2. **Build** a base language environment in the Docker image +3. **Copy** the contents of the repository into the Docker image +4. **Assemble** a specific environment in the Docker image based on repository contents +5. **Push** the built Docker image to a specific Docker registry (optional) +6. **Run** the build Docker image as a Docker container (optional) ### Detect @@ -56,9 +56,9 @@ repositories built with the same buildpack. For example, in `CondaBuildPack`, the base environment consists of installing [miniconda](https://conda.io/miniconda.html) and basic notebook packages (from `repo2docker/buildpacks/conda/environment.yml`). This is going to be the same for most repositories built with `CondaBuildPack`, so we want to use -[docker layer caching](https://thenewstack.io/understanding-the-docker-cache-for-faster-builds/) as +[Docker layer caching](https://thenewstack.io/understanding-the-docker-cache-for-faster-builds/) as much as possible for performance reasons. Next time a repository is built with `CondaBuildPack`, -we can skip straight to the **copy** step (since the base environment docker image _layers_ have +we can skip straight to the **copy** step (since the base environment Docker image _layers_ have already been built and cached). The `get_build_scripts` and `get_build_script_files` methods are primarily used for this. @@ -91,20 +91,20 @@ This usually means installing required libraries specified in a format native to Most of this work is done in `get_assemble_scripts` method. It can return arbitrary bash script lines that can be run as different users, and has access to the repository contents (unlike -`get_build_scripts`). The docker image layers produced by this usually can not be cached, +`get_build_scripts`). The Docker image layers produced by this usually can not be cached, so less restrictions apply to this than to `get_build_scripts`. -At the end of the assemble step, the docker image is ready to be used in various ways! +At the end of the assemble step, the Docker image is ready to be used in various ways! ### Push -Optionally, repo2docker can **push** a built image to a [docker registry](https://docs.docker.com/registry/), +Optionally, repo2docker can **push** a built image to a [Docker registry](https://docs.docker.com/registry/), if you specify the `--push` flag. ### Run Optionally, repo2docker can **run** the built image and allow the user to access the Jupyter Notebook -running inside by default. This is also done as a convenience only (since you can do the same with `docker run` +running inside by default. This is also done as a convenience only (since you can do the same with `Docker run` after using repo2docker only to build), and implemented in `Repo2Docker.run`. It is activated by default unless the `--no-run` commandline flag is passed. diff --git a/docs/source/changelog.md b/docs/source/changelog.md index 58cef1cff..73852c92b 100644 --- a/docs/source/changelog.md +++ b/docs/source/changelog.md @@ -134,7 +134,7 @@ - pre-commit update to fix ci [#1238](https://github.com/jupyterhub/repo2docker/pull/1238) ([@minrk](https://github.com/minrk)) - Upgrade to mamba 1.1 and enable rich SAT error messages [#1232](https://github.com/jupyterhub/repo2docker/pull/1232) ([@SylvainCorlay](https://github.com/SylvainCorlay)) - Upgrade to mamba 1.0 [#1213](https://github.com/jupyterhub/repo2docker/pull/1213) ([@SylvainCorlay](https://github.com/SylvainCorlay)) -- docker image: update alpine to 3.16 [#1212](https://github.com/jupyterhub/repo2docker/pull/1212) ([@consideRatio](https://github.com/consideRatio)) +- Docker image: update alpine to 3.16 [#1212](https://github.com/jupyterhub/repo2docker/pull/1212) ([@consideRatio](https://github.com/consideRatio)) - reconcile CLI/config priority [#1211](https://github.com/jupyterhub/repo2docker/pull/1211) ([@minrk](https://github.com/minrk)) - pipfile: pass --clear flag, and do it separetely to not be ignored [#1208](https://github.com/jupyterhub/repo2docker/pull/1208) ([@consideRatio](https://github.com/consideRatio)) - run submodule test over https [#1204](https://github.com/jupyterhub/repo2docker/pull/1204) ([@minrk](https://github.com/minrk)) @@ -299,12 +299,12 @@ The repo2docker container image has moved to [quay.io/jupyterhub/repo2docker](ht - Workaround docker-py dependency's failure to import six {pr}`1066:` by {user}`consideratio` - fix: add chardet, a not explicitly declared dependency {pr}`1064` by {user}`johnhoman` -- Add build-base to build stage of docker image {pr}`1051` by {user}`yuvipanda` +- Add build-base to build stage of Docker image {pr}`1051` by {user}`yuvipanda` - Fix regression in hydroshare introduced after moving to requests {pr}`1034` by {user}`MridulS` ### Other merged PRs -- Update README quay.io URL, Add docker latest tag {pr}`1075` by {user}`manics` +- Update README quay.io URL, Add Docker latest tag {pr}`1075` by {user}`manics` - GitHub workflow build and push to Docker hub {pr}`1071` by {user}`manics` - Rename master branch to main {pr}`1068` by {user}`manics` - Remove Pipfile & Pipfile.lock {pr}`1054` by {user}`yuvipanda` @@ -343,7 +343,7 @@ The repo2docker container image has moved to [quay.io/jupyterhub/repo2docker](ht ### Other merged PRs - Cleanup install_requires including duplicates {pr}`1020` by {user}`manics` -- bump docker action version {pr}`1018` by {user}`minrk` +- bump Docker action version {pr}`1018` by {user}`minrk` - bump python in circleci test {pr}`1013` by {user}`minrk` - Investigating the missing logs {pr}`1008` by {user}`betatim` - Experiment with different install mechanism to get code coverage stats again {pr}`982` by {user}`betatim` @@ -376,7 +376,7 @@ The repo2docker container image has moved to [quay.io/jupyterhub/repo2docker](ht - chmod start script from repo2docker-entrypoint {pr}`886` by {user}`danlester` - pypi jupyter-offlinenotebook==0.1.0 {pr}`880` by {user}`manics` - Add support for Julia 1.4.1 {pr}`878` by {user}`davidanthoff` -- Change --env option to work like docker's {pr}`874` by {user}`hwine` +- Change --env option to work like Docker's {pr}`874` by {user}`hwine` - Add support for Julia 1.4.0 {pr}`870` by {user}`davidanthoff` - Update server proxy and rsession proxy {pr}`869` by {user}`betatim` - Use miniforge instead of miniconda to get conda {pr}`859` by {user}`yuvipanda` @@ -549,7 +549,7 @@ Release date: 2019-02-21 ### New features -- Add additional metadata to docker images about how they were built {pr}`500` by +- Add additional metadata to Docker images about how they were built {pr}`500` by {user}`jrbourbeau`. - Allow users to install global NPM packages: {pr}`573` by {user}`GladysNalvarte`. - Add documentation on switching the user interface presented by a @@ -579,7 +579,7 @@ Release date: 2019-02-21 - Fix quoting issue in `GIT_CREDENTIAL_ENV` environment variable by {user}`minrk` in {pr}`572`. - Change to using the first 8 characters of each Git commit, not the last 8, - to tag each built docker image of repo2docker itself. {user}`minrk` in {pr}`562`. + to tag each built Docker image of repo2docker itself. {user}`minrk` in {pr}`562`. - Allow users to select the Julia when using a `requirements.txt` by {user}`yuvipanda` in {pr}`557`. - Set `JULIA_DEPOT_PATH` to install packages outside the home directory by diff --git a/docs/source/cli.md b/docs/source/cli.md index 274c905be..0da611374 100644 --- a/docs/source/cli.md +++ b/docs/source/cli.md @@ -17,7 +17,7 @@ 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). +[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: @@ -32,7 +32,7 @@ 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: +To debug the container image being built, pass the `--debug` parameter: > ```bash > jupyter-repo2docker --debug https://github.com/norvig/pytudes @@ -40,10 +40,8 @@ To debug the docker image being built, pass the `--debug` parameter: 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. +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 @@ -76,7 +74,7 @@ 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. +[](#config-start) configuration file. (command-line-api)= diff --git a/docs/source/conf.py b/docs/source/conf.py index d4b2479d2..d2b45faf7 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -41,6 +41,7 @@ # myst_enable_extensions = [ "colon_fence", + "substitution", ] @@ -59,8 +60,11 @@ from repo2docker.buildpacks.conda import CondaBuildPack -default_python = CondaBuildPack.major_pythons["3"] - +default_python = f"`Python {CondaBuildPack.major_pythons['3']}`" +myst_substitutions = { + "default_python": default_python, + "default_python_version": default_python, +} rst_prolog = f""" .. |default_python| replace:: **Python {default_python}** .. |default_python_version| replace:: {default_python} diff --git a/docs/source/configuration/actions.md b/docs/source/configuration/actions.md index 3e3177e12..0f2aa483d 100644 --- a/docs/source/configuration/actions.md +++ b/docs/source/configuration/actions.md @@ -1,11 +1,19 @@ # Configuration files for post-build actions +These files control behavior that happens *after* the image is initially built (AKA, after the packages and languages have been installed). It's useful if you need to ensure files are in a particular place, or certain commands are run when a new session launches. + +:::{note} +After building the image, all actions are run as a user named `jovyan`. +You do not have root permissions on the machine! + +See [the Jupyter Docker Stacks definition of `jovyan`](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/faq.html#who-is-jovyan) for more details. +::: + (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`. +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. @@ -14,20 +22,18 @@ 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)= +(config-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. +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`. +If you only need to run things once during the build phase use [](#postBuild). % TODO: Discuss runtime limits, best practices, etc. diff --git a/docs/source/configuration/datascience.md b/docs/source/configuration/datascience.md deleted file mode 100644 index fa5ecbbdf..000000000 --- a/docs/source/configuration/datascience.md +++ /dev/null @@ -1,59 +0,0 @@ -# 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---
`, 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. diff --git a/docs/source/configuration/development.md b/docs/source/configuration/development.md index e661635b3..1084303c1 100644 --- a/docs/source/configuration/development.md +++ b/docs/source/configuration/development.md @@ -10,9 +10,9 @@ environment Python dependencies. When using `pipenv`, you end up with 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 +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 +distinguish packages and development packages and that `repo2docker` will install both kinds. (requirements-txt)= @@ -29,14 +29,5 @@ on GitHub shows a typical requirements file. ## `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 +`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. diff --git a/docs/source/configuration/index.md b/docs/source/configuration/index.md index 571a008ad..c64189d8c 100644 --- a/docs/source/configuration/index.md +++ b/docs/source/configuration/index.md @@ -7,9 +7,6 @@ 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 @@ -22,7 +19,7 @@ can be found on this page (and to the right). ```{toctree} :maxdepth: 2 -./datascience +./research ./development ./system ./actions diff --git a/docs/source/configuration/research.md b/docs/source/configuration/research.md new file mode 100644 index 000000000..04e0dae9d --- /dev/null +++ b/docs/source/configuration/research.md @@ -0,0 +1,66 @@ +# Configuration for research and data science 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. 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`. + +:::{warning} +If you include a Python version in a `runtime.txt` file in addition to your +`environment.yml`, your `runtime.txt` will be ignored. +::: + +(install-r)= + +## `install.R` - Install packages with R/RStudio + +This is used to install R libraries pinned to a specific snapshot on +[Posit Package Manager](https://packagemanager.posit.co/). +For an example `install.R` file, visit our [example `install.R` file](https://github.com/binder-examples/r/blob/HEAD/install.R). + +To set the date of the snapshot, or to specify a specific version of R, add a [runtime.txt](#runtime-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())`. + +To define the date of the package manager snapshot, add a line to [`runtime.txt`](#runtime-txt) like so: + +``` +r---
+``` + +Where `YYYY-MM-DD` is a snapshot of [CRAN](https://cran.r-project.org/) that will be used for your R installation. +If `runtime.txt` isn't provided in this case, the most recent date on CRAN will be used. + +(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. + +:::{admonition} `REQUIRE` files are no longer supported +The recommended way of installing a Julia environment is to use a `Project.toml` file. +::: \ No newline at end of file diff --git a/docs/source/configuration/system.md b/docs/source/configuration/system.md index f80fd9c5e..a3b0fb81f 100644 --- a/docs/source/configuration/system.md +++ b/docs/source/configuration/system.md @@ -14,25 +14,27 @@ We use `apt.txt`, for example, to install LaTeX in our ## `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). +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} +:::{warning} `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). +(when using [`environment.yml`](#environment-yml) for conda or [`Project.toml`](#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. +### Set the Python version + +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). -Have `r----
` 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). +### Set the R version + +Add the line `r----
` 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). + +`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)= @@ -43,8 +45,8 @@ Specify packages to be installed by the [nix package manager](https://github.com 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. +`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 @@ -58,13 +60,11 @@ To see an example repository visit ## `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. +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. +With `Dockerfile`s, a regular Docker build will be performed. -:::{note} +:::{warning} If a Dockerfile is present, all other configuration files will be ignored. ::: diff --git a/docs/source/contribute/contributing.md b/docs/source/contribute/contributing.md index 8e26bcda2..d68ea5d4b 100644 --- a/docs/source/contribute/contributing.md +++ b/docs/source/contribute/contributing.md @@ -150,7 +150,7 @@ according to black's style guide. You can activate it with `pre-commit install`. As part of our continuous integration tests we will check that code is formatted properly and the tests will fail if this is not the case. -### Verify that docker is installed and running +### Verify that Docker is installed and running If you do not already have [Docker](https://www.docker.com/), you should be able to download and install it for your operating system using the links from the diff --git a/docs/source/contribute/tasks.md b/docs/source/contribute/tasks.md index bdaf83107..070abf6d7 100644 --- a/docs/source/contribute/tasks.md +++ b/docs/source/contribute/tasks.md @@ -41,7 +41,7 @@ Some of the tests have non-python requirements for your development machine. The - `git-lfs` must be installed ([instructions](https://github.com/git-lfs/git-lfs)). It need not be activated -- there is no need to run the `git lfs install` command. It just needs to be available to the test suite. - If your test failure messages include "`git-lfs filter-process: git-lfs: command not found`", this step should address the problem. -- Minimum Docker Image size of 128GB is required. If you are not running docker on a linux OS, you may need to expand the runtime image size for your installation. See Docker's instructions for [macOS](https://docs.docker.com/docker-for-mac/space/) or [Windows 10](https://docs.docker.com/docker-for-windows/#resources) for more information. +- Minimum Docker Image size of 128GB is required. If you are not running Docker on a linux OS, you may need to expand the runtime image size for your installation. See Docker's instructions for [macOS](https://docs.docker.com/docker-for-mac/space/) or [Windows 10](https://docs.docker.com/docker-for-windows/#resources) for more information. - If your test failure messages include "`No space left on device: '/home/...`", this step should address the problem. ## Update and Freeze BuildPack Dependencies diff --git a/docs/source/design.md b/docs/source/design.md index 6077621d7..6d7cdcad7 100644 --- a/docs/source/design.md +++ b/docs/source/design.md @@ -43,7 +43,7 @@ This provides a few advantages: Many ingredients go into making an image from a repository: -1. version of the base docker image +1. version of the base Docker image 1. version of `repo2docker` itself 1. versions of the libraries installed by the repository @@ -62,7 +62,7 @@ explicitly in your dependencies. `repo2docker` should do one thing, and do it well. This one thing is: -> Given a repository, deterministically build a docker image from +> Given a repository, deterministically build a Docker image from > it. There's also some convenience code (to run the built image) for users, but diff --git a/docs/source/faq.md b/docs/source/faq.md index 4f48a2752..9579aebc4 100644 --- a/docs/source/faq.md +++ b/docs/source/faq.md @@ -10,7 +10,7 @@ and have found an answer, send a PR to add it here! 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 +Docker image used by `repo2docker`. A typical error message will look like the following: ``` @@ -44,13 +44,13 @@ a subsequent build step.) 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 +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 +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. +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! @@ -108,4 +108,4 @@ our own new tool. In the case of repo2docker, we spent time integrating with a p 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. +read our [blog post about why we built repo2docker](https://github.com/yuvipanda/words/blob/fd096dd49d87e624acd8bdf6d13c0cecb930bb3f/content/post/why-not-s2i.md). diff --git a/docs/source/howto/export_environment.rst b/docs/source/howto/export_environment.rst index c61010aa6..42505737b 100644 --- a/docs/source/howto/export_environment.rst +++ b/docs/source/howto/export_environment.rst @@ -1,8 +1,8 @@ .. _export-environment: -============================================================================ -Export your environment to a ``environment.yml`` that works with repo2docker -============================================================================ +============================================================================= +Export your environment to an ``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. @@ -16,7 +16,7 @@ This is the most robust for reproducibility, but it does bake in potential platform-specific packages, so you can only use an exported environment on the same platform. -``repo2docker`` uses a linux based image as the starting point for every docker +``repo2docker`` uses a linux based image as the starting point for every Docker image it creates. However a lot of people use OSX or Windows as their day to day operating system. This means that the ``environment.yml`` created by a strict export will not work with error messages saying that certain packages can not @@ -48,7 +48,7 @@ Strict version export Follow this procedure to create a strict export of your environment that will work with ``repo2docker`` and sites like `mybinder.org `_. -We will launch a terminal inside a basic docker image, install the packages +We will launch a terminal inside a basic Docker image, install the packages you need and then perform a strict export of the environment. #. install repo2docker on your computer by following :ref:`install` diff --git a/docs/source/use/community-image.md b/docs/source/use/community-image.md index cfe89469d..6c4a6a4b7 100644 --- a/docs/source/use/community-image.md +++ b/docs/source/use/community-image.md @@ -8,8 +8,8 @@ Here are some steps to follow. Many communities define their own user envionment images for re-use. Here are a few to look into. -1. [jupyter docker-stacks](https://jupyter-docker-stacks.readthedocs.io/) has a number of user images for general data science workflows. -2. [pangeo docker-stacks](https://github.com/pangeo-data/pangeo-docker-images) has images for geospatial workflows in the cloud +1. [jupyter Docker-stacks](https://jupyter-docker-stacks.readthedocs.io/) has a number of user images for general data science workflows. +2. [pangeo Docker-stacks](https://github.com/pangeo-data/pangeo-docker-images) has images for geospatial workflows in the cloud 3. [rocker](https://rocker-project.org/) has images meant for reproducibility with the R computing language. For example, the [Jupyter Docker Stacks images](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html#core-stacks) define images for several core datascience workflows. Each one points to a **hosted version of the image** on an image repository (such as [quay.io](https://quay.io)). @@ -18,7 +18,7 @@ For example, the [Jupyter Docker Stacks images](https://jupyter-docker-stacks.re Tags are a way to checkpoint an image so that you know exactly what is inside. They are similar to released versions of software. Tags will be listed in the image provider used by the community. For example: -[Here's the list of tags for the `docker-stacks-foundation` image](https://quay.io/repository/jupyter/docker-stacks-foundation?tab=tags). +[Here's the list of tags for the `Docker-stacks-foundation` image](https://quay.io/repository/jupyter/docker-stacks-foundation?tab=tags). :::{admonition} Don't use the `latest` tag :class: warning diff --git a/docs/source/use/extend-community-image.md b/docs/source/use/extend-community-image.md index 22f5a7831..078c9d4c9 100644 --- a/docs/source/use/extend-community-image.md +++ b/docs/source/use/extend-community-image.md @@ -53,7 +53,7 @@ jobs: steps: # For biggish images, github actions runs out of disk space. - # So we cleanup some unwanted things in the disk image, and reclaim that space for our docker use + # So we cleanup some unwanted things in the disk image, and reclaim that space for our Docker use # https://github.com/actions/virtual-environments/issues/2606#issuecomment-772683150 # and https://github.com/easimon/maximize-build-space/blob/b4d02c14493a9653fe7af06cc89ca5298071c66e/action.yml#L104 # This gives us a total of about 52G of free space, which should be enough for now diff --git a/docs/source/use/pathways.md b/docs/source/use/pathways.md index 65f963ba2..9dfed4eb9 100644 --- a/docs/source/use/pathways.md +++ b/docs/source/use/pathways.md @@ -10,7 +10,7 @@ A decision tree for the recommended way to get your reproducible user environmen The simplest thing to do is check whether another community already maintains and offers an image that you can simply re-use. This reduces the burden on you to keep the image up-to-date, and gives you an opportunity to collaborate and make contributions rather than building something yourself from scratch. -See [](./community-maintained.md) for a brief how-to on using a community maintained image. +See [](./community-image.md) for a brief how-to on using a community maintained image. ::::{grid} 2 :::{grid-item-card} Benefits From d3a8e3030cd6a76e8ecde5d50a40f70f7e69d92b Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 31 Jul 2025 22:32:49 +0000 Subject: [PATCH 07/12] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/conf.py | 4 ++-- docs/source/configuration/actions.md | 2 +- docs/source/configuration/research.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index d2b45faf7..590400c75 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -62,8 +62,8 @@ default_python = f"`Python {CondaBuildPack.major_pythons['3']}`" myst_substitutions = { - "default_python": default_python, - "default_python_version": default_python, + "default_python": default_python, + "default_python_version": default_python, } rst_prolog = f""" .. |default_python| replace:: **Python {default_python}** diff --git a/docs/source/configuration/actions.md b/docs/source/configuration/actions.md index 0f2aa483d..a441893da 100644 --- a/docs/source/configuration/actions.md +++ b/docs/source/configuration/actions.md @@ -1,6 +1,6 @@ # Configuration files for post-build actions -These files control behavior that happens *after* the image is initially built (AKA, after the packages and languages have been installed). It's useful if you need to ensure files are in a particular place, or certain commands are run when a new session launches. +These files control behavior that happens _after_ the image is initially built (AKA, after the packages and languages have been installed). It's useful if you need to ensure files are in a particular place, or certain commands are run when a new session launches. :::{note} After building the image, all actions are run as a user named `jovyan`. diff --git a/docs/source/configuration/research.md b/docs/source/configuration/research.md index 04e0dae9d..0df6d4a85 100644 --- a/docs/source/configuration/research.md +++ b/docs/source/configuration/research.md @@ -63,4 +63,4 @@ of the Julia packages that are installed. :::{admonition} `REQUIRE` files are no longer supported The recommended way of installing a Julia environment is to use a `Project.toml` file. -::: \ No newline at end of file +::: From aae1c6cdbf6ec480c02a6fd7121bec98fe5e4433 Mon Sep 17 00:00:00 2001 From: choldgraf Date: Fri, 1 Aug 2025 09:53:05 -0700 Subject: [PATCH 08/12] Address comments --- docs/source/_static/images/whentouse.svg | 4 ++-- docs/source/architecture.md | 4 +--- docs/source/changelog.md | 2 +- docs/source/contribute/tasks.md | 2 +- docs/source/faq.md | 15 +++++---------- docs/source/howto/export_environment.rst | 9 +++------ docs/source/index.md | 12 ++++++------ docs/source/use/community-image.md | 10 +++++----- docs/source/use/extend-community-image.md | 10 ++++++++-- docs/source/use/pathways.md | 1 + docs/source/use/repository.md | 4 ++-- 11 files changed, 35 insertions(+), 38 deletions(-) diff --git a/docs/source/_static/images/whentouse.svg b/docs/source/_static/images/whentouse.svg index 59fdc066f..089e25011 100644 --- a/docs/source/_static/images/whentouse.svg +++ b/docs/source/_static/images/whentouse.svg @@ -1,4 +1,4 @@ -eyJ2ZXJzaW9uIjoiMSIsImVuY29kaW5nIjoiYnN0cmluZyIsImNvbXByZXNzZWQiOnRydWUsImVuY29kZWQiOiJ4nO2bWVfbRlx1MDAxNMff8yl03MeCMvvSNyBpwpKEhFx1MDAxNFx1MDAxMkpPjrBcdTAwMDdbxZZcdTAwMWNJZuvJd+9cdTAwMWRcdTAwMDHaLMsyOJQ0XHUwMDE4kmNGI2uWO//7u3fG/zxznE5yOTad35yOueh6Q79cdTAwMTd5551cdTAwMTVbfmai2Fx1MDAwZlx1MDAwM7hE0r/jcFx1MDAxMnXTmoMkXHUwMDE5x789f57f4XbD0fVdZmhGJkhiqPcn/O04/6T/w1x1MDAxNb9n7117w/jO9lx1MDAxYVx1MDAxNlx1MDAxZk9cdTAwMGZeXHUwMDFkXHUwMDBlxfEh61x1MDAxZaS3ppVuXHUwMDFik5iLJC+9gFwijFx1MDAxNXNcdKFcdTAwMDRTyjRGTGWXL+Hyqlx1MDAxMtjVlHBENcVKU5FdPvd7yVx1MDAwMKowhV1J4SVcdTAwMTlcIpRRybMqXHUwMDAz4/dcdTAwMDdcdNTRKCvzgv7QtiUviZMoPDVcdTAwMWLhMIxsXHUwMDFif8HG/uTNPPa6p/0onFx1MDAwNL2sTlx1MDAxMnlBPPZcIlx1MDAxOJK83ok/XHUwMDFj7iWX6ad3ulFcdTAwMTjHq1x1MDAwMy/pXHUwMDBlOpUnXHUwMDFk3DScVMqze+NcdTAwMTCGP79cdTAwMGJcdTAwMWXdXHUwMDFmXHUwMDA0JraDj7PScOx1/cSOXHUwMDExRnlfbDvHm710nv7KW1x1MDAxNnkjs2knKphcZodZsVx1MDAxZvSMnYPO8cZh6XFB7+ZxpeqxMb10xjSWmKHCVFx1MDAxNGyK0mrp2zBI7UspTKUmMr/Nj1+AXSXpp554w9jkQ27b8LJqc0W7K9ieXHUwMDEwW6/Wvm57Qm6cqk/ImGRr38/6U7I/L4rC80525dtK0+f+vbu7XHUwMDEz4v7WV8U/XHUwMDA3+2Nf72xw1O5zb97lMzBcdTAwMTn3vOuOYsmpJEhJpXk+XHUwMDE0Qz84rY73MOye1oxNuobgmcR1/oiNM1x1MDAxOYP1XHUwMDE4b+SMPD9I4J/pXHUwMDFkXHUwMDA1/sjrXHUwMDFi51dcdTAwMDds5Fx1MDAxNN7FXHUwMDA1I1xyg2TPv7KtLkygLf3dXHUwMDFi+UNrT7z0qLWh31x1MDAwZlKLhrkwUac4vYlcdTAwMGZKkVVIwnF+tVx1MDAxYl43Jpo2uzDy+37gXHI/3qsj3iRcdD+Y+LorSTQxxbE0r29XPnZcdH9WmOuKbqHXq3z9gkd0ncgv5/FaNzh9NWilW0ryVHaIXHUwMDEyjFGsZVm3uKYuI1x1MDAxOEtBmaSc5LJ2q1tEa1dcblx1MDAwNYKFMVx1MDAxNojhfDoy3WLMVVx1MDAxNEnJMFx1MDAxN5RzrZ9krFHGTHtcdTAwMTljRIJH0VxuXHUwMDE1XHL6RsWomCq9VTFcIsBRYVWYz0euYq+vXHUwMDA2X7snn99cdTAwMWbqMX45uPR0tE9Hy1MxJJkurrxFVYxdL/5cdTAwMTe2Vlx1MDAwNKZn6qWKu7DMXHUwMDA0TklAMalcdTAwMTeTrqE5Sb6DcDW0fTnq5Mnk05U+e/P2nJDJltnFgytx0UadXHUwMDA0iFx1MDAxM1x1MDAxN1xuK8U001x1MDAxMuVOOVx1MDAxNSfBkEuEZlxmWfFiitWIXHUwMDEzdZFcdTAwMTBCIY1cdTAwMTRBNF+wT0x107K5YnTSXozAW2iwb1W00Vx1MDAxYi3CZCZRUXBcdTAwMWXAU2LpWlx1MDAxNO9cYv5G+Fx1MDAxN13/41Dt7O2/29Wfj1x1MDAxZj9R3VeL8PV6hqBnNFx0wFx1MDAwZY6CXHUwMDFjRZyURJbBUd9JjFx1MDAxNmn8ctRpXHUwMDE1f7nE3d3BhVx1MDAxY+mteG3yYedqu13MR1x1MDAxMHOpRDYgwFxcXHUwMDEyko9UKk9cZiFcdTAwMTdzJIlcdTAwMDLpUUjkizqL+YhyXHRCXGJcdTAwMTOCQN0wqYn5WF72pE91+tRvr0+EXG74laxWoMRMgVx1MDAwMq7lXHUwMDFjSFkvPea7XHUwMDA31TQq1D2Ur4VCXHUwMDExWdT4OyhcdTAwMTS9XuSRXHUwMDE5h6SXYodjueNxx3fzXHUwMDFivVx1MDAxYz1qJujKvJVcdTAwMDVJSORCOM5BdDhcdTAwMDYgqlx1MDAwNHNcbnNcdTAwMTdTiMFcdTAwMTDnQnA9nYSigrmccsY11NKM50tcItMjgoUrMVx1MDAwMqdNkKZIyPwh8/XJgMhR/HPp06i9PmFcdTAwMDVcdTAwMTNHqMZ1OSmlZlx1MDAxM1x1MDAxNDghYOScf+8tT7Ver2CkYfT7l+39l95cdTAwMWIhklx1MDAwZpv0w8d+sE9cdTAwMTfPXHUwMDFjyeJcbmmrXCLj0K+2/c9CXHUwMDBiUbG5KHv/10pt7ZlcdTAwMTZ//7unV0r+cVPjM/TiZFx1MDAwM6DHT2CUdm1cdTAwMGanbCTxomRcdTAwMWRcZstcdTAwMGb6cC2frtus9maLXHUwMDE0diqi3YlcdTAwMWS9VdBcbsmo4lx1MDAxYahcdTAwMWQjXHUwMDBlf1x1MDAxNGr1vbGdq2LRiX+RN604XG7YRdA7wCGkXHUwMDE1cDzOc6PpILpcdTAwMWOu2JQ41kxcIsanRiHzZVx1MDAxZFx1MDAxM/Tm97A52VXoIXIpYFx1MDAxOUWKK2GTtlhMd5C7RFx1MDAwM59JaLWdKc7bdFx1MDAxOLpEiWaIXCLMbcqf8GKHYWBx8WWf39DndF7XrJpcdTAwMGaMNyUkMFwixWtV2TfD4/A8XSMlf5O2fM/0b1f5tCFtxntj0/W9Yc1cdTAwMDOr11x1MDAxYZxVvVx1MDAwZbSBZ42lXHUwMDBiQTnQXHUwMDE4+Fx1MDAwNE10Ltmpr8JIcFx1MDAxN8J+qTiDWZGF8DFcdTAwMGLuKbgzXGLuJShcbtxfSF1mzlxuzPrJOzV7p1dcdTAwMGKE90RrXCI0qss1Yj0712hcdTAwMDMljWBcdTAwMGXv4J9K7Zh2XCKgWupeKDpcbiOINidxXHUwMDEyjo6C7lx1MDAwMIzExM8jM1xuz6D6UVx1MDAxMEDPTa+WS1x1MDAwYrnTpXDpyO/1irm3MprOw8IqrTb2y6l2aznk2lx1MDAxY800kyuVLlx1MDAwN4ohXFxcdTAwMTNcdTAwMDJzW9k+pVxuuUhcbqooXHUwMDExXG5Nb0JQrV3KJJc2XHUwMDEzLlx1MDAxNM8tLZdcdTAwMDJBXYBihFx1MDAxNTxcdTAwMDFcXIF4UoZmZVx1MDAxOC/ArZozmFx1MDAxZVxcXHUwMDFiWEvKqqWZMiApYWpBIFx1MDAxZY5cXE/38Fr/pffCe3f8aW97XHUwMDFjcPz28KEydMsl11k2f/+7V6dcdTAwMTfLQ6BrcyaujK5cdTAwMThJ227BKKFEgv3dnV0xtcGIoExcYlxyLFxcZlfGXHUwMDA00oJcdTAwMGKpQHwgZFx1MDAxNlx1MDAwZkavq9hVlGJCXHUwMDAwMIGvhVJ37aPFVSm0XHUwMDEyQOFcYkGcKFdKI4DLL/J/hdX6pd9cdTAwMDZWlVx1MDAxMi5TXHUwMDFj2d1ronhlXHUwMDFmikFcdTAwMTTR6J1cdTAwMTBylbDbUFx1MDAxMmFcZitu2jvJRXahfkpvtL/I0Vx1MDAxZZgqWK9cdTAwMDVcZiiAaiFhVc3zQqBcdTAwMDFRKitsmz9cdTAwMWVQ3UhcdTAwMTnOOfZi4/TA4G3DY7s70oPCy2Ja8jHQ6lx1MDAxY1x1MDAxNKzS6l06t1x1MDAxY2ZtzpQ3MavCXHUwMDE2WbHdXlx1MDAwNl6FXHUwMDEwpyxcbpzxOZvT1J7401oyiVx1MDAwNIRPXHUwMDA011x1MDAwNbBcdTAwMDJcdTAwMWWClU2uMCpcdTAwMTjBT9TarFx1MDAxM9FcdTAwMDIyoVx1MDAwNJZcdTAwMDQmaIpPO+nJgdkyXHUwMDAx5GF/lrhhPY9a5aXeXl/T/Hj35UHPuzq7XHUwMDFhvP7w5kek1lLtaeuei60z18y8z/t+2Np8vKVAdNB0zlx1MDAxOJVcYlx1MDAwMVUjUpONbIlzoCacgZfTTGChysi6XHUwMDEwzrVcItbWWFx1MDAwZTE6YoVcdTAwMTdReUCY9bFVglx1MDAxNVx1MDAwML+M5UpcdTAwMTK8Ulx1MDAxZVx1MDAwMy2LL9JcdTAwMDTmPzS11i/9XHUwMDE21FxuXHUwMDBiXHUwMDFlwiRcdTAwMDaRXHUwMDFlk8BCsuKgXHUwMDE4ReBcdTAwMWGbjieAkbraXHUwMDFlSWeUI1x1MDAwZVxik3/CU4b1tmXzPdJcIuSqYE0jpWVcdTAwMWS5zj7NqZGdX8ru4pC+N7e+hZ45nlx1MDAxM/uj8dBEK0cwuWD4J35cdTAwMTfemcRcdE+aT3c/MLfOwcEqt1Y657To23KwtflcYlojtsKihjUoiFx1MDAwMoWFiDQ3+5szlXOxlWtcdTAwMTdpXGZ6QCl4IVlHrVx1MDAxMkPAS5H9lYyByDxpRKNGxO0lQnBe/s5FLlx1MDAxMEBcdTAwMDOzXHUwMDE0gllcdTAwMWZcdFwi/oCJ1nfJ3unm1lx1MDAxNTnf38Bn/qfN7fdfjvWPeESgVHt12rbnMuusXHUwMDA1M/fzXHUwMDFlXHUwMDAxs9osJLZpLUpcdTAwMTGxXHUwMDA3XHUwMDA19D2wVVNcIlx1MDAxNcWKUoFgXHUwMDFjSsdcdTAwMDRcdTAwMTbcNW9Frq3PQlTIlWKCp5Otrcm1clx1MDAxOIKrlcowXHUwMDE0wVX/b89cdTAwMDbUXHUwMDBiQFx1MDAxYnDFzCVcblxclOZcdTAwMTSULpe6m5NcdTAwMDHcXHUwMDFl7MjBNVx1MDAxN71cZlxcMXZtLl+DI1OEkZrtwKeE61x1MDAxY5eUtHdJXFxDrFx1MDAwNtNVdy6AzXRJilxiqe153EdcYq1bkzhJN8mdOFx1MDAxY5mjXHUwMDAwiiPvUYHqXHUwMDFjXHUwMDAwrIJq21x1MDAwZS2HTnXvvTo4/+Nd0P97jaNcdTAwMTdX+96Atfo6ooSFS0AzuaA28KeVXHUwMDAzrLD0qVx1MDAwYt5IXHUwMDEzoCBwmGz6XHUwMDA0K2ZcdTAwMWPWPlx1MDAxNXbXXGZ0XHUwMDFjnG5dzKpcXFx1MDAwZVxiXGYuXGJRLVx1MDAxMVtcdTAwMDRPf8Yj9mdcdTAwMGJEsEJI+5Wtulx1MDAwMJaomSdcdTAwMDEwJchurd3lXGLrXHUwMDFjMdBa4nt9Q/lgYFx1MDAwMsdcdTAwMGJ6ziA8d5LQmZRPgdeqgVx1MDAxMq5cIpxohlx1MDAwNbVfnpWlSv/ZXHUwMDE59tZdWVhcdTAwMDee3WBqx1x1MDAxYo/3XHUwMDEymIJcZss6Z745X59eJb+cpC9cdTAwMWJcdTAwMTGkKtK5Pk1cdTAwMGa3fXv27V9cdTAwMWZkQ/4ifQ==2. Use upstream maintainedimage + packages4. Use Dockerfile1. Use communitymaintained image3. Use repo2docker filesmore customchanges/removalsneededChange base decisionsmade by repo2dockerNeed a simpler,specificset of packagesJust need someextra packagesWhen and how to use repo2docker \ No newline at end of file +eyJ2ZXJzaW9uIjoiMSIsImVuY29kaW5nIjoiYnN0cmluZyIsImNvbXByZXNzZWQiOnRydWUsImVuY29kZWQiOiJ4nO1cXGtT2zhcdTAwMTf+3l/hyX5535mNV/fLftlcdIFcdTAwMDKFXinQ7bLDmMRJXGaJndpcdTAwMGVcdTAwMDF2+t/3yEDs2Fx1MDAwZdhcdTAwMTBaulxydDogybF0dJ5HzzmS+OeFZTXiy7Hb+N1quFx1MDAxN1x1MDAxZGfodUNn2vjVlJ+7YeRcdTAwMDU+VJHk9yiYhJ2k5SCOx9Hvv/2WPmF3gtH1U+7QXHUwMDFkuX5cdTAwMWNBu7/gd8v6J/lcdTAwMWZqvK55tvWa8d2dXHUwMDE2XHUwMDE2XHUwMDFmz1x1MDAwZTc/XHUwMDBmxcln1jlMXHUwMDFlTVx1MDAxYd12JnYv4rT0XHUwMDAyijBW3NZcdTAwMTRcdTAwMTGNXHRcdTAwMTNcYolZ7SXUNlx1MDAwNaW2UJpRxTQlgpFZ9dTrxlx1MDAwM2jCXHSytVx1MDAxMEIyhZhQks9aXGZcXK8/iKGJRrMyx+9cdTAwMGZNT9KSKFx1MDAwZYMzt1x1MDAxZFxmg9D08Fx1MDAxN6wl7pC0kydO56xcdTAwMWZcdTAwMDZcdTAwMTO/O2tcdTAwMTOHjlx1MDAxZo2dXHUwMDEwXGaStut5w+FefJl8eqNcdTAwMTNcdTAwMDZR1Fx1MDAxYzhxZ9DIvenwpt8kVz57NlxuwPjpU/Dq/sB3I2N6PCtccsZOx4uNiTBKx2L6Od7uJrP0d9qz0Fx1MDAxObnbZpr8yXA4K/b8rmtmoHHS/jz3Or9787q55pHrdpP50lhihmg6UalHMYzzpW9cdTAwMDI/8S7MqWBYaZ6O24vWwa3i5GN7zjByU5ubTmxkXFwuXHUwMDFkzGTcda5cdTAwMWbBkjNk5l1wJGf1Q88/y3d9XHUwMDE4dM5K3pI4I4yf2NZ+5FqOXHUwMDA13j6a+GBWy1x1MDAxYjl9KPG7R77T7UJVz51aYPIzKI6sS4BM5Fx1MDAwZXuZyVx1MDAwZvx4z7syXHUwMDAzzVx1MDAxOMaUvnRG3tDMXHUwMDEzn3tva+j1/cRTYIhu2MiaLfZcdTAwMDB/s1x1MDAwNnEwTms78ImO57thcTqD0Ot7vjP8uLxROZM4+OBG1+OKw4mbtbK7dVx1MDAwYi9sXHUwMDEznlR8/bWMXHUwMDFh0FaTr13wkK5cdTAwMTF5PI1aXHUwMDFk/2xzUIlcdTAwMWEkXHUwMDA3aDOtXHRcdTAwMTGEa6HUXHUwMDFjN8BrJWOEXHUwMDEygjGWQlx1MDAxMlrgXHUwMDA2JqlNXHUwMDEwQphcdTAwMTAkXHUwMDExxaSEXHUwMDFjXHUwMDE4s1x1MDAxNUVSMsxcdTAwMDXlXFzrXHUwMDE1V9zJXHUwMDE1bnWuYERqirVCWe++pYpi6YwqMMWMKZiuZ0dcdTAwMTVsXHUwMDA2qklcdTAwMTRcdTAwMDcja900XHUwMDBmYTrdci7gtlx1MDAxMkxgWLo4UkzqetwwdHvxXHUwMDEzMEOVQSxcdTAwMDf6jow/Xenz12+mhExeue/w4EpcXFSBvoRFncOSr4T5ljr1hERcdTAwMTUoQmyJuKZcdTAwMWFWXHUwMDE1sGs6p7fIp0Tdi/yVLLhcdTAwMDfqvepQN3NcdTAwMDGerrLeeoN0rFx1MDAwYlJhhnRKJVx1MDAwNVmH01x1MDAxNs9cdTAwMDXpuLB8XHUwMDFl+SNcdTAwMDBYXHUwMDAysu71UrqM9f+JMF6v+8tBe1x1MDAxM1x1MDAxZl/izrvBhVx1MDAxY+lXUWvyYfdqp1pcZiCNypeYXG6uKFx1MDAwN5eYRztNXCJcdTAwMDSmtJScM8JYauFZXHUwMDEwwCQ0oZRpgTQti1x1MDAwMVhatlx1MDAwMntcdTAwMTnY+9XBTqiAf1x1MDAxMHCVoJ3jxWhHXHUwMDA0Zk8h/vzQTq/hXHUwMDEyuuOAdJPlXHUwMDEwgOP3vL5llsXoWVx1MDAwYv3KfV9cdTAwMGXKdfe9Opzuv/X7py2O1q9cdTAwMGWcXHUwMDAxqyTnuWS2XHUwMDEwXHUwMDA0c1D0SCqVi/QxwsImminMOaJUy6Kcx4wz2yxcdTAwMThSgPvh0lhcdTAwMWYjZXOKXHUwMDA1lrDsa4nq4d413z9cdTAwMTfuz2vE/lx1MDAwMDUuVEaXZ/S8YItwzzhcdTAwMDdeV1x1MDAxOcG/JNhLLlx1MDAxNcs6cV3YXHUwMDFmXHUwMDBlXFzfxMPWIJhacWBN5nFUXG57JWxFODgqXHUwMDE2XHUwMDE0wk4q51x1MDAxYX03XHUwMDE2qDyU5bBAu9V6e7DJd95yb1x1MDAxY269eeNNw1x1MDAwZnGltV5cdTAwMGJcdTAwMWKWcaVcdTAwMTSmjECcN89cdTAwMDKCKltwwWGl4Fx1MDAxMiORev1M2Uv4XHUwMDAwbJZcdTAwMTGlIfJcdTAwMTep/TNcdTAwMWOwXHUwMDAy/d2gv6pcdTAwMGV6xYUxNirA23QlXHUwMDEzVuVBz6hcdTAwMTKcPVxm9DdcdTAwMTWp12U8T223Q2ft02feP1x1MDAxOeJ+97jpnoZyNpw573PCMJg2ZjVfb366U0kgRVRcdTAwMTZcdTAwMTF1KWU9cKO5pJszXGZdp5uR34DSm0zc1ItcdTAwMDdWPHCPfNc/98LAN1x1MDAwNrC2LVx1MDAxZiz/Ryn5ZPr2XHUwMDFkg4tFY7RcdTAwMTZcdTAwMGbRunOEc5w0b9c6pHS3a+TcXCKnTaRccmzDXHUwMDE5MDrHmORcIlx1MDAxMFx1MDAwZaRP7mQlYDXEXHUwMDA0pYJRTFx1MDAxOCdpi5SVKIZ3gLqhmCtOUDqV93OUiyg8/lNx1DqqzlFcdTAwMTTMg1x1MDAxMOdlwlx1MDAwNFOaL51cdTAwMDUkQjGQXHUwMDEwiC2RpEpXvoyPrq+Ld63X59vki3yzSzq775zP/HM9jqKcZTywXHUwMDA2R41cdTAwMDMv3/e/Mj1E2e6i2c9//1raeqHHm6+Cr6efVlx1MDAxOODQieI2UIlcdTAwMTfDMN+ZLlx1MDAxNmY5dsJ4XHJcXMPz+1CX2vt2W3K7giZJKLMzMcNvXCJbMSEh0qDgNFx1MDAxMChcdTAwMTCRadV3xsalbEG5SS1SXHUwMDA1XHKxZvymxddZt1xcv5t2qtjhlqGZXHUwMDAx8GK+XHUwMDE2nsvW5fnIXHUwMDFknlx1MDAwNNOS2et5XHUwMDE3bnfP7d86YPGN29He2O14zrDkjfm6O2i03EUraDuBkS2JxJorolx1MDAwNUK5rC2nJidcdTAwMGJhoFx1MDAwNOlukFfUdlx1MDAxOGI3+FwiijBp8rZFXHUwMDE2pXWk3c9Im7g6bXJMXHUwMDAxXHUwMDAxVJTtz8h82S1pKq1cdTAwMTlFmD4kiTPXiVx1MDAwMrFcdTAwMDGHcP0gYrtcdTAwMTVffrBcZtV0b4w28rrd7GbJvHS6T4bk1VS208tcdM7WW/5GZ+1w9/j9x6smOT9jSO6UpGjKdFx1MDAxMFxiXHUwMDFkUMCcY0RcdMih1ELX0ZkkNlx1MDAxNVx1MDAxMPMymC/GSzI0SNtMXHUwMDEyqjVGXGbCMJl6SbrtwmwpzbZcZkZcdTAwMDTeUCtW+1x1MDAxOVx1MDAwMc1qJGhcdTAwMDBISmlJylx1MDAxME3RwmBccitMNDe76N9OXGKNOpung1x1MDAwMySba2jt6nCt31x1MDAxZWy8368thND3XHUwMDE3Qot93nw1XHUwMDBi7r5MKZRf5f+TeqTcUyrpXHUwMDExbVx1MDAwYqa5XHUwMDA0KYJcdM6sLVx0m0kqgUdBaUhoXCKB9FxudMa4XHJ+XHUwMDA2K1x1MDAxM3xcbsNcZpWw2UqP3ENfvMa+XHUwMDEyRlxuaUFKN5bwwvNcIsB5QiOe2XxeTn6ZY63Yo/TI5YKto28sSO7RXHUwMDAzeUFyufxNI+GdTrxcdTAwMGI92lx1MDAxZl9cdTAwMDbNabN9JdmmW1x0wkrZJlDTJjeniZw/XHUwMDAy1mRcdTAwMTRcdTAwMTBKMFxiXHUwMDEyXG7Ll9C0uDVcXCVfzGqdXHUwMDA0+fnyxeuqzqEvLlx1MDAwNFG87HwoxVx1MDAwYiVcYlWCXHUwMDEwpTP7OcvaXHUwMDFifnxG11x1MDAxY420TidRnOQtr89NXHUwMDFl+VBcdTAwMWQ66fFJk/Xsdr1cdTAwMTjGdOTHgTWFyc0mSZvFXHUwMDAzXHUwMDE4VtDrgVx1MDAxNZ53qrds8NbisVtlQ79/4MvKXHUwMDAwf9o48dvue/9L83iHRFx1MDAwM1x1MDAxMXD5qlLkg5FktkJMI8mJolKl50CvXHUwMDBmoXBkc0JcdFx1MDAxMlJiqUnGUVc54CfjXHUwMDFkXSP2XHUwMDAx6aAwXHUwMDA0pmXigVx1MDAxNrev0iQw4Vx1MDAxNCElXHUwMDFmdNr0YbGP77h73ulB0DrYabuv+jHa3Pv0549cdTAwMTj7fL8k8E9cdTAwMTH5lPtJXHUwMDA12Vx1MDAwNPa2uVZKcVBGiohcXOTDJLdhxiRcdTAwMDJlxYDQyCpcdTAwMTV7XbpcXPZq1WAvplx1MDAxNFZUs9Jt9sW3alx1MDAxNKZcdTAwMWHDXHUwMDFjL/uoPES8UqZcdTAwMTb4cXOxd1x1MDAwYoKnz8W+6TTHZ+/d5v7e8U4zPLhSk1x1MDAxZOVUVCSKQuyDNMQsmuusWLiJfYRcctRcdTAwMGKBr4lraObiyipcdTAwMWL7dJheq3NcXE4hUIyKlWVjs5dcdTAwMTbyoNaSS6Qp+Ybb0uz05YHwxl+i9eNX3NP6+HR9d+1HVCSrbOxcdTAwMTNrknJPqaJJwPagXHUwMDEwXHTXXHUwMDFhXFyFsVx1MDAxY51BpFx1MDAwZVx1MDAxM6fMTV/KOJfFm76rbOzj6atdR5JQyjVeIElcdTAwMTbHU0poxmGal33K//GS5JmkY++RXHUwMDA03yBcdTAwMWT7crTzct+9XHUwMDFjf9KdU7nzdrI/7cheXHUwMDE1XGZjWJtsXG7LmjLHpijLneEnXHUwMDEy20zBmiekolx1MDAxNDNRsqVCXHUwMDA0wFx1MDAxY1x1MDAxMagkSPOM6WcgJniVjr1cdTAwMWLF6zVQXGZcdTAwMGKiJKAhy0SIXCI6X5pezTNcdTAwMTexXHUwMDE0fdiW8JMmZNuOn1xcVp87U3riXHUwMDFlgX16SY7x5LLkNsyRn1xch/njyD/y/1x1MDAwN8ZJTqVCi8jqXHUwMDA14XXK0ouO/DE4gncydP//jJOyXHUwMDBiXGZg3Tl+q8LwrZLRLykz+6559frjZGvDoZ2Atz+J18c0qHY21yTobFx1MDAwNdJAIFxy2oDnL1x1MDAwM2NGbESSXHKg5Kp1ybmyVWZ26Vx1MDAxNLRR41x1MDAwNoHknIDeK0vMsjtO55o/yaA4Z1x1MDAwZtpcdTAwMTJ6WFx1MDAxODTdOt9cdTAwMWRv7+x92DrF28fb76fxZVx1MDAxMNRcboNcdTAwMDTEbplbXHUwMDExq8TsfzJcYir3kypcdTAwMDJcbjjMNlaXhGmE8kdSsFx1MDAwNqrjVJgjXFxcdTAwMDRcdTAwMGJdXGaCVnnZx3PXy1x1MDAxYfLJbPlJVbzUbOpcdTAwMTZuZif5OKXRsjezhaSMPuqi8/PIyt4jXHUwMDA2nj4rO8CbXHUwMDFmRu1h72PbR9Pp26u1XrBcdTAwMWZVVCOU2Vx1MDAxMOIoiGE41ihcdTAwMDdgQlx1MDAwMN6UXHUwMDExZFx1MDAwZVTybI5ilZR9OkBvVlx1MDAwN7TAXHUwMDE0NFx1MDAwNS69wyzQwr9dIFx1MDAxNFx1MDAxN1x1MDAxMEOhXHUwMDA3nTF7mFx1MDAxNkG7W293d3u9zY3+3p8x3/OizpfLXHUwMDFmUYusUrJPrEbKPaWKXHUwMDFhwUja5swlXHUwMDEzQmGJdO68P4W5XHUwMDAxlcKIZIogpnExtFolZVx1MDAxZk9fWzXoXHUwMDBigaVcdTAwMTWSpTdcdTAwMWRcdTAwMGJcdTAwMDHWLXtprrRcdTAwMTT8XHUwMDE56pFnkpK9R1x1MDAwZiw3JfvihtFcdTAwMWHOeLxcdTAwMTeDRVx1MDAxYrd3XHUwMDFhXHUwMDFi5547XSt6/C+95MuQf8JcdTAwMDCN67/sXHUwMDAyj3198fVf2zvMXHUwMDEwIn0=2. Use a community image andadd a few packages yourself4. Use a custom Dockerfile1. Use a communitymaintained image3. Use repo2docker config filesWhen and how to use repo2dockerDoes a community alreadymaintain an image with theenvironment I need?noyesDo you just need a fewextra packages in additionto what a community-maintained image offers?noyesCan your environment bedefined by repo2docker configfiles?(see the docs for what ispossible)noyes \ No newline at end of file diff --git a/docs/source/architecture.md b/docs/source/architecture.md index 915e5cd3e..0697969cc 100644 --- a/docs/source/architecture.md +++ b/docs/source/architecture.md @@ -104,9 +104,7 @@ if you specify the `--push` flag. ### Run Optionally, repo2docker can **run** the built image and allow the user to access the Jupyter Notebook -running inside by default. This is also done as a convenience only (since you can do the same with `Docker run` -after using repo2docker only to build), and implemented in `Repo2Docker.run`. It is activated by default -unless the `--no-run` commandline flag is passed. +running inside by default. This is also done as a convenience only (since you can do the same with `docker run` after using repo2docker only to build), and implemented in `Repo2Docker.run`. It is activated by default unless the `--no-run` commandline flag is passed. ## ContentProviders diff --git a/docs/source/changelog.md b/docs/source/changelog.md index 73852c92b..dc415acab 100644 --- a/docs/source/changelog.md +++ b/docs/source/changelog.md @@ -304,7 +304,7 @@ The repo2docker container image has moved to [quay.io/jupyterhub/repo2docker](ht ### Other merged PRs -- Update README quay.io URL, Add Docker latest tag {pr}`1075` by {user}`manics` +- Update README quay.io URL, add Docker latest tag {pr}`1075` by {user}`manics` - GitHub workflow build and push to Docker hub {pr}`1071` by {user}`manics` - Rename master branch to main {pr}`1068` by {user}`manics` - Remove Pipfile & Pipfile.lock {pr}`1054` by {user}`yuvipanda` diff --git a/docs/source/contribute/tasks.md b/docs/source/contribute/tasks.md index 070abf6d7..6e5835558 100644 --- a/docs/source/contribute/tasks.md +++ b/docs/source/contribute/tasks.md @@ -41,7 +41,7 @@ Some of the tests have non-python requirements for your development machine. The - `git-lfs` must be installed ([instructions](https://github.com/git-lfs/git-lfs)). It need not be activated -- there is no need to run the `git lfs install` command. It just needs to be available to the test suite. - If your test failure messages include "`git-lfs filter-process: git-lfs: command not found`", this step should address the problem. -- Minimum Docker Image size of 128GB is required. If you are not running Docker on a linux OS, you may need to expand the runtime image size for your installation. See Docker's instructions for [macOS](https://docs.docker.com/docker-for-mac/space/) or [Windows 10](https://docs.docker.com/docker-for-windows/#resources) for more information. +- Minimum Docker Image size of `128GB` is required. If you are not running Docker on a Linux OS, you may need to expand the runtime image size for your installation. See Docker's [instructions for macOS](https://docs.docker.com/docker-for-mac/space/) or [instructions for Windows 10](https://docs.docker.com/docker-for-windows/#resources) for more information. - If your test failure messages include "`No space left on device: '/home/...`", this step should address the problem. ## Update and Freeze BuildPack Dependencies diff --git a/docs/source/faq.md b/docs/source/faq.md index 9579aebc4..23fed0d84 100644 --- a/docs/source/faq.md +++ b/docs/source/faq.md @@ -7,11 +7,8 @@ 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: +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 @@ -34,12 +31,10 @@ 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.) +Yes! With a [](#postBuild) file, you can place any files that should be called from the command line in the folder `~/.local/bin`. +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? +## Can I use repo2docker to bootstrap my own `Dockerfile` to edit by hand? No, you can't. diff --git a/docs/source/howto/export_environment.rst b/docs/source/howto/export_environment.rst index 42505737b..0aa72fd25 100644 --- a/docs/source/howto/export_environment.rst +++ b/docs/source/howto/export_environment.rst @@ -16,12 +16,9 @@ This is the most robust for reproducibility, but it does bake in potential platform-specific packages, so you can only use an exported environment on the same platform. -``repo2docker`` uses a linux based image as the starting point for every Docker -image it creates. However a lot of people use OSX or Windows as their day to -day operating system. This means that the ``environment.yml`` created by a strict -export will not work with error messages saying that certain packages can not -be resolved (``ResolvePackageNotFound``). - +``repo2docker`` uses a Linux-based image as the starting point for every Docker image it creates. +However a lot of people use OSX or Windows as their day to day operating system. +This means that the ``environment.yml`` created by a strict export will not work with error messages saying that certain packages can not be resolved (``ResolvePackageNotFound``). The solution ============ diff --git a/docs/source/index.md b/docs/source/index.md index cedb33ed5..4c2ac26a1 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,6 +1,6 @@ # Welcome to `repo2docker`'s documentation -`repo2docker` lets you **reproducibly build, run, and deploy user environment images for data science from source code repositories**. +`repo2docker` lets you **reproducibly build, run, and deploy user environment images for research and computing workflows 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 @@ -37,15 +37,15 @@ In short, `repo2docker` is a tool to reproducibly build, run, and deploy these u When you call `repo2docker` like so: ``` -jupyter-repo2docker +jupyter-repo2docker ``` 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) +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 @@ -55,7 +55,7 @@ Please report [Bugs](https://github.com/jupyterhub/repo2docker/issues), ## Get started with repo2docker -This tutorial walks you setting up repo2docker, building your first environment image, and running it locally with Docker. +This tutorial walks you through setting up repo2docker, building your first environment image, and running it locally with Docker. ```{toctree} :maxdepth: 2 @@ -74,7 +74,7 @@ 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. +Our contributor 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 diff --git a/docs/source/use/community-image.md b/docs/source/use/community-image.md index 6c4a6a4b7..95cf543dd 100644 --- a/docs/source/use/community-image.md +++ b/docs/source/use/community-image.md @@ -1,12 +1,12 @@ # Use a community-maintained image in a JupyterHub -The simplest way to deploy environment images to a JupyterHub or BinderHub is to _find and re-use a pre-existing image maintained by a community_. In this case, you won't have to maintain anything - you'll simply use a community's image and contribute upstream if you wish. +The simplest way to deploy environment images to a JupyterHub or BinderHub is to _find and re-use a pre-existing image maintained by a community_. +In this case, you won't have to maintain anything -- you'll simply use a community's image and contribute upstream if you wish. Here are some steps to follow. ## First, find a community-maintained image for your workflow - -Many communities define their own user envionment images for re-use. Here are a few to look into. +Many communities define their own user envionment images for re-use. Here are a few to look into: 1. [jupyter Docker-stacks](https://jupyter-docker-stacks.readthedocs.io/) has a number of user images for general data science workflows. 2. [pangeo Docker-stacks](https://github.com/pangeo-data/pangeo-docker-images) has images for geospatial workflows in the cloud @@ -35,7 +35,7 @@ Instead, we recommend periodically manually updating the tag you use over time. Once you have an image and a tag, you can configure your JupyterHub to use it. -Here's sample configuration if you're using the [Zero to JupyterHub for Kubernetes distribution](https://z2jh.jupyter.org). +Here's a sample configuration if you're using the [Zero to JupyterHub for Kubernetes distribution](https://z2jh.jupyter.org): ```yaml singleuser: @@ -44,7 +44,7 @@ singleuser: tag: 2023.04.15 ``` -Here's sample configuration if you're using the [Dockerspawner for JupyterHub spawner](https://jupyterhub-dockerspawner.readthedocs.io/en/latest/). +Here's a sample configuration if you're using the [Dockerspawner for JupyterHub spawner](https://jupyterhub-dockerspawner.readthedocs.io/en/latest/): ```python c.DockerSpawner.image = 'pangeo/pangeo-notebook:2023.04.15' diff --git a/docs/source/use/extend-community-image.md b/docs/source/use/extend-community-image.md index 078c9d4c9..75e4039ce 100644 --- a/docs/source/use/extend-community-image.md +++ b/docs/source/use/extend-community-image.md @@ -6,7 +6,7 @@ To do this, you should define a `Dockerfile` that "inherits" the community image [Here's a repository that demonstrates how to do this using the `repo2docker` github action](https://github.com/2i2c-org/example-inherit-from-community-image). Below is a summary of the most important parts. -An [`environment.yml` file](https://github.com/2i2c-org/example-inherit-from-community-image/blob/main/environment.yml) defines **only the extra things to install** in addition to the upstream image. +A [local `environment.yml` file](https://github.com/2i2c-org/example-inherit-from-community-image/blob/main/environment.yml) defines **only the extra things to install** in addition to the upstream image. ```{code-block} :caption: environment.yml @@ -24,7 +24,13 @@ dependencies: - otter-grader ``` -A repository `Dockerfile` inherits from the upstream image. For example, the following inherits the scipy-notebook image with the `2023-05-01` tag, and copies +A local `Dockerfile` does the following things: + +- Inherits from the upstream image. +- Copies your local `environment.yml` file into a directory in the image. +- Updates the `conda` environment with it to install the extra packages. + + For example, the following inherits the `scipy-notebook` image with the `2023-05-01` tag and takes the above steps. (you could follow a similar workflow with other package managers). ```{code-block} Dockerfile :caption: Dockerfile diff --git a/docs/source/use/pathways.md b/docs/source/use/pathways.md index 9dfed4eb9..b4eeb00ba 100644 --- a/docs/source/use/pathways.md +++ b/docs/source/use/pathways.md @@ -2,6 +2,7 @@ Many users of `repo2docker` primarily wish to define the environment for a Binder or a JupyterHub. Here are four ways to accomplish this, from least-to-most work. +% TO EDIT THIS FIGURE: Load the linked SVG into excalidraw.com, make edits, and re-export. ```{figure} ../_static/images/whentouse.svg A decision tree for the recommended way to get your reproducible user environment using `repo2docker` or a community image built with `repo2docker`. ``` diff --git a/docs/source/use/repository.md b/docs/source/use/repository.md index 048de524e..0c9d95f0c 100644 --- a/docs/source/use/repository.md +++ b/docs/source/use/repository.md @@ -19,7 +19,7 @@ by `repo2docker` to see how to configure the build process. ## Supported repository providers -repo2docker can fetch repositories from a number of repositories. Here are the ones we support: +`repo2docker` can fetch repositories from a number of repositories. Here are the various types of _repository references_ we support: - A URL of a Git repository (`https://github.com/binder-examples/requirements`), - A Zenodo DOI (`10.5281/zenodo.1211089`), @@ -33,7 +33,7 @@ repo2docker can fetch repositories from a number of repositories. Here are the o In each case you can build from these repository sources like so: ```bash -jupyter-repo2docker +jupyter-repo2docker ``` ## Supported version control systems From ee2373b9e99f7da97ed18560e30f5eafd8c5c70f Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 1 Aug 2025 16:53:24 +0000 Subject: [PATCH 09/12] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source/use/community-image.md | 1 + docs/source/use/extend-community-image.md | 2 +- docs/source/use/pathways.md | 1 + 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/use/community-image.md b/docs/source/use/community-image.md index 95cf543dd..d499768c5 100644 --- a/docs/source/use/community-image.md +++ b/docs/source/use/community-image.md @@ -6,6 +6,7 @@ In this case, you won't have to maintain anything -- you'll simply use a communi Here are some steps to follow. ## First, find a community-maintained image for your workflow + Many communities define their own user envionment images for re-use. Here are a few to look into: 1. [jupyter Docker-stacks](https://jupyter-docker-stacks.readthedocs.io/) has a number of user images for general data science workflows. diff --git a/docs/source/use/extend-community-image.md b/docs/source/use/extend-community-image.md index 75e4039ce..f4bf5159d 100644 --- a/docs/source/use/extend-community-image.md +++ b/docs/source/use/extend-community-image.md @@ -30,7 +30,7 @@ A local `Dockerfile` does the following things: - Copies your local `environment.yml` file into a directory in the image. - Updates the `conda` environment with it to install the extra packages. - For example, the following inherits the `scipy-notebook` image with the `2023-05-01` tag and takes the above steps. (you could follow a similar workflow with other package managers). +For example, the following inherits the `scipy-notebook` image with the `2023-05-01` tag and takes the above steps. (you could follow a similar workflow with other package managers). ```{code-block} Dockerfile :caption: Dockerfile diff --git a/docs/source/use/pathways.md b/docs/source/use/pathways.md index b4eeb00ba..71c507258 100644 --- a/docs/source/use/pathways.md +++ b/docs/source/use/pathways.md @@ -3,6 +3,7 @@ Many users of `repo2docker` primarily wish to define the environment for a Binder or a JupyterHub. Here are four ways to accomplish this, from least-to-most work. % TO EDIT THIS FIGURE: Load the linked SVG into excalidraw.com, make edits, and re-export. + ```{figure} ../_static/images/whentouse.svg A decision tree for the recommended way to get your reproducible user environment using `repo2docker` or a community image built with `repo2docker`. ``` From 2aceb4352111e9fdffb1100bfd6379ecc66e30ed Mon Sep 17 00:00:00 2001 From: choldgraf Date: Fri, 1 Aug 2025 09:55:14 -0700 Subject: [PATCH 10/12] Data and interactive --- docs/source/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/index.md b/docs/source/index.md index 4c2ac26a1..fa3b415d9 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,6 +1,6 @@ # Welcome to `repo2docker`'s documentation -`repo2docker` lets you **reproducibly build, run, and deploy user environment images for research and computing workflows from source code repositories**. +`repo2docker` lets you **reproducibly build, run, and deploy user environment images for interactive data and computing workflows 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 From 8e4b0a0ea6cd398c7cb6d3c401dcd8aebbc5bfc3 Mon Sep 17 00:00:00 2001 From: choldgraf Date: Fri, 1 Aug 2025 10:01:32 -0700 Subject: [PATCH 11/12] typos --- docs/source/architecture.md | 6 +++--- docs/source/cli.md | 2 +- docs/source/configuration/system.md | 2 +- docs/source/faq.md | 2 +- docs/source/howto/languages.md | 2 +- docs/source/index.md | 2 +- docs/source/start.md | 2 +- docs/source/use/pathways.md | 14 +++++++------- 8 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/source/architecture.md b/docs/source/architecture.md index 0697969cc..40e91a4c3 100644 --- a/docs/source/architecture.md +++ b/docs/source/architecture.md @@ -64,7 +64,7 @@ already been built and cached). The `get_build_scripts` and `get_build_script_files` methods are primarily used for this. `get_build_scripts` can return arbitrary bash script lines that can be run as different users, and `get_build_script_files` is used to copy specific scripts (such as a conda installer) into -the image to be run as pat of `get_build_scripts`. Code in either has following constraints: +the image to be run as part of `get_build_scripts`. Code in either has following constraints: 1. You can _not_ use the contents of repository in them, since this happens before the repository is copied into the image. For example, `pip install -r requirements.txt` will not work, @@ -103,8 +103,8 @@ if you specify the `--push` flag. ### Run -Optionally, repo2docker can **run** the built image and allow the user to access the Jupyter Notebook -running inside by default. This is also done as a convenience only (since you can do the same with `docker run` after using repo2docker only to build), and implemented in `Repo2Docker.run`. It is activated by default unless the `--no-run` commandline flag is passed. +Optionally, repo2docker can **run** the built image and allow the user to access the Jupyter Notebook running inside by default. +This is also done as a convenience only (since you can do the same with `docker run` after using repo2docker only to build), and implemented in `Repo2Docker.run`. It is activated by default unless the `--no-run` commandline flag is passed. ## ContentProviders diff --git a/docs/source/cli.md b/docs/source/cli.md index 0da611374..ac60bda8e 100644 --- a/docs/source/cli.md +++ b/docs/source/cli.md @@ -17,7 +17,7 @@ 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). +[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 `requirements.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: diff --git a/docs/source/configuration/system.md b/docs/source/configuration/system.md index a3b0fb81f..b3f5f9626 100644 --- a/docs/source/configuration/system.md +++ b/docs/source/configuration/system.md @@ -46,7 +46,7 @@ When you use this config file all other configuration files (like `requirements. 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. +`repo2docker` will not 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 diff --git a/docs/source/faq.md b/docs/source/faq.md index 23fed0d84..43187b89b 100644 --- a/docs/source/faq.md +++ b/docs/source/faq.md @@ -90,7 +90,7 @@ 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 +see the rstudio logs as it tries to initialize the shiny app. If you are 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? diff --git a/docs/source/howto/languages.md b/docs/source/howto/languages.md index 66560b941..7661a39d7 100644 --- a/docs/source/howto/languages.md +++ b/docs/source/howto/languages.md @@ -66,7 +66,7 @@ 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. +Both of these environment variables are 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. diff --git a/docs/source/index.md b/docs/source/index.md index fa3b415d9..7862b351f 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -21,7 +21,7 @@ Host repositories in a provider like GitHub, an open science repository like [Ze ## What is a user image and why would I build one with `repo2docker`? -A **user image** contains the entire software environment that a user may access from an interactive data science session. For example, it might contain many **programming languages**, **software for data analysis**, or even **contenet files and datasets** available to anybody that accesses that environment. User images are built with [Docker](https://www.docker.com/), a standard open source tool for defining, building, and deploying images. +A **user image** contains the entire software environment that a user may access from an interactive data science session. For example, it might contain many **programming languages**, **software for data analysis**, or even **content files and datasets** available to anybody that accesses that environment. User images are built with [Docker](https://www.docker.com/), a standard open source tool for defining, building, and deploying images. Many data science platforms and services like [JupyterHub](https://jupyterhub.readthedocs.io) and [Binder](https://mybinder.org) launch interactive data science sessions **with a user image attached**, meaning that the user gains access to whatever is in the image. In short, this allows somebody to define and build the user image one time, in a way that users can reproducibly re-use many times. diff --git a/docs/source/start.md b/docs/source/start.md index 6329a6ae4..87d148fc9 100644 --- a/docs/source/start.md +++ b/docs/source/start.md @@ -10,7 +10,7 @@ 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 +This [article about using Windows and the WSL](https://nickjanetakis.com/blog/setting-up-docker-for-windows-and-wsl-to-work-flawlessly) (Windows Subsystem for Linux or Bash on Windows) provides additional information about Windows and Docker. ::: diff --git a/docs/source/use/pathways.md b/docs/source/use/pathways.md index 71c507258..5375152df 100644 --- a/docs/source/use/pathways.md +++ b/docs/source/use/pathways.md @@ -25,7 +25,7 @@ See [](./community-image.md) for a brief how-to on using a community maintained :::{grid-item-card} Drawbacks - Might have lots of stuff you don’t need - Large image sizes, slower pulling -- Might get you 98% of the way there, but that ain’t 100% +- Might get you 98% of the way there, but that isn't 100% - Architectural choices made might not fit your use case - Updates are not on your schedule ::: @@ -38,14 +38,14 @@ Sometimes a community-maintained environment image has **almost** what you need, This is not the same thing as forking the repository for the community image, modifying it, and re-building it from scratch. It's similar to depending on an upstream piece of software and then building upon it in your own tool. ::::{grid} 2 -:::{grid-item-card} Benefits of inheriting and adding to community images +:::{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 ::: - :::{grid-item-card} Drawbacks of inheriting and adding to community images + :::{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 @@ -70,7 +70,7 @@ Check out the other sections under "Image building basics" for more useful how-t - Only get whatever packages you want - Good defaults chosen by the community ::: - :::{grid-item-card} Drawbacks community-maintained images + :::{grid-item-card} Drawbacks - Build time is slower - Images may be bigger - Might not support 100% of what you want, and at some point you might have to take the ramp-off to a Dockerfile @@ -83,17 +83,17 @@ If you need full control over the entire computational environment, you can alwa 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. -[Here's an example repository that uses a `Dockerfile` to build with repo2docker]. +[Here's an example repository that uses a `Dockerfile` to build with repo2docker](https://github.com/yuvipanda/example-use-dockerfile). ::::{grid} 2 -:::{grid-item-card} Benefits of community-maintained images +:::{grid-item-card} Benefits - 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 ::: -:::{grid-item-card} Drawbacks of community-maintained images +:::{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 From 5e755cd7a827e878515c8dac963779b28749c2b3 Mon Sep 17 00:00:00 2001 From: choldgraf Date: Fri, 1 Aug 2025 10:03:40 -0700 Subject: [PATCH 12/12] Interactive computing --- docs/source/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/index.md b/docs/source/index.md index 7862b351f..43593c8a9 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,6 +1,6 @@ # Welcome to `repo2docker`'s documentation -`repo2docker` lets you **reproducibly build, run, and deploy user environment images for interactive data and computing workflows from source code repositories**. +`repo2docker` lets you **reproducibly build, run, and deploy user environment images for interactive computing and data workflows 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