hazza/docker-stacks
1
0
Fork 0
mirror of https://github.com/jupyter/docker-stacks.git synced 2025-10-12 04:22:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve wording in docs about Jupyter Notebook (#1949)

Browse Source 
* Improve wording in docs about Jupyter Notebook

* Fixes

* Better naming

* Apply suggestions from code review
This commit is contained in:
Ayaz Salikhov
2023-07-28 12:16:02 +04:00
committed by GitHub
parent 7c03161578
commit df06e24103
16 changed files with 61 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/ISSUE_TEMPLATE/bug_report.yml vendored
View File

@@ -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

19
README.md
View File

@@ -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

10
base-notebook/Dockerfile
View File

@@ -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 && \

3
base-notebook/jupyter_server_config.py
View File

@@ -53,7 +53,6 @@ if "GEN_CERT" in os.environ:
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))

4
binder/README.ipynb
View File

@@ -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,

4
docker-stacks-foundation/Dockerfile
View File

@@ -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

2
docs/contributing/features.md
View File

@@ -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

37
docs/using/common.md
View File

@@ -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 \

6
docs/using/recipes.md
View File

@@ -145,7 +145,7 @@ docker run -it --rm \
Ref: <https://github.com/jupyter/docker-stacks/issues/999>
## Let's Encrypt a Notebook server
## Let's Encrypt a Server
See the README for a basic automation here
<https://github.com/jupyter/docker-stacks/tree/main/examples/make-deploy>
@@ -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:

20
docs/using/running.md
View File

@@ -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.

6
docs/using/selecting.md
View File

@@ -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

4
examples/docker-compose/README.md
View File

@@ -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

2
examples/make-deploy/README.md
View File

@@ -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
```

2
minimal-notebook/Dockerfile
View File

@@ -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

5
tests/base-notebook/test_container_options.py
View File

@@ -12,8 +12,7 @@ LOGGER = logging.getLogger(__name__)
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(

2
tests/base-notebook/test_notebook.py
View File

@@ -8,7 +8,7 @@ from tests.conftest import TrackedContainer, find_free_port
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}")