hazza/docker-stacks
1
0
Fork 0
mirror of https://github.com/jupyter/docker-stacks.git synced 2025-10-17 23:12:56 +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

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