diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index a3aba057f..a76cbf522 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -97,7 +97,7 @@ body: description: | A clear and concise description of what the bug is. placeholder: | - Example: No output is visible in the notebook and the notebook server log contains messages about ... + Example: No output is visible in the notebook and the Server log contains messages about ... validations: required: true diff --git a/README.md b/README.md index 7d764bf94..714c2dadf 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ You can use a stack image to do any of the following (and more): - Start a personal Jupyter Server with the JupyterLab frontend (default) - Run JupyterLab for a team using JupyterHub -- Start a personal Jupyter Notebook server in a local Docker container +- Start a personal Jupyter Server with the Jupyter Notebook frontend in a local Docker container - Write your own project Dockerfile ## Quick Start @@ -20,14 +20,14 @@ You can try a [relatively recent build of the jupyter/base-notebook image on myb by simply clicking the preceding link. Otherwise, the examples below may help you get started if you [have Docker installed](https://docs.docker.com/get-docker/), 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 Server in a container. +and want to launch a single Jupyter Application in a container. The [User Guide on ReadTheDocs](https://jupyter-docker-stacks.readthedocs.io/en/latest/) describes additional uses and features in detail. **Example 1:** This command pulls the `jupyter/scipy-notebook` image tagged `2023-07-25` from Docker Hub if it is not already present on the local host. -It then starts a container running a Jupyter Server and exposes the container's internal port `8888` to port `10000` of the host machine: +It then starts a container running a Jupyter Server with the JupyterLab frontend and exposes the container's internal port `8888` to port `10000` of the host machine: ```bash docker run -p 10000:8888 jupyter/scipy-notebook:2023-07-25 @@ -41,12 +41,12 @@ where: - `hostname` is the name of the computer running Docker - `token` is the secret token printed in the console. -The container remains intact for restart after the Jupyter Server exits. +The container remains intact for restart after the Server exits. **Example 2:** This command pulls the `jupyter/datascience-notebook` image tagged `2023-07-25` from Docker Hub if it is not already present on the local host. -It then starts an _ephemeral_ container running a Jupyter Server and exposes the server on host port 10000. +It then starts an _ephemeral_ container running a Jupyter Server with the JupyterLab frontend and exposes the server on host port 10000. ```bash docker run -it --rm -p 10000:8888 -v "${PWD}":/home/jovyan/work jupyter/datascience-notebook:2023-07-25 @@ -83,18 +83,13 @@ We'd also like to invite members of the community to help with two maintainer ac Anyone in the community can jump in and help with these activities anytime. We will happily grant additional permissions (e.g., the ability to merge PRs) to anyone who shows an ongoing interest in working on the project. -## Jupyter Notebook Deprecation Notice +## Choosing Jupyter frontend -Following [Jupyter Notebook notice](https://github.com/jupyter/notebook#notice), JupyterLab is now the default for all the Jupyter Docker stack images. +JupyterLab is the default for all the Jupyter Docker Stacks images. It is still possible to switch back to Jupyter Notebook (or to launch a different startup command). You can achieve this by passing the environment variable `DOCKER_STACKS_JUPYTER_CMD=notebook` (or any other valid `jupyter` subcommand) at container startup; more information is available in the [documentation](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/common.html#alternative-commands). -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. - ## Alternatives - [jupyter/repo2docker](https://github.com/jupyterhub/repo2docker) - Turn git repositories into diff --git a/base-notebook/Dockerfile b/base-notebook/Dockerfile index 45260fe05..5f47a5d42 100644 --- a/base-notebook/Dockerfile +++ b/base-notebook/Dockerfile @@ -12,7 +12,7 @@ SHELL ["/bin/bash", "-o", "pipefail", "-c"] USER root -# Install all OS dependencies for notebook server that starts but lacks all +# Install all OS dependencies for Server that starts but lacks all # features (e.g., download as all possible file formats) RUN apt-get update --yes && \ apt-get install --yes --no-install-recommends \ @@ -28,19 +28,19 @@ RUN apt-get update --yes && \ USER ${NB_UID} -# Install Jupyter Notebook, Lab, and Hub -# Generate a notebook server config +# Install JupyterLab, Jupyter Notebook, JupyterHub and NBClassic +# Generate a Jupyter Server config # Cleanup temporary files # Correct permissions # Do all this in a single RUN command to avoid duplicating all of the # files across image layers when the permissions change WORKDIR /tmp RUN mamba install --yes \ + 'jupyterlab' \ 'notebook' \ 'jupyterhub' \ - 'jupyterlab' \ 'nbclassic' && \ - jupyter notebook --generate-config && \ + jupyter server --generate-config && \ mamba clean --all -f -y && \ npm cache clean --force && \ jupyter lab clean && \ diff --git a/base-notebook/jupyter_server_config.py b/base-notebook/jupyter_server_config.py index 679f96bee..c4c501478 100644 --- a/base-notebook/jupyter_server_config.py +++ b/base-notebook/jupyter_server_config.py @@ -53,7 +53,6 @@ os.chmod(pem_file, stat.S_IRUSR | stat.S_IWUSR) c.ServerApp.certfile = pem_file -# Change default umask for all subprocesses of the notebook server if set in -# the environment +# Change default umask for all subprocesses of the Server if set in the environment if "NB_UMASK" in os.environ: os.umask(int(os.environ["NB_UMASK"], 8)) diff --git a/binder/README.ipynb b/binder/README.ipynb index 4116a188f..66630c9e8 100644 --- a/binder/README.ipynb +++ b/binder/README.ipynb @@ -28,7 +28,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "The notebook server is running as the following user." + "The Server is running as the following user." ] }, { @@ -128,7 +128,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.9.10" + "version": "3.11.4" } }, "nbformat": 4, diff --git a/docker-stacks-foundation/Dockerfile b/docker-stacks-foundation/Dockerfile index d87dad6de..e68687361 100644 --- a/docker-stacks-foundation/Dockerfile +++ b/docker-stacks-foundation/Dockerfile @@ -18,8 +18,8 @@ SHELL ["/bin/bash", "-o", "pipefail", "-c"] USER root -# Install all OS dependencies for notebook server that starts but lacks all -# features (e.g., download as all possible file formats) +# Install all OS dependencies for Server that starts +# but lacks all features (e.g., download as all possible file formats) ENV DEBIAN_FRONTEND noninteractive RUN apt-get update --yes && \ # - apt-get upgrade is run to patch known vulnerabilities in apt-get packages as diff --git a/docs/contributing/features.md b/docs/contributing/features.md index 08c1331f2..86c6289ef 100644 --- a/docs/contributing/features.md +++ b/docs/contributing/features.md @@ -20,7 +20,7 @@ Please follow the process below to suggest a new feature for inclusion in one of Roughly speaking, we evaluate new features based on the following criteria: - **Usefulness to Jupyter users**: Is the feature generally applicable across domains? Does it work - with Jupyter Notebook, JupyterLab, JupyterHub, etc.? + with JupyterLab, Jupyter Notebook, JupyterHub, etc.? - **Fit with the image purpose**: Does the feature match the theme of the stack in which it will be added? Would it fit better in a new community stack? - **Complexity of build/runtime configuration**: How many lines of code does the feature require diff --git a/docs/using/common.md b/docs/using/common.md index 790eb2d67..6e04e5f86 100644 --- a/docs/using/common.md +++ b/docs/using/common.md @@ -1,6 +1,6 @@ # Common Features -Except for `jupyter/docker-stacks-foundation`, a container launched from any Jupyter Docker Stacks image runs a Jupyter Server with a JupyterLab frontend. +Except for `jupyter/docker-stacks-foundation`, a container launched from any Jupyter Docker Stacks image runs a Jupyter Server with the JupyterLab frontend. The container does so by executing a `start-notebook.sh` script. This script configures the internal container environment and then runs `jupyter lab`, passing any command-line arguments received. @@ -8,9 +8,9 @@ This page describes the options supported by the startup script and how to bypas ## Jupyter Server Options -You can pass [Jupyter server options](https://jupyter-server.readthedocs.io/en/latest/operators/public-server.html) to the `start-notebook.sh` script when launching the container. +You can pass [Jupyter Server options](https://jupyter-server.readthedocs.io/en/latest/operators/public-server.html) to the `start-notebook.sh` script when launching the container. -1. For example, to secure the Notebook server with a [custom password](https://jupyter-server.readthedocs.io/en/latest/operators/public-server.html#preparing-a-hashed-password) +1. For example, to secure the Jupyter Server with a [custom password](https://jupyter-server.readthedocs.io/en/latest/operators/public-server.html#preparing-a-hashed-password) hashed using `jupyter_server.auth.passwd()` instead of the default token, you can run the following (this hash was generated for the `my-password` password): @@ -19,7 +19,7 @@ You can pass [Jupyter server options](https://jupyter-server.readthedocs.io/en/l start-notebook.sh --PasswordIdentityProvider.hashed_password='argon2:$argon2id$v=19$m=10240,t=10,p=8$JdAN3fe9J45NvK/EPuGCvA$O/tbxglbwRpOFuBNTYrymAEH6370Q2z+eS1eF4GM6Do' ``` -2. To set the [base URL](https://jupyter-server.readthedocs.io/en/latest/operators/public-server.html#running-the-notebook-with-a-customized-url-prefix) of the notebook server, you can run the following: +2. To set the [base URL](https://jupyter-server.readthedocs.io/en/latest/operators/public-server.html#running-the-notebook-with-a-customized-url-prefix) of the Jupyter Server, you can run the following: ```bash docker run -it --rm -p 8888:8888 jupyter/base-notebook \ @@ -28,7 +28,7 @@ You can pass [Jupyter server options](https://jupyter-server.readthedocs.io/en/l ## Docker Options -You may instruct the `start-notebook.sh` script to customize the container environment before launching the notebook server. +You may instruct the `start-notebook.sh` script to customize the container environment before launching the Server. You do so by passing arguments to the `docker run` command. ### User-related configurations @@ -133,7 +133,7 @@ or executables (`chmod +x`) to be run to the paths below: - `/usr/local/bin/start-notebook.d/` - handled **before** any of the standard options noted above are applied - `/usr/local/bin/before-notebook.d/` - handled **after** all the standard options noted above are applied - and ran right before the notebook server launches + and ran right before the Server launches See the `run-hooks` function in the [`jupyter/base-notebook start.sh`](https://github.com/jupyter/docker-stacks/blob/main/docker-stacks-foundation/start.sh) script for execution details. @@ -163,7 +163,7 @@ docker run -it --rm -p 8888:8888 \ --ServerApp.certfile=/etc/ssl/notebook.pem ``` -In either case, Jupyter Notebook expects the key and certificate to be a **base64 encoded text file**. +In either case, Jupyter Server expects the key and certificate to be a **base64 encoded text file**. The certificate file or PEM may contain one or more certificates (e.g., server, intermediate, and root). For additional information about using SSL, see the following: @@ -174,7 +174,7 @@ For additional information about using SSL, see the following: - The [`jupyter_server_config.py`](https://github.com/jupyter/docker-stacks/blob/main/base-notebook/jupyter_server_config.py) file for how this Docker image generates a self-signed certificate. - The [Jupyter Server documentation](https://jupyter-server.readthedocs.io/en/latest/operators/public-server.html#securing-a-jupyter-server) - for best practices about securing a public notebook server in general. + for best practices about securing a public Server in general. ## Alternative Commands @@ -184,31 +184,32 @@ JupyterLab, built on top of Jupyter Server, is now the default for all the image However, switching back to the classic notebook or using a different startup command is still possible. You can achieve this by setting the environment variable `DOCKER_STACKS_JUPYTER_CMD` at container startup. The table below shows some options. +Since `Jupyter Notebook v7` `jupyter-server` is used as a backend. -| `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 | +| `DOCKER_STACKS_JUPYTER_CMD` | Frontend | +| --------------------------- | ---------------- | +| `lab` (default) | JupyterLab | +| `notebook` | Jupyter Notebook | +| `nbclassic` | NbClassic | +| `server` | None | +| `retro`\* | 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. +- Any other valid `jupyter` subcommand that starts the Jupyter Application can be used. Example: ```bash -# Run Jupyter Notebook on Jupyter Server +# Run Jupyter Server with the Jupyter Notebook frontend docker run -it --rm \ -p 8888:8888 \ -e DOCKER_STACKS_JUPYTER_CMD=notebook \ jupyter/base-notebook # Executing the command: jupyter notebook ... -# Run Jupyter Notebook classic +# Use Jupyter NBClassic frontend docker run -it --rm \ -p 8888:8888 \ -e DOCKER_STACKS_JUPYTER_CMD=nbclassic \ diff --git a/docs/using/recipes.md b/docs/using/recipes.md index 57de144ad..7dbaee25e 100644 --- a/docs/using/recipes.md +++ b/docs/using/recipes.md @@ -145,7 +145,7 @@ docker run -it --rm \ Ref: -## Let's Encrypt a Notebook server +## Let's Encrypt a Server See the README for a basic automation here @@ -461,14 +461,14 @@ USER ${NB_UID} Credit: [britishbadger](https://github.com/britishbadger) from [docker-stacks/issues/369](https://github.com/jupyter/docker-stacks/issues/369) -## Run Jupyter Notebook/Lab inside an already secured environment (i.e., with no token) +## Run Server inside an already secured environment (i.e., with no token) (Adapted from [issue 728](https://github.com/jupyter/docker-stacks/issues/728)) The default security is very good. There are use cases, encouraged by containers, where the jupyter container and the system it runs within lie inside the security boundary. It is convenient to launch the server without a password or token in these use cases. -In this case, you should use the `start.sh` script to launch the server with no token: +In this case, you should use the `start-notebook.sh` script to launch the server with no token: For JupyterLab: diff --git a/docs/using/running.md b/docs/using/running.md index 125b5f025..923bbbd15 100644 --- a/docs/using/running.md +++ b/docs/using/running.md @@ -16,8 +16,8 @@ The following are some common patterns. **Example 1:** This command pulls the `jupyter/scipy-notebook` image tagged `2023-07-25` 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. -The server logs appear in the terminal and include a URL to the notebook server. +It then starts a container running Jupyter Server with the JupyterLab frontend and exposes the server on host port 8888. +The server logs appear in the terminal and include a URL to the server. ```bash docker run -it -p 8888:8888 jupyter/scipy-notebook:2023-07-25 @@ -33,7 +33,7 @@ docker run -it -p 8888:8888 jupyter/scipy-notebook:2023-07-25 # or http://127.0.0.1:8888/lab?token=f31f2625f13d131f578fced0fc76b81d10f6c629e92c7099 ``` -Pressing `Ctrl-C` twice shuts down the notebook server but leaves the container intact on disk for later restart or permanent deletion using commands like the following: +Pressing `Ctrl-C` twice shuts down the Server but leaves the container intact on disk for later restart or permanent deletion using commands like the following: ```bash # list containers @@ -54,14 +54,14 @@ docker rm 221331c047c4 **Example 2:** This command pulls the `jupyter/r-notebook` image tagged `2023-07-25` 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 10000. -The server logs appear in the terminal and include a URL to the notebook server, but with the internal container port (8888) instead of the correct host port (10000). +It then starts a container running Server and exposes the server on host port 10000. +The server logs appear in the terminal and include a URL to the Server, but with the internal container port (8888) instead of the correct host port (10000). ```bash docker run -it --rm -p 10000:8888 -v "${PWD}":/home/jovyan/work jupyter/r-notebook:2023-07-25 ``` -Pressing `Ctrl-C` twice shuts down the notebook server and immediately destroys the Docker container. +Pressing `Ctrl-C` twice shuts down the Server and immediately destroys the Docker container. New files and changes in `~/work` in the container will be preserved. Any other changes made in the container will be lost. @@ -78,7 +78,7 @@ where: - `--detach`: will run the container in detached mode -You can also use the following docker commands to see the port and notebook server token: +You can also use the following docker commands to see the port and Jupyter Server token: ```bash # get the random host port assigned to the container port 8888 @@ -131,8 +131,8 @@ subgidSize=$(( $(podman info --format "{{ range .Host.IDMappings.GIDMap }}+{{.Si ``` This command pulls the `docker.io/jupyter/r-notebook` image tagged `2023-07-25` from Docker Hub if it is not already present on the local host. -It then starts a container running a Jupyter Server and exposes the server on host port 10000. -The server logs appear in the terminal and include a URL to the notebook server, but with the internal container port (8888) instead of the correct host port (10000). +It then starts a container running a Jupyter Server with the JupyterLab frontend and exposes the server on host port 10000. +The server logs appear in the terminal and include a URL to the server, but with the internal container port (8888) instead of the correct host port (10000). ```bash podman run -it --rm -p 10000:8888 \ @@ -156,7 +156,7 @@ The `podman run` option `--userns=auto` will, for instance, not be possible to u The example could be improved by investigating more in detail which UIDs and GIDs need to be available in the container and then only map them. ``` -Pressing `Ctrl-C` twice shuts down the notebook server and immediately destroys the Docker container. +Pressing `Ctrl-C` twice shuts down the Server and immediately destroys the Docker container. New files and changes in `~/work` in the container will be preserved. Any other changes made in the container will be lost. diff --git a/docs/using/selecting.md b/docs/using/selecting.md index 300f8f05a..3723ba457 100644 --- a/docs/using/selecting.md +++ b/docs/using/selecting.md @@ -25,7 +25,7 @@ The following sections describe these images, including their contents, relation `jupyter/docker-stacks-foundation` is a small image supporting a majority of [options common across all core stacks](common.md). It is the basis for all other stacks on which Jupyter-related applications can be built (e.g., kernel-based containers, [nbclient](https://github.com/jupyter/nbclient) applications, etc.). -As such, it does not contain application-level software like Jupyter Notebook server, Jupyter Lab or Jupyter Hub. +As such, it does not contain application-level software like JupyterLab, Jupyter Notebook or JupyterHub. It contains: @@ -47,13 +47,13 @@ It contains: [Dockerfile commit history](https://github.com/jupyter/docker-stacks/commits/main/base-notebook/Dockerfile) | [Docker Hub image tags](https://hub.docker.com/r/jupyter/base-notebook/tags/) -`jupyter/base-notebook` adds base Jupyter server applications like Notebook, Jupyter Lab and Jupyter Hub +`jupyter/base-notebook` adds base Jupyter Applications like JupyterLab, Jupyter Notebook, JupyterHub and NBClassic and serves as the basis for all other stacks besides `jupyter/docker-stacks-foundation`. It contains: - Everything in `jupyter/docker-stacks-foundation` -- Minimally functional Jupyter Notebook server (e.g., no LaTeX support for saving notebooks as PDFs) +- Minimally functional Server (e.g., no LaTeX support for saving notebooks as PDFs) - `notebook`, `jupyterhub` and `jupyterlab` packages - A `start-notebook.sh` script as the default command - A `start-singleuser.sh` script useful for launching containers in JupyterHub diff --git a/examples/docker-compose/README.md b/examples/docker-compose/README.md index 5846aa7d8..26a585f42 100644 --- a/examples/docker-compose/README.md +++ b/examples/docker-compose/README.md @@ -86,8 +86,8 @@ NAME=your-notebook PORT=9001 WORK_VOLUME=our-work notebook/up.sh ### How do I run over HTTPS? -To run the notebook server with a self-signed certificate, pass the `--secure` option to the `up.sh` script. -You must also provide a password, which will be used to secure the notebook server. +To run the Jupyter Server with a self-signed certificate, pass the `--secure` option to the `up.sh` script. +You must also provide a password, which will be used to secure the Jupyter Server. You can specify the password by setting the `PASSWORD` environment variable, or by passing it to the `up.sh` script. ```bash diff --git a/examples/make-deploy/README.md b/examples/make-deploy/README.md index d4fc70fe1..0636612c8 100644 --- a/examples/make-deploy/README.md +++ b/examples/make-deploy/README.md @@ -20,7 +20,7 @@ make virtualbox-vm NAME=dev eval $(docker-machine env dev) # pull a docker stack and build a local image from it make image -# start a notebook server in a container +# start a Server in a container make notebook ``` diff --git a/minimal-notebook/Dockerfile b/minimal-notebook/Dockerfile index a998d2a10..29f3bddad 100644 --- a/minimal-notebook/Dockerfile +++ b/minimal-notebook/Dockerfile @@ -12,7 +12,7 @@ SHELL ["/bin/bash", "-o", "pipefail", "-c"] USER root -# Install all OS dependencies for fully functional notebook server +# Install all OS dependencies for fully functional Server RUN apt-get update --yes && \ apt-get install --yes --no-install-recommends \ # Common useful utilities diff --git a/tests/base-notebook/test_container_options.py b/tests/base-notebook/test_container_options.py index 6fa2e81fd..5fa28d891 100644 --- a/tests/base-notebook/test_container_options.py +++ b/tests/base-notebook/test_container_options.py @@ -12,8 +12,7 @@ def test_cli_args(container: TrackedContainer, http_client: requests.Session) -> None: - """Container should respect notebook server command line args - (e.g., disabling token security)""" + """Image should respect command line args (e.g., disabling token security)""" host_port = find_free_port() running_container = container.run_detached( command=["start-notebook.sh", "--IdentityProvider.token=''"], @@ -59,7 +58,7 @@ def test_unsigned_ssl( container: TrackedContainer, http_client: requests.Session ) -> None: """Container should generate a self-signed SSL certificate - and notebook server should use it to enable HTTPS. + and Jupyter Server should use it to enable HTTPS. """ host_port = find_free_port() running_container = container.run_detached( diff --git a/tests/base-notebook/test_notebook.py b/tests/base-notebook/test_notebook.py index 29c2bec74..3985990eb 100644 --- a/tests/base-notebook/test_notebook.py +++ b/tests/base-notebook/test_notebook.py @@ -8,7 +8,7 @@ def test_secured_server( container: TrackedContainer, http_client: requests.Session ) -> None: - """Notebook server should eventually request user login.""" + """Jupyter Server should eventually request user login.""" host_port = find_free_port() container.run_detached(ports={"8888/tcp": host_port}) resp = http_client.get(f"http://localhost:{host_port}")