mirror of
https://github.com/jupyter/docker-stacks.git
synced 2025-10-17 23:12:56 +00:00
Migrate start-notebook & start-singleuser to python (#2006)
* Migrate start-notebook.sh to bash Based on > Stop using bash, haha 👍 from https://github.com/jupyter/docker-stacks/issues/1532. If there's more apetite for this, I'll try to migrate `start.sh` and `start-singleuser.sh` as well - I think they should all be merged together. We can remove the `.sh` suffixes for accuracy, and keep symlinks in so old config still works. Since the shebang is what is used to launch the correct interpreter, the `.sh` doesn't matter. Will help fix https://github.com/jupyter/docker-stacks/issues/1532, as I believe all those things are going to be easier to do from python than bash * Rename start-notebook.sh to start-notebook * Cleanup start-notebook a little * Fix typo * Migrate start-singleuser as well * Remove unused import * Run symlink commands as root * Combine repetitive RUN commands * Remove multiple args to env -u can not be set by shebang, we must set the env var instead * Fix conditional inversion Co-authored-by: Ayaz Salikhov <mathbunnyru@users.noreply.github.com> * Fix how start-singleuser is exec'd * Actually call jupyterhub-singleuser in start-singleuser * Pass through any additional args we get * Put .py suffix on the start-* scripts * Add .sh shims for the start-* scripts * Document start-notebook.sh and start-singleuser.sh * Partially test start-notebook.sh * Reflow warning docs Co-authored-by: Ayaz Salikhov <mathbunnyru@users.noreply.github.com> --------- Co-authored-by: Ayaz Salikhov <mathbunnyru@users.noreply.github.com>
This commit is contained in:
Yuvi Panda
@@ -1,14 +1,14 @@
|
||||
# Common Features
|
||||
|
||||
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.
|
||||
The container does so by executing a `start-notebook.py` script.
|
||||
This script configures the internal container environment and then runs `jupyter lab`, passing any command-line arguments received.
|
||||
|
||||
This page describes the options supported by the startup script and how to bypass it to run alternative commands.
|
||||
|
||||
## 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.py` script when launching the container.
|
||||
|
||||
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,
|
||||
@@ -16,19 +16,19 @@ You can pass [Jupyter Server options](https://jupyter-server.readthedocs.io/en/l
|
||||
|
||||
```bash
|
||||
docker run -it --rm -p 8888:8888 jupyter/base-notebook \
|
||||
start-notebook.sh --PasswordIdentityProvider.hashed_password='argon2:$argon2id$v=19$m=10240,t=10,p=8$JdAN3fe9J45NvK/EPuGCvA$O/tbxglbwRpOFuBNTYrymAEH6370Q2z+eS1eF4GM6Do'
|
||||
start-notebook.py --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 Jupyter Server, you can run the following:
|
||||
|
||||
```bash
|
||||
docker run -it --rm -p 8888:8888 jupyter/base-notebook \
|
||||
start-notebook.sh --ServerApp.base_url=/customized/url/prefix/
|
||||
start-notebook.py --ServerApp.base_url=/customized/url/prefix/
|
||||
```
|
||||
|
||||
## Docker Options
|
||||
|
||||
You may instruct the `start-notebook.sh` script to customize the container environment before launching the Server.
|
||||
You may instruct the `start-notebook.py` script to customize the container environment before launching the Server.
|
||||
You do so by passing arguments to the `docker run` command.
|
||||
|
||||
### User-related configurations
|
||||
@@ -104,7 +104,7 @@ You do so by passing arguments to the `docker run` command.
|
||||
You do **not** need this option to allow the user to `conda` or `pip` install additional packages.
|
||||
This option is helpful for cases when you wish to give `${NB_USER}` the ability to install OS packages with `apt` or modify other root-owned files in the container.
|
||||
You **must** run the container with `--user root` for this option to take effect.
|
||||
(The `start-notebook.sh` script will `su ${NB_USER}` after adding `${NB_USER}` to sudoers.)
|
||||
(The `start-notebook.py` 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 runs on an isolated host.**
|
||||
|
||||
### Additional runtime configurations
|
||||
@@ -147,7 +147,7 @@ For example, to mount a host folder containing a `notebook.key` and `notebook.cr
|
||||
docker run -it --rm -p 8888:8888 \
|
||||
-v /some/host/folder:/etc/ssl/notebook \
|
||||
jupyter/base-notebook \
|
||||
start-notebook.sh \
|
||||
start-notebook.py \
|
||||
--ServerApp.keyfile=/etc/ssl/notebook/notebook.key \
|
||||
--ServerApp.certfile=/etc/ssl/notebook/notebook.crt
|
||||
```
|
||||
@@ -159,7 +159,7 @@ For example:
|
||||
docker run -it --rm -p 8888:8888 \
|
||||
-v /some/host/folder/notebook.pem:/etc/ssl/notebook.pem \
|
||||
jupyter/base-notebook \
|
||||
start-notebook.sh \
|
||||
start-notebook.py \
|
||||
--ServerApp.certfile=/etc/ssl/notebook.pem
|
||||
```
|
||||
|
||||
@@ -220,7 +220,7 @@ docker run -it --rm \
|
||||
|
||||
### `start.sh`
|
||||
|
||||
The `start-notebook.sh` script inherits most of its option handling capability from a more generic `start.sh` script.
|
||||
The `start-notebook.py` script inherits most of its option handling capability from a more generic `start.sh` script.
|
||||
The `start.sh` script supports all the features described above but allows you to specify an arbitrary command to execute.
|
||||
For example, to run the text-based `ipython` console in a container, do the following:
|
||||
|
||||
|
||||
@@ -375,14 +375,14 @@ Credit: [britishbadger](https://github.com/britishbadger) from [docker-stacks/is
|
||||
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-notebook.sh` script to launch the server with no token:
|
||||
In this case, you should use the `start-notebook.py` script to launch the server with no token:
|
||||
|
||||
For JupyterLab:
|
||||
|
||||
```bash
|
||||
docker run -it --rm \
|
||||
jupyter/base-notebook \
|
||||
start-notebook.sh --IdentityProvider.token=''
|
||||
start-notebook.py --IdentityProvider.token=''
|
||||
```
|
||||
|
||||
For Jupyter Notebook:
|
||||
@@ -391,7 +391,7 @@ For Jupyter Notebook:
|
||||
docker run -it --rm \
|
||||
-e DOCKER_STACKS_JUPYTER_CMD=notebook \
|
||||
jupyter/base-notebook \
|
||||
start-notebook.sh --IdentityProvider.token=''
|
||||
start-notebook.py --IdentityProvider.token=''
|
||||
```
|
||||
|
||||
## Enable nbclassic-extension spellchecker for markdown (or any other nbclassic-extension)
|
||||
|
||||
@@ -69,7 +69,7 @@ Any other changes made in the container will be lost.
|
||||
By default, [jupyter's root_dir](https://jupyter-server.readthedocs.io/en/latest/other/full-config.html) is `/home/jovyan`.
|
||||
So, new notebooks will be saved there, unless you change the directory in the file browser.
|
||||
|
||||
To change the default directory, you will need to specify `ServerApp.root_dir` by adding this line to previous command: `start-notebook.sh --ServerApp.root_dir=/home/jovyan/work`.
|
||||
To change the default directory, you will need to specify `ServerApp.root_dir` by adding this line to previous command: `start-notebook.py --ServerApp.root_dir=/home/jovyan/work`.
|
||||
```
|
||||
|
||||
### Example 3
|
||||
|
||||
@@ -56,10 +56,17 @@ It contains:
|
||||
- Everything in `jupyter/docker-stacks-foundation`
|
||||
- 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
|
||||
- A `start-notebook.py` script as the default command
|
||||
- A `start-singleuser.py` script useful for launching containers in JupyterHub
|
||||
- Options for a self-signed HTTPS certificate
|
||||
|
||||
```{warning}
|
||||
`jupyter/base-notebook` also contains `start-notebook.sh` and `start-singleuser.sh` files to maintain backwards compatibility.
|
||||
External config that explicitly refers to those files should instead
|
||||
update to refer to `start-notebook.py` and `start-singleuser.py`.
|
||||
The shim `.sh` files will be removed at some future date.
|
||||
```
|
||||
|
||||
### jupyter/minimal-notebook
|
||||
|
||||
[Source on GitHub](https://github.com/jupyter/docker-stacks/tree/main/images/minimal-notebook) |
|
||||
|
||||
Reference in New Issue
Block a user