From 1d8d7df2424032ef5704c4eeb7accb8225ac8095 Mon Sep 17 00:00:00 2001 From: romainx Date: Wed, 19 Jan 2022 12:15:54 +0100 Subject: [PATCH 1/9] Default to JupyterLab Introduce a new `JUPYTER_CMD` option --- Makefile | 1 - base-notebook/start-notebook.sh | 12 +++++++----- base-notebook/test/test_container_options.py | 6 ++---- base-notebook/test/test_start_container.py | 17 +++++++++-------- 4 files changed, 18 insertions(+), 18 deletions(-) diff --git a/Makefile b/Makefile index 8c5173cdad..b0f2f7bdac 100644 --- a/Makefile +++ b/Makefile @@ -128,7 +128,6 @@ cont-rm-all: ## remove all containers -dev/%: DARGS?=-e JUPYTER_ENABLE_LAB=yes dev/%: PORT?=8888 dev/%: ## run a foreground container for a stack docker run -it --rm -p $(PORT):8888 $(DARGS) $(OWNER)/$(notdir $@) diff --git a/base-notebook/start-notebook.sh b/base-notebook/start-notebook.sh index a0ab5a9734..d32dd8dd62 100755 --- a/base-notebook/start-notebook.sh +++ b/base-notebook/start-notebook.sh @@ -4,6 +4,10 @@ set -e +# The Jupyter command to launch +# JupyterLab by default +JUPYTER_CMD="${JUPYTER_CMD:=lab}" + if [[ -n "${JUPYTERHUB_API_TOKEN}" ]]; then echo "WARNING: using start-singleuser.sh instead of start-notebook.sh to start a server associated with JupyterHub." exec /usr/local/bin/start-singleuser.sh "$@" @@ -15,10 +19,8 @@ if [[ "${RESTARTABLE}" == "yes" ]]; then fi if [[ -n "${JUPYTER_ENABLE_LAB}" ]]; then - # shellcheck disable=SC1091,SC2086 - exec /usr/local/bin/start.sh ${wrapper} jupyter lab ${NOTEBOOK_ARGS} "$@" -else echo "WARNING: Jupyter Notebook deprecation notice https://github.com/jupyter/docker-stacks#jupyter-notebook-deprecation-notice." - # shellcheck disable=SC1091,SC2086 - exec /usr/local/bin/start.sh ${wrapper} jupyter notebook ${NOTEBOOK_ARGS} "$@" fi + +# shellcheck disable=SC1091,SC2086 +exec /usr/local/bin/start.sh ${wrapper} jupyter ${JUPYTER_CMD} ${NOTEBOOK_ARGS} "$@" diff --git a/base-notebook/test/test_container_options.py b/base-notebook/test/test_container_options.py index 9deb677dbc..2c32d3353d 100644 --- a/base-notebook/test/test_container_options.py +++ b/base-notebook/test/test_container_options.py @@ -23,8 +23,7 @@ def test_cli_args(container: TrackedContainer, http_client: requests.Session) -> warnings = [ warning for warning in logs.split("\n") if warning.startswith("WARNING") ] - assert len(warnings) == 1 - assert warnings[0].startswith("WARNING: Jupyter Notebook deprecation notice") + assert not warnings assert "login_submit" not in resp.text @@ -49,8 +48,7 @@ def test_unsigned_ssl( warnings = [ warning for warning in logs.split("\n") if warning.startswith("WARNING") ] - assert len(warnings) == 1 - assert warnings[0].startswith("WARNING: Jupyter Notebook deprecation notice") + assert not warnings def test_uid_change(container: TrackedContainer) -> None: diff --git a/base-notebook/test/test_start_container.py b/base-notebook/test/test_start_container.py index c644a8580d..a4f14ac808 100644 --- a/base-notebook/test/test_start_container.py +++ b/base-notebook/test/test_start_container.py @@ -11,10 +11,14 @@ @pytest.mark.parametrize( - "env,expected_server", + "env,expected_server,expected_warning", [ - (["JUPYTER_ENABLE_LAB=yes"], "lab"), - (None, "notebook"), + (["JUPYTER_ENABLE_LAB=yes"], "lab", True), + (None, "lab", False), + (["JUPYTER_CMD=lab"], "lab", False), + (["JUPYTER_CMD=notebook"], "notebook", False), + (["JUPYTER_CMD=server"], "server", False), + (["JUPYTER_CMD=nbclassic"], "nbclassic", False), ], ) def test_start_notebook( @@ -22,6 +26,7 @@ def test_start_notebook( http_client: requests.Session, env, expected_server: str, + expected_warning: bool, ) -> None: """Test the notebook start-notebook script""" LOGGER.info( @@ -36,7 +41,7 @@ def test_start_notebook( logs = c.logs(stdout=True).decode("utf-8") LOGGER.debug(logs) assert "ERROR" not in logs - if expected_server != "notebook": + if not expected_warning: assert "WARNING" not in logs else: warnings = [ @@ -48,10 +53,6 @@ def test_start_notebook( assert ( f"Executing the command: jupyter {expected_server}" in logs ), f"Not the expected command (jupyter {expected_server}) was launched" - # Checking warning messages - if not env: - msg = "WARNING: Jupyter Notebook deprecation notice" - assert msg in logs, f"Expected warning message {msg} not printed" def test_tini_entrypoint( From de087bb1a38b5f6d800d8c0cfc558563adc6e0e1 Mon Sep 17 00:00:00 2001 From: romainx Date: Wed, 19 Jan 2022 18:12:15 +0100 Subject: [PATCH 2/9] Test improved (review) --- base-notebook/test/test_start_container.py | 43 +++++++++++++--------- 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/base-notebook/test/test_start_container.py b/base-notebook/test/test_start_container.py index a4f14ac808..5921decb7d 100644 --- a/base-notebook/test/test_start_container.py +++ b/base-notebook/test/test_start_container.py @@ -2,8 +2,10 @@ # Distributed under the terms of the Modified BSD License. import logging +from typing import Optional import pytest import requests +import re from conftest import TrackedContainer @@ -11,22 +13,26 @@ @pytest.mark.parametrize( - "env,expected_server,expected_warning", + "env,expected_server,expected_warnings", [ - (["JUPYTER_ENABLE_LAB=yes"], "lab", True), - (None, "lab", False), - (["JUPYTER_CMD=lab"], "lab", False), - (["JUPYTER_CMD=notebook"], "notebook", False), - (["JUPYTER_CMD=server"], "server", False), - (["JUPYTER_CMD=nbclassic"], "nbclassic", False), + ( + ["JUPYTER_ENABLE_LAB=yes"], + "lab", + ["WARNING: Jupyter Notebook deprecation notice"], + ), + (None, "lab", []), + (["JUPYTER_CMD=lab"], "lab", []), + (["JUPYTER_CMD=notebook"], "notebook", []), + (["JUPYTER_CMD=server"], "server", []), + (["JUPYTER_CMD=nbclassic"], "nbclassic", []), ], ) def test_start_notebook( container: TrackedContainer, http_client: requests.Session, - env, + env: Optional[list], expected_server: str, - expected_warning: bool, + expected_warnings: list, ) -> None: """Test the notebook start-notebook script""" LOGGER.info( @@ -38,17 +44,18 @@ def test_start_notebook( command=["start-notebook.sh"], ) resp = http_client.get("http://localhost:8888") + # checking errors and warnings in logs logs = c.logs(stdout=True).decode("utf-8") LOGGER.debug(logs) - assert "ERROR" not in logs - if not expected_warning: - assert "WARNING" not in logs - else: - warnings = [ - warning for warning in logs.split("\n") if warning.startswith("WARNING") - ] - assert len(warnings) == 1 - assert warnings[0].startswith("WARNING: Jupyter Notebook deprecation notice") + assert "ERROR" not in logs, "ERROR(s) found in logs" + for exp_warning in expected_warnings: + assert exp_warning in logs, f"Expected warning {exp_warning} not found in logs" + warnings = re.findall(r"^WARNING", logs, flags=re.MULTILINE) + assert len(expected_warnings) == len( + warnings + ), "Not found the number of expected warnings in logs" + + # checking if the server is listening assert resp.status_code == 200, "Server is not listening" assert ( f"Executing the command: jupyter {expected_server}" in logs From 39ae7d22025d1455b7f3c850748a7b9f0a29f691 Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Wed, 19 Jan 2022 23:37:45 +0200 Subject: [PATCH 3/9] Fix typing --- base-notebook/test/test_start_container.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/base-notebook/test/test_start_container.py b/base-notebook/test/test_start_container.py index 5921decb7d..4ce099a808 100644 --- a/base-notebook/test/test_start_container.py +++ b/base-notebook/test/test_start_container.py @@ -30,9 +30,9 @@ def test_start_notebook( container: TrackedContainer, http_client: requests.Session, - env: Optional[list], + env: Optional[list[str]], expected_server: str, - expected_warnings: list, + expected_warnings: list[str], ) -> None: """Test the notebook start-notebook script""" LOGGER.info( From 1178c33e27499cf6d37927fc40ee3fd5f2383bc3 Mon Sep 17 00:00:00 2001 From: romainx Date: Thu, 20 Jan 2022 09:12:38 +0100 Subject: [PATCH 4/9] Fix comand and improve tests --- base-notebook/start-notebook.sh | 4 +- base-notebook/test/test_start_container.py | 47 ++++++++++++++-------- 2 files changed, 32 insertions(+), 19 deletions(-) diff --git a/base-notebook/start-notebook.sh b/base-notebook/start-notebook.sh index d32dd8dd62..64892dc4ee 100755 --- a/base-notebook/start-notebook.sh +++ b/base-notebook/start-notebook.sh @@ -18,8 +18,8 @@ if [[ "${RESTARTABLE}" == "yes" ]]; then wrapper="run-one-constantly" fi -if [[ -n "${JUPYTER_ENABLE_LAB}" ]]; then - echo "WARNING: Jupyter Notebook deprecation notice https://github.com/jupyter/docker-stacks#jupyter-notebook-deprecation-notice." +if [[ -v JUPYTER_ENABLE_LAB ]]; then + echo "WARNING: JUPYTER_ENABLE_LAB is ignored, use JUPYTER_CMD if you want to change the command used to start the server" fi # shellcheck disable=SC1091,SC2086 diff --git a/base-notebook/test/test_start_container.py b/base-notebook/test/test_start_container.py index 5921decb7d..1cb17e71bd 100644 --- a/base-notebook/test/test_start_container.py +++ b/base-notebook/test/test_start_container.py @@ -6,6 +6,7 @@ import pytest import requests import re +import time from conftest import TrackedContainer @@ -13,40 +14,54 @@ @pytest.mark.parametrize( - "env,expected_server,expected_warnings", + "env,expected_command,expected_start,expected_warnings", [ ( ["JUPYTER_ENABLE_LAB=yes"], - "lab", - ["WARNING: Jupyter Notebook deprecation notice"], + "jupyter lab", + True, + ["WARNING: JUPYTER_ENABLE_LAB is ignored"], + ), + (None, "jupyter lab", True, []), + (["JUPYTER_CMD=lab"], "jupyter lab", True, []), + (["RESTARTABLE=yes"], "run-one-constantly jupyter lab", True, []), + (["JUPYTER_CMD=notebook"], "jupyter notebook", True, []), + (["JUPYTER_CMD=server"], "jupyter server", True, []), + (["JUPYTER_CMD=nbclassic"], "jupyter nbclassic", True, []), + ( + ["JUPYTERHUB_API_TOKEN=my_token"], + "jupyterhub-singleuser", + False, + ["WARNING: using start-singleuser.sh"], ), - (None, "lab", []), - (["JUPYTER_CMD=lab"], "lab", []), - (["JUPYTER_CMD=notebook"], "notebook", []), - (["JUPYTER_CMD=server"], "server", []), - (["JUPYTER_CMD=nbclassic"], "nbclassic", []), ], ) def test_start_notebook( container: TrackedContainer, http_client: requests.Session, env: Optional[list], - expected_server: str, + expected_command: str, + expected_start: bool, expected_warnings: list, ) -> None: """Test the notebook start-notebook script""" LOGGER.info( - f"Test that the start-notebook launches the {expected_server} server from the env {env} ..." + f"Test that the start-notebook launches the {expected_command} server from the env {env} ..." ) c = container.run( tty=True, environment=env, command=["start-notebook.sh"], ) - resp = http_client.get("http://localhost:8888") - # checking errors and warnings in logs + # sleeping some time to let the server start + time.sleep(3) logs = c.logs(stdout=True).decode("utf-8") LOGGER.debug(logs) + # checking that the expected command is launched + assert ( + f"Executing the command: {expected_command}" in logs + ), f"Not the expected command ({expected_command}) was launched" + # checking errors and warnings in logs assert "ERROR" not in logs, "ERROR(s) found in logs" for exp_warning in expected_warnings: assert exp_warning in logs, f"Expected warning {exp_warning} not found in logs" @@ -54,12 +69,10 @@ def test_start_notebook( assert len(expected_warnings) == len( warnings ), "Not found the number of expected warnings in logs" - # checking if the server is listening - assert resp.status_code == 200, "Server is not listening" - assert ( - f"Executing the command: jupyter {expected_server}" in logs - ), f"Not the expected command (jupyter {expected_server}) was launched" + if expected_start: + resp = http_client.get("http://localhost:8888") + assert resp.status_code == 200, "Server is not listening" def test_tini_entrypoint( From 554ab113b13abeaccce3f21e88e7d29d3fb1b394 Mon Sep 17 00:00:00 2001 From: romainx Date: Thu, 20 Jan 2022 09:35:20 +0100 Subject: [PATCH 5/9] Update documentation --- README.md | 11 +++++------ docs/index.rst | 2 +- docs/using/common.md | 2 +- docs/using/recipes.md | 25 ++++++++++++++++++++----- examples/openshift/README.md | 10 ---------- 5 files changed, 27 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index c1ede2ed75..ec281fd023 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ where `hostname` is the name of the computer running docker and `token` is the s Docker destroys the container after notebook server exit, but any files written to `~/work` in the container remain intact on the host. ```bash -docker run --rm -p 10000:8888 -e JUPYTER_ENABLE_LAB=yes -v "${PWD}":/home/jovyan/work jupyter/datascience-notebook:33add21fab64 +docker run --rm -p 10000:8888 -e -v "${PWD}":/home/jovyan/work jupyter/datascience-notebook:33add21fab64 ``` ## Contributing @@ -76,13 +76,12 @@ We will happily grant additional permissions (e.g., ability to merge PRs) to any ## Jupyter Notebook Deprecation Notice -Following [Jupyter Notebook notice](https://github.com/jupyter/notebook#notice), we encourage users to transition to JupyterLab. -This can be done by passing the environment variable `JUPYTER_ENABLE_LAB=yes` at container startup, +Following [Jupyter Notebook notice](https://github.com/jupyter/notebook#notice), JupyterLab is now the default for all of the Jupyter Docker stack images. +It is still possible to switch back to Jupyter Notebook (or to launch a different startup command). +This can be done by passing the environment variable `JUPYTER_CMD=notebook` (or any other valid `jupyter` command) at container startup, more information is available in the [documentation](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/common.html#docker-options). -At some point, JupyterLab will become the default for all of the Jupyter Docker stack images, however a new environment variable will be introduced to switch back to Jupyter Notebook if needed. - -After the change of default, and according to the Jupyter Notebook project status and its compatibility with JupyterLab, +According to the Jupyter Notebook project status and its compatibility with JupyterLab, these Docker images may remove the classic Jupyter Notebook interface altogether in favor of another _classic-like_ UI built atop JupyterLab. This change is tracked in the issue [#1217](https://github.com/jupyter/docker-stacks/issues/1217), please check its content for more information. diff --git a/docs/index.rst b/docs/index.rst index c0ebc97fdd..4a333004be 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -42,7 +42,7 @@ Visiting ``http://:10000/lab?token=`` in a browser loads Jupyte where ``hostname`` is the name of the computer running docker and ``token`` is the secret token printed in the console. Docker destroys the container after notebook server exit, but any files written to ``~/work`` in the container remain intact on the host.:: - docker run --rm -p 10000:8888 -e JUPYTER_ENABLE_LAB=yes -v "${PWD}":/home/jovyan/work jupyter/datascience-notebook:33add21fab64 + docker run --rm -p 10000:8888 -v "${PWD}":/home/jovyan/work jupyter/datascience-notebook:33add21fab64 CPU Architectures ----------------- diff --git a/docs/using/common.md b/docs/using/common.md index 7c69649d4f..64ae69ace2 100644 --- a/docs/using/common.md +++ b/docs/using/common.md @@ -69,7 +69,7 @@ You do so by passing arguments to the `docker run` command. (The `start-notebook.sh` script will `su ${NB_USER}` after adding `${NB_USER}` to sudoers.) **You should only enable `sudo` if you trust the user or if the container is running on an isolated host.** - `-e GEN_CERT=yes` - Instructs the startup script to generates a self-signed SSL certificate and configure Jupyter Notebook to use it to accept encrypted HTTPS connections. -- `-e JUPYTER_ENABLE_LAB=yes` - Instructs the startup script to run `jupyter lab` instead of the default `jupyter notebook` command. +- `-e JUPYTER_CMD=yes` - Instructs the startup script to run `jupyter ${JUPYTER_CMD}` instead of the default `jupyter lab` command. Useful in container orchestration environments where setting environment variables is easier than change command line parameters. - `-e RESTARTABLE=yes` - Runs Jupyter in a loop so that quitting Jupyter does not cause the container to exit. This may be useful when you need to install extensions that require restarting Jupyter. diff --git a/docs/using/recipes.md b/docs/using/recipes.md index 5349ac810f..efa063c96a 100644 --- a/docs/using/recipes.md +++ b/docs/using/recipes.md @@ -137,13 +137,28 @@ ENV PATH "${CONDA_DIR}/envs/${conda_env}/bin:${PATH}" # ENV CONDA_DEFAULT_ENV ${conda_env} ``` -## Run JupyterLab +## Switching back to classic notebook or using a different startup command -JupyterLab is preinstalled as a notebook extension starting in tag -[c33a7dc0eece](https://github.com/jupyter/docker-stacks/pull/355). +JupyterLab built on top of Jupyter Server is now the default for all images of the stack. +However, it is still possible to switch back to the classic notebook or to use a different startup command. +This can be done by setting the environment variable `JUPYTER_CMD` at container startup. -Run jupyterlab using a command such as -`docker run -it --rm -p 8888:8888 -e JUPYTER_ENABLE_LAB=yes jupyter/datascience-notebook` +- `JUPYTER_CMD=notebook`: Start Jupyter Notebook frontend and backend. +- `JUPYTER_CMD=nbclassic`: Start Jupyter Notebook frontend and Jupyter Server backend. + +_Note: Any other valid `jupyter` command that starts the Jupyter server can be used._ + +Example: + +```bash +# Run Jupyter Notebook classic +docker run -it --rm -p 8888:8888 -e JUPYTER_CMD=notebook jupyter/base-notebook +# Executing the command: jupyter notebook + +# Run Jupyter Notebook on Jupyter Server +docker run -it --rm -p 8888:8888 -e JUPYTER_CMD=nbclassic jupyter/base-notebook +# Executing the command: jupyter nbclassic +``` ## Dask JupyterLab Extension diff --git a/examples/openshift/README.md b/examples/openshift/README.md index 82e39e2f54..c16458148b 100644 --- a/examples/openshift/README.md +++ b/examples/openshift/README.md @@ -127,16 +127,6 @@ To delete the notebook instance, run `oc delete` using a label selector for the oc delete all,configmap --selector app=mynotebook ``` -## Enabling Jupyter Lab Interface - -To enable the Jupyter Lab interface for a deployed notebook set the `JUPYTER_ENABLE_LAB` environment variable. - -```bash -oc set env dc/mynotebook JUPYTER_ENABLE_LAB=true -``` - -Setting the environment variable will trigger a new deployment and the Jupyter Lab interface will be enabled. - ## Adding Persistent Storage You can upload notebooks and other files using the web interface of the notebook. From c6f7d4637e549794e9286174dfb062cb28816797 Mon Sep 17 00:00:00 2001 From: romainx Date: Thu, 20 Jan 2022 15:28:01 +0100 Subject: [PATCH 6/9] Fix / improve docs (review) --- docs/using/common.md | 41 +++++++++++++++++++++++++++++++++++++++-- docs/using/recipes.md | 23 ----------------------- 2 files changed, 39 insertions(+), 25 deletions(-) diff --git a/docs/using/common.md b/docs/using/common.md index 64ae69ace2..6277ef9648 100644 --- a/docs/using/common.md +++ b/docs/using/common.md @@ -69,7 +69,8 @@ You do so by passing arguments to the `docker run` command. (The `start-notebook.sh` script will `su ${NB_USER}` after adding `${NB_USER}` to sudoers.) **You should only enable `sudo` if you trust the user or if the container is running on an isolated host.** - `-e GEN_CERT=yes` - Instructs the startup script to generates a self-signed SSL certificate and configure Jupyter Notebook to use it to accept encrypted HTTPS connections. -- `-e JUPYTER_CMD=yes` - Instructs the startup script to run `jupyter ${JUPYTER_CMD}` instead of the default `jupyter lab` command. +- `-e JUPYTER_CMD=` - Instructs the startup script to run `jupyter ${JUPYTER_CMD}` instead of the default `jupyter lab` command. + See [Switching back to classic notebook or using a different startup command][switch_back] for available options. Useful in container orchestration environments where setting environment variables is easier than change command line parameters. - `-e RESTARTABLE=yes` - Runs Jupyter in a loop so that quitting Jupyter does not cause the container to exit. This may be useful when you need to install extensions that require restarting Jupyter. @@ -130,7 +131,41 @@ For additional information about using SSL, see the following: ## Alternative Commands -### start.sh +### Switching back to classic notebook or using a different startup command + +JupyterLab built on top of Jupyter Server is now the default for all images of the stack. +However, it is still possible to switch back to the classic notebook or to use a different startup command. +This can be done by setting the environment variable `JUPYTER_CMD` at container startup. +The table below shows some options. + +| `JUPYTER_CMD` | Backend | Frontend | +| --------------- | ---------------- | ---------------- | +| `lab` (default) | Jupyter Server | JupyterLab | +| `notebook` | Jupyter Notebook | Jupyter Notebook | +| `nbclassic` | Jupyter Server | Jupyter Notebook | +| `server` | Jupyter Server | None | +| `retro`\* | Jupyter Server | RetroLab | + +Notes: + +- \*Not installed at this time, but it could be the case in the future or in a community stack. +- Any other valid `jupyter` command that starts the Jupyter server can be used. + +Example: + +```bash +# Run Jupyter Notebook classic +docker run -it --rm -p 8888:8888 -e JUPYTER_CMD=notebook \ + jupyter/base-notebook +# Executing the command: jupyter notebook ... + +# Run Jupyter Notebook on Jupyter Server +docker run -it --rm -p 8888:8888 -e JUPYTER_CMD=nbclassic + jupyter/base-notebook +# Executing the command: jupyter nbclassic ... +``` + +### `start.sh` The `start-notebook.sh` script actually inherits most of its option handling capability from a more generic `start.sh` script. The `start.sh` script supports all of the features described above, but allows you to specify an arbitrary command to execute. @@ -196,3 +231,5 @@ mamba install --quiet --yes humanize && \ fix-permissions "${CONDA_DIR}" && \ fix-permissions "/home/${NB_USER}" ``` + +[switch_back]: common.html#switching-back-to-classic-notebook-or-using-a-different-startup-command diff --git a/docs/using/recipes.md b/docs/using/recipes.md index efa063c96a..809245b7d1 100644 --- a/docs/using/recipes.md +++ b/docs/using/recipes.md @@ -137,29 +137,6 @@ ENV PATH "${CONDA_DIR}/envs/${conda_env}/bin:${PATH}" # ENV CONDA_DEFAULT_ENV ${conda_env} ``` -## Switching back to classic notebook or using a different startup command - -JupyterLab built on top of Jupyter Server is now the default for all images of the stack. -However, it is still possible to switch back to the classic notebook or to use a different startup command. -This can be done by setting the environment variable `JUPYTER_CMD` at container startup. - -- `JUPYTER_CMD=notebook`: Start Jupyter Notebook frontend and backend. -- `JUPYTER_CMD=nbclassic`: Start Jupyter Notebook frontend and Jupyter Server backend. - -_Note: Any other valid `jupyter` command that starts the Jupyter server can be used._ - -Example: - -```bash -# Run Jupyter Notebook classic -docker run -it --rm -p 8888:8888 -e JUPYTER_CMD=notebook jupyter/base-notebook -# Executing the command: jupyter notebook - -# Run Jupyter Notebook on Jupyter Server -docker run -it --rm -p 8888:8888 -e JUPYTER_CMD=nbclassic jupyter/base-notebook -# Executing the command: jupyter nbclassic -``` - ## Dask JupyterLab Extension [Dask JupyterLab Extension](https://github.com/dask/dask-labextension) provides a JupyterLab extension to manage Dask clusters, as well as embed Dask's dashboard plots directly into JupyterLab panes. From 88d83c9f16e48e9c5f52f58b890fb8797b7916f2 Mon Sep 17 00:00:00 2001 From: romainx Date: Thu, 20 Jan 2022 19:41:50 +0100 Subject: [PATCH 7/9] Wording in the examples (review) --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index ec281fd023..f7ad583983 100644 --- a/README.md +++ b/README.md @@ -21,9 +21,9 @@ and want to launch a single Jupyter Notebook server in a container. The [User Guide on ReadTheDocs](https://jupyter-docker-stacks.readthedocs.io/) describes additional uses and features in detail. **Example 1:** This command pulls the `jupyter/scipy-notebook` image tagged `33add21fab64` from Docker Hub if it is not already present on the local host. -It then starts a container running a Jupyter Notebook server and exposes the server on host port 8888. +It then starts a container running a Jupyter Server and exposes the server on host port 8888. The server logs appear in the terminal. -Visiting `http://:8888/?token=` in a browser loads the Jupyter Notebook dashboard page, +Visiting `http://:8888/?token=` in a browser loads JupyterLab, where `hostname` is the name of the computer running docker and `token` is the secret token printed in the console. The container remains intact for restart after the notebook server exits. @@ -32,7 +32,7 @@ docker run -p 8888:8888 jupyter/scipy-notebook:33add21fab64 ``` **Example 2:** This command performs the same operations as **Example 1**, but it exposes the server on host port 10000 instead of port 8888. -Visiting `http://:10000/?token=` in a browser loads Jupyter Notebook server, +Visiting `http://:10000/?token=` in a browser loads JupyterLab, where `hostname` is the name of the computer running docker and `token` is the secret token printed in the console. ```bash @@ -40,15 +40,15 @@ docker run -p 10000:8888 jupyter/scipy-notebook:33add21fab64 ``` **Example 3:** This command pulls the `jupyter/datascience-notebook` image tagged `33add21fab64` from Docker Hub if it is not already present on the local host. -It then starts an _ephemeral_ container running a Jupyter Notebook server and exposes the server on host port 10000. +It then starts an _ephemeral_ container running a Jupyter Server and exposes the server on host port 10000. The command mounts the current working directory on the host as `/home/jovyan/work` in the container. The server logs appear in the terminal. Visiting `http://:10000/?token=` in a browser loads JupyterLab, where `hostname` is the name of the computer running docker and `token` is the secret token printed in the console. -Docker destroys the container after notebook server exit, but any files written to `~/work` in the container remain intact on the host. +Docker destroys the container after Jupyter Server exit, but any files written to `~/work` in the container remain intact on the host. ```bash -docker run --rm -p 10000:8888 -e -v "${PWD}":/home/jovyan/work jupyter/datascience-notebook:33add21fab64 +docker run --rm -p 10000:8888 -v "${PWD}":/home/jovyan/work jupyter/datascience-notebook:33add21fab64 ``` ## Contributing From 74bc6b3fa5f3ebb29c7eb1e80fe8c7531b6260f2 Mon Sep 17 00:00:00 2001 From: romainx Date: Thu, 20 Jan 2022 23:23:54 +0100 Subject: [PATCH 8/9] Align examples in both docs (review) --- README.md | 4 ++-- docs/index.rst | 14 +++++++------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index f7ad583983..e1924d7d93 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ by simply clicking the preceding link. The image used in binder was last updated on 22 May 2021. Otherwise, three examples below may help you get started if you [have Docker installed](https://docs.docker.com/install/), know [which Docker image](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html) you want to use -and want to launch a single Jupyter Notebook server in a container. +and want to launch a single Jupyter Server in a container. The [User Guide on ReadTheDocs](https://jupyter-docker-stacks.readthedocs.io/) describes additional uses and features in detail. @@ -25,7 +25,7 @@ It then starts a container running a Jupyter Server and exposes the server on ho The server logs appear in the terminal. Visiting `http://:8888/?token=` in a browser loads JupyterLab, where `hostname` is the name of the computer running docker and `token` is the secret token printed in the console. -The container remains intact for restart after the notebook server exits. +The container remains intact for restart after the Jupyter Server exits. ```bash docker run -p 8888:8888 jupyter/scipy-notebook:33add21fab64 diff --git a/docs/index.rst b/docs/index.rst index 4a333004be..f9fc865177 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,32 +15,32 @@ You can try a `relatively recent build of the jupyter/base-notebook image on myb by simply clicking the preceding link. Otherwise, three examples below may help you get started if you `have Docker installed `_, know :doc:`which Docker image ` you want to use -and want to launch a single Jupyter Notebook server in a container. +and want to launch a single Jupyter Server in a container. The other pages in this documentation describe additional uses and features in detail. **Example 1:** This command pulls the ``jupyter/scipy-notebook`` image tagged ``33add21fab64`` from Docker Hub if it is not already present on the local host. -It then starts a container running a Jupyter Notebook server and exposes the server on host port 8888. +It then starts a container running a Jupyter Server and exposes the server on host port 8888. The server logs appear in the terminal. -Visiting ``http://:8888/?token=`` in a browser loads the Jupyter Notebook dashboard page, +Visiting ``http://:8888/?token=`` in a browser loads JupyterLab, where ``hostname`` is the name of the computer running docker and ``token`` is the secret token printed in the console. -The container remains intact for restart after the notebook server exits.:: +The container remains intact for restart after the Jupyter Server exits.:: docker run -p 8888:8888 jupyter/scipy-notebook:33add21fab64 **Example 2:** This command performs the same operations as **Example 1**, but it exposes the server on host port 10000 instead of port 8888. -Visiting ``http://:10000/?token=`` in a browser loads Jupyter Notebook server, +Visiting ``http://:10000/?token=`` in a browser loads JupyterLab, where ``hostname`` is the name of the computer running docker and ``token`` is the secret token printed in the console.:: docker run -p 10000:8888 jupyter/scipy-notebook:33add21fab64 **Example 3:** This command pulls the ``jupyter/datascience-notebook`` image tagged ``33add21fab64`` from Docker Hub if it is not already present on the local host. -It then starts an *ephemeral* container running a Jupyter Notebook server and exposes the server on host port 10000. +It then starts an *ephemeral* container running a Jupyter Server and exposes the server on host port 10000. The command mounts the current working directory on the host as ``/home/jovyan/work`` in the container. The server logs appear in the terminal. Visiting ``http://:10000/lab?token=`` in a browser loads JupyterLab, where ``hostname`` is the name of the computer running docker and ``token`` is the secret token printed in the console. -Docker destroys the container after notebook server exit, but any files written to ``~/work`` in the container remain intact on the host.:: +Docker destroys the container after Jupyter Server exit, but any files written to ``~/work`` in the container remain intact on the host.:: docker run --rm -p 10000:8888 -v "${PWD}":/home/jovyan/work jupyter/datascience-notebook:33add21fab64 From c9546339815d832f37d5c48bbb4503371eea60e0 Mon Sep 17 00:00:00 2001 From: romainx Date: Thu, 20 Jan 2022 23:32:52 +0100 Subject: [PATCH 9/9] JUPYTER_CMD -> DOCKER_STACKS_JUPYTER_CMD (review) --- README.md | 2 +- base-notebook/start-notebook.sh | 6 +++--- base-notebook/test/test_start_container.py | 8 ++++---- docs/using/common.md | 22 +++++++++++----------- 4 files changed, 19 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index e1924d7d93..50282230c2 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ We will happily grant additional permissions (e.g., ability to merge PRs) to any Following [Jupyter Notebook notice](https://github.com/jupyter/notebook#notice), JupyterLab is now the default for all of the Jupyter Docker stack images. It is still possible to switch back to Jupyter Notebook (or to launch a different startup command). -This can be done by passing the environment variable `JUPYTER_CMD=notebook` (or any other valid `jupyter` command) at container startup, +This can be done by passing the environment variable `DOCKER_STACKS_JUPYTER_CMD=notebook` (or any other valid `jupyter` command) at container startup, more information is available in the [documentation](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/common.html#docker-options). According to the Jupyter Notebook project status and its compatibility with JupyterLab, diff --git a/base-notebook/start-notebook.sh b/base-notebook/start-notebook.sh index 64892dc4ee..ce47768d34 100755 --- a/base-notebook/start-notebook.sh +++ b/base-notebook/start-notebook.sh @@ -6,7 +6,7 @@ set -e # The Jupyter command to launch # JupyterLab by default -JUPYTER_CMD="${JUPYTER_CMD:=lab}" +DOCKER_STACKS_JUPYTER_CMD="${DOCKER_STACKS_JUPYTER_CMD:=lab}" if [[ -n "${JUPYTERHUB_API_TOKEN}" ]]; then echo "WARNING: using start-singleuser.sh instead of start-notebook.sh to start a server associated with JupyterHub." @@ -19,8 +19,8 @@ if [[ "${RESTARTABLE}" == "yes" ]]; then fi if [[ -v JUPYTER_ENABLE_LAB ]]; then - echo "WARNING: JUPYTER_ENABLE_LAB is ignored, use JUPYTER_CMD if you want to change the command used to start the server" + echo "WARNING: JUPYTER_ENABLE_LAB is ignored, use DOCKER_STACKS_JUPYTER_CMD if you want to change the command used to start the server" fi # shellcheck disable=SC1091,SC2086 -exec /usr/local/bin/start.sh ${wrapper} jupyter ${JUPYTER_CMD} ${NOTEBOOK_ARGS} "$@" +exec /usr/local/bin/start.sh ${wrapper} jupyter ${DOCKER_STACKS_JUPYTER_CMD} ${NOTEBOOK_ARGS} "$@" diff --git a/base-notebook/test/test_start_container.py b/base-notebook/test/test_start_container.py index 4295c95414..fcc09f5ede 100644 --- a/base-notebook/test/test_start_container.py +++ b/base-notebook/test/test_start_container.py @@ -23,11 +23,11 @@ ["WARNING: JUPYTER_ENABLE_LAB is ignored"], ), (None, "jupyter lab", True, []), - (["JUPYTER_CMD=lab"], "jupyter lab", True, []), + (["DOCKER_STACKS_JUPYTER_CMD=lab"], "jupyter lab", True, []), (["RESTARTABLE=yes"], "run-one-constantly jupyter lab", True, []), - (["JUPYTER_CMD=notebook"], "jupyter notebook", True, []), - (["JUPYTER_CMD=server"], "jupyter server", True, []), - (["JUPYTER_CMD=nbclassic"], "jupyter nbclassic", True, []), + (["DOCKER_STACKS_JUPYTER_CMD=notebook"], "jupyter notebook", True, []), + (["DOCKER_STACKS_JUPYTER_CMD=server"], "jupyter server", True, []), + (["DOCKER_STACKS_JUPYTER_CMD=nbclassic"], "jupyter nbclassic", True, []), ( ["JUPYTERHUB_API_TOKEN=my_token"], "jupyterhub-singleuser", diff --git a/docs/using/common.md b/docs/using/common.md index 6277ef9648..18af973171 100644 --- a/docs/using/common.md +++ b/docs/using/common.md @@ -69,7 +69,7 @@ You do so by passing arguments to the `docker run` command. (The `start-notebook.sh` script will `su ${NB_USER}` after adding `${NB_USER}` to sudoers.) **You should only enable `sudo` if you trust the user or if the container is running on an isolated host.** - `-e GEN_CERT=yes` - Instructs the startup script to generates a self-signed SSL certificate and configure Jupyter Notebook to use it to accept encrypted HTTPS connections. -- `-e JUPYTER_CMD=` - Instructs the startup script to run `jupyter ${JUPYTER_CMD}` instead of the default `jupyter lab` command. +- `-e DOCKER_STACKS_JUPYTER_CMD=` - Instructs the startup script to run `jupyter ${DOCKER_STACKS_JUPYTER_CMD}` instead of the default `jupyter lab` command. See [Switching back to classic notebook or using a different startup command][switch_back] for available options. Useful in container orchestration environments where setting environment variables is easier than change command line parameters. - `-e RESTARTABLE=yes` - Runs Jupyter in a loop so that quitting Jupyter does not cause the container to exit. @@ -135,16 +135,16 @@ For additional information about using SSL, see the following: JupyterLab built on top of Jupyter Server is now the default for all images of the stack. However, it is still possible to switch back to the classic notebook or to use a different startup command. -This can be done by setting the environment variable `JUPYTER_CMD` at container startup. +This can be done by setting the environment variable `DOCKER_STACKS_JUPYTER_CMD` at container startup. The table below shows some options. -| `JUPYTER_CMD` | Backend | Frontend | -| --------------- | ---------------- | ---------------- | -| `lab` (default) | Jupyter Server | JupyterLab | -| `notebook` | Jupyter Notebook | Jupyter Notebook | -| `nbclassic` | Jupyter Server | Jupyter Notebook | -| `server` | Jupyter Server | None | -| `retro`\* | Jupyter Server | RetroLab | +| `DOCKER_STACKS_JUPYTER_CMD` | Backend | Frontend | +| --------------------------- | ---------------- | ---------------- | +| `lab` (default) | Jupyter Server | JupyterLab | +| `notebook` | Jupyter Notebook | Jupyter Notebook | +| `nbclassic` | Jupyter Server | Jupyter Notebook | +| `server` | Jupyter Server | None | +| `retro`\* | Jupyter Server | RetroLab | Notes: @@ -155,12 +155,12 @@ Example: ```bash # Run Jupyter Notebook classic -docker run -it --rm -p 8888:8888 -e JUPYTER_CMD=notebook \ +docker run -it --rm -p 8888:8888 -e DOCKER_STACKS_JUPYTER_CMD=notebook \ jupyter/base-notebook # Executing the command: jupyter notebook ... # Run Jupyter Notebook on Jupyter Server -docker run -it --rm -p 8888:8888 -e JUPYTER_CMD=nbclassic +docker run -it --rm -p 8888:8888 -e DOCKER_STACKS_JUPYTER_CMD=nbclassic \ jupyter/base-notebook # Executing the command: jupyter nbclassic ... ```