From c2a3750556990f7c1e88a3b6b8cf64a72911748f Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Thu, 18 May 2023 11:31:41 -0600 Subject: [PATCH 1/4] Support Sphinx >=6.x https://github.com/sphinx-doc/sphinx/issues/11094 `extlinks` config expects a formatting slug in the caption portion of its config. Without it, Sphinx 6.x throws: Exception occurred: File "/path/to/site-packages/sphinx/ext/extlinks.py", line 103, in role title = caption % part TypeError: not all arguments converted during string formatting --- docs/source/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index ec8294dad..2dcb08615 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -29,9 +29,9 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] templates_path = ["_templates"] extlinks = { - "issue": ("https://github.com/jupyterhub/repo2docker/issues/%s", "Issue #"), - "pr": ("https://github.com/jupyterhub/repo2docker/pull/%s", "PR #"), - "user": ("https://github.com/%s", "@"), + "issue": ("https://github.com/jupyterhub/repo2docker/issues/%s", "Issue #%s"), + "pr": ("https://github.com/jupyterhub/repo2docker/pull/%s", "PR #%s"), + "user": ("https://github.com/%s", "@%s"), } From f610e1bbb5412bcf1eb2641571e15c44fdb572a5 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Thu, 18 May 2023 11:41:45 -0600 Subject: [PATCH 2/4] Add link from Dockerfile config file to debug usage --- docs/source/config_files.rst | 4 ++++ docs/source/usage.rst | 2 ++ 2 files changed, 6 insertions(+) diff --git a/docs/source/config_files.rst b/docs/source/config_files.rst index 8d14f7a49..1fc044829 100644 --- a/docs/source/config_files.rst +++ b/docs/source/config_files.rst @@ -245,5 +245,9 @@ With Dockerfiles, a regular Docker build will be performed. .. note:: If a Dockerfile is present, all other configuration files will be ignored. +If you're working on an existing project and need the `Dockerfile` escape +hatch, you can :ref:`view the generated Dockerfile +`. + See the `Advanced Binder Documentation `_ for best-practices with Dockerfiles. diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 8795a2228..9072d3f83 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -106,6 +106,8 @@ by ``repo2docker`` to see how to configure the build process. :ref:`configuration files `. +.. _usage-debugging-with-debug-and-no-build: + Debugging repo2docker with ``--debug`` and ``--no-build`` ========================================================= From e1ce6f55b6eb088a0ec5d3d2219e82e3539d78f8 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Thu, 18 May 2023 12:01:35 -0600 Subject: [PATCH 3/4] Warn of unexpected behavior when creating a Dockerfile from debug output When creating a Dockerfile from redirecting debug output, `repo2docker` sees the initially-empty `Dockerfile` and that influences its output (since `Dockerfile` is empty, `repo2docker` outputs nothing). --- docs/source/usage.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 9072d3f83..77a5a3f44 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -113,9 +113,9 @@ Debugging repo2docker with ``--debug`` and ``--no-build`` To debug the docker image being built, pass the ``--debug`` parameter: - .. code-block:: bash +.. code-block:: bash - jupyter-repo2docker --debug https://github.com/norvig/pytudes + jupyter-repo2docker --debug https://github.com/norvig/pytudes This will print the generated ``Dockerfile``, build it, and run it. @@ -124,9 +124,15 @@ 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 +.. code-block:: bash - jupyter-repo2docker --no-build --debug https://github.com/norvig/pytudes + jupyter-repo2docker --no-build --debug https://github.com/norvig/pytudes + +.. warning:: + + ``repo2docker --no-build --debug . > Dockerfile`` will create an empty + Dockerfile. Please use ``repo2docker --no-build --debug . > tmp_Dockerfile + && mv tmp_Dockerfile Dockerfile`` instead! Command line API From e4c2b4109784f3a01fbc57ef0308411c06ecd6d5 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Thu, 18 May 2023 20:13:10 -0600 Subject: [PATCH 4/4] Correct my misunderstanding and add documentation that would have helped past me I did not see the "Can I use repo2docker to bootstrap my own Dockerfile?" FAQ the first time through. I've linked it from the part that I _did_ see so hopefully the next person through (maybe me in 6 months) won't have the same misunderstanding! --- docs/source/config_files.rst | 11 +++++------ docs/source/faq.rst | 33 +++++++++++++++++++++++++++++++++ docs/source/usage.rst | 11 ++++++----- 3 files changed, 44 insertions(+), 11 deletions(-) diff --git a/docs/source/config_files.rst b/docs/source/config_files.rst index 1fc044829..6420abf2f 100644 --- a/docs/source/config_files.rst +++ b/docs/source/config_files.rst @@ -240,14 +240,13 @@ In the majority of cases, providing your own Dockerfile is not necessary as the 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. +Try the ``--appendix`` :ref:`CLI flag ` as a last resort. If you +still can't achieve your goals, you should create a Dockerfile from scratch to +define your image. .. note:: - If a Dockerfile is present, all other configuration files will be ignored. - -If you're working on an existing project and need the `Dockerfile` escape -hatch, you can :ref:`view the generated Dockerfile -`. + With Dockerfiles, a regular Docker build will be performed. All other + configuration files will be ignored. See the `Advanced Binder Documentation `_ for best-practices with Dockerfiles. diff --git a/docs/source/faq.rst b/docs/source/faq.rst index ce442d04e..426428dc1 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -115,6 +115,9 @@ flag for each variable that you want to define. For example ``jupyter-repo2docker -e VAR1=val1 -e VAR2=val2 ...`` + +.. _faq-dockerfile-bootstrap: + Can I use repo2docker to bootstrap my own Dockerfile? ----------------------------------------------------- @@ -189,3 +192,33 @@ 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. + + +Where are my ``man`` pages? +--------------------------- + +The base image used by ``repo2docker`` is `Minimal Ubuntu +`_ version 18. In Minimal Ubuntu, ``man`` +pages are disabled to reduce image size. If your use case is interactive +computing or education, you may want to re-enable ``man`` pages. To do this, +use the ``--appendix`` :ref:`CLI flag ` to pass in additional +``Dockerfile`` instructions, for example: + +.. code-block:: dockerfile + + # Re-enable man pages disabled in Ubuntu 18 minimal image + # https://wiki.ubuntu.com/Minimal + USER root + RUN yes | unminimize + # NOTE: $NB_PYTHON_PREFIX is the same as $CONDA_PREFIX at run-time. + # $CONDA_PREFIX isn't available in this context. + # NOTE: Prepending ensures a working path; if $MANPATH was previously empty, + # the trailing colon ensures that system paths are searched. + ENV MANPATH="${NB_PYTHON_PREFIX}/share/man:${MANPATH}" + RUN mandb + + # Revert to default user + USER ${NB_USER} + +This appendix can be used by, for example, writing it to a file named +``appendix`` and executing ``repo2docker --appendix "$(cat appendix)" .``. diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 77a5a3f44..47077728f 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -111,6 +111,11 @@ by ``repo2docker`` to see how to configure the build process. Debugging repo2docker with ``--debug`` and ``--no-build`` ========================================================= +.. warning:: + + This feature is *not* for bootstrapping a custom Dockerfile. Please see the + :ref:`relevant FAQ entry `. + To debug the docker image being built, pass the ``--debug`` parameter: .. code-block:: bash @@ -128,12 +133,8 @@ be used by docker directly. jupyter-repo2docker --no-build --debug https://github.com/norvig/pytudes -.. warning:: - - ``repo2docker --no-build --debug . > Dockerfile`` will create an empty - Dockerfile. Please use ``repo2docker --no-build --debug . > tmp_Dockerfile - && mv tmp_Dockerfile Dockerfile`` instead! +.. _usage-cli: Command line API ================