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

📝 Structure improvements to common.md

Browse Source
This commit is contained in:
Tania Allard
2022-01-29 09:03:27 +00:00
parent 3152f60dea
commit f2a843071e
1 changed files with 25 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/using/common.md
View File

@@ -30,6 +30,8 @@ docker run -d -p 8888:8888 \
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 notebook server.
You do so by passing arguments to the `docker run` command. You do so by passing arguments to the `docker run` command.
### User-related configurations
- `-e NB_USER=<username>` - The desired username and associated home folder. - `-e NB_USER=<username>` - The desired username and associated home folder.
Default value is `jovyan`. Default value is `jovyan`.
Setting `NB_USER` refits the `jovyan` default user and ensures that the desired user has the correct file permissions Setting `NB_USER` refits the `jovyan` default user and ensures that the desired user has the correct file permissions
@@ -40,7 +42,9 @@ You do so by passing arguments to the `docker run` command.
Example usage: Example usage:
```bash ```bash
docker run --rm -it -p 8888:8888 -e NB_USER="my-username" -e CHOWN_HOME=yes -w "/home/${NB_USER}" --user root jupyter/base-notebook:latest docker run --rm -it -p 8888:8888 \
-e NB_USER="my-username" -e CHOWN_HOME=yes \
-w "/home/${NB_USER}" --user root jupyter/base-notebook:latest
``` ```
- `-e NB_UID=<numeric uid>` - Instructs the startup script to switch the numeric user ID of `${NB_USER}` to the given value. - `-e NB_UID=<numeric uid>` - Instructs the startup script to switch the numeric user ID of `${NB_USER}` to the given value.
@@ -48,7 +52,8 @@ You do so by passing arguments to the `docker run` command.
This feature is useful when mounting host volumes with specific owner permissions. This feature is useful when mounting host volumes with specific owner permissions.
For this option to take effect, you must run the container with `--user root`. For this option to take effect, you must run the container with `--user root`.
(The startup script will `su ${NB_USER}` after adjusting the user ID.) (The startup script will `su ${NB_USER}` after adjusting the user ID.)
You might consider using modern Docker options `--user` and `--group-add` instead. Instead, you might consider using the modern Docker-native options [`--user`](https://docs.docker.com/engine/reference/run/#user) and
[`--group-add`](https://docs.docker.com/engine/reference/run/#additional-groups) - see the last bullet in this section for more details.
See bullet points regarding `--user` and `--group-add`. See bullet points regarding `--user` and `--group-add`.
- `-e NB_GID=<numeric gid>` - Instructs the startup script to change the primary group of `${NB_USER}` to `${NB_GID}` - `-e NB_GID=<numeric gid>` - Instructs the startup script to change the primary group of `${NB_USER}` to `${NB_GID}`
@@ -57,16 +62,18 @@ You do so by passing arguments to the `docker run` command.
For this option to take effect, you must run the container with `--user root`. For this option to take effect, you must run the container with `--user root`.
(The startup script will `su ${NB_USER}` after adjusting the group ID.) (The startup script will `su ${NB_USER}` after adjusting the group ID.)
You might consider using modern Docker options `--user` and `--group-add` instead. You might consider using modern Docker options `--user` and `--group-add` instead.
See the last bullet below for details. See bullet points regarding `--user` and `--group-add`.
The user is added to supplemental group `users` (gid 100) in order to allow write access to the home directory and `/opt/conda`. The user is added to supplemental group `users` (gid 100) in order to allow write access to the home directory and `/opt/conda`.
If you override the user/group logic, ensure the user stays in group `users` if you want them to be able to modify files in the image. If you override the user/group logic, ensure the user stays in the group `users` if you want them to be able to modify files in the image.
- `-e NB_GROUP=<name>` - The name used for `${NB_GID}`, which defaults to `${NB_USER}`. - `-e NB_GROUP=<name>` - The name used for `${NB_GID}`, which defaults to `${NB_USER}`.
This is only used if `${NB_GID}` is specified and completely optional: there is only cosmetic effect. This is only used if `${NB_GID}` is specified and completely optional: there is only cosmetic effect.
## Permision-specific configurations
- `-e NB_UMASK=<umask>` - Configures Jupyter to use a different `umask` value from default, i.e. `022`. - `-e NB_UMASK=<umask>` - Configures Jupyter to use a different `umask` value from default, i.e. `022`.
For example, if setting `umask` to `002`, new files will be readable and writable by group members instead of just writable by the owner. For example, if setting `umask` to `002`, new files will be readable and writable by group members instead of the owner only.
Wikipedia has a good article about [`umask`](https://en.wikipedia.org/wiki/Umask). [Check this Wikipedia article](https://en.wikipedia.org/wiki/Umask) for an in-depth description of `umask` and suitable values for multiple needs.
While the default `umask` value should be sufficient for most use cases, you can set the `NB_UMASK` value to fit your requirements. While the default `umask` value should be sufficient for most use cases, you can set the `NB_UMASK` value to fit your requirements.
_Note that `NB_UMASK` when set only applies to the Jupyter process itself - _Note that `NB_UMASK` when set only applies to the Jupyter process itself -
you cannot use it to set a `umask` for additional files created during run-hooks. you cannot use it to set a `umask` for additional files created during run-hooks.
@@ -76,11 +83,11 @@ You do so by passing arguments to the `docker run` command.
- `-e CHOWN_HOME=yes` - Instructs the startup script to change the `${NB_USER}` home directory owner and group to the current value of `${NB_UID}` and `${NB_GID}`. - `-e CHOWN_HOME=yes` - Instructs the startup script to change the `${NB_USER}` home directory owner and group to the current value of `${NB_UID}` and `${NB_GID}`.
This change will take effect even if the user home directory is mounted from the host using `-v` as described below. This change will take effect even if the user home directory is mounted from the host using `-v` as described below.
The change is **not** applied recursively by default. The change is **not** applied recursively by default.
You can change modify the `chown` behavior by setting `CHOWN_HOME_OPTS` (e.g., `-e CHOWN_HOME_OPTS='-R'`). You can modify the `chown` behavior by setting `CHOWN_HOME_OPTS` (e.g., `-e CHOWN_HOME_OPTS='-R'`).
- `-e CHOWN_EXTRA="<some dir>,<some other dir>"` - Instructs the startup script to change the owner and group of each comma-separated container directory to the current value of `${NB_UID}` and `${NB_GID}`. - `-e CHOWN_EXTRA="<some dir>,<some other dir>"` - Instructs the startup script to change the owner and group of each comma-separated container directory to the current value of `${NB_UID}` and `${NB_GID}`.
The change is **not** applied recursively by default. The change is **not** applied recursively by default.
You can change modify the `chown` behavior by setting `CHOWN_EXTRA_OPTS` (e.g., `-e CHOWN_EXTRA_OPTS='-R'`). You can modify the `chown` behavior by setting `CHOWN_EXTRA_OPTS` (e.g., `-e CHOWN_EXTRA_OPTS='-R'`).
- `-e GRANT_SUDO=yes` - Instructs the startup script to grant the `NB_USER` user passwordless `sudo` capability. - `-e GRANT_SUDO=yes` - Instructs the startup script to grant the `NB_USER` user passwordless `sudo` capability.
You do **not** need this option to allow the user to `conda` or `pip` install additional packages. You do **not** need this option to allow the user to `conda` or `pip` install additional packages.
@@ -89,26 +96,20 @@ 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.) (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.** **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. ### Additional runtime configurations
- `-e GEN_CERT=yes` - Instructs the startup script to generate a self-signed SSL certificate and configure Jupyter Notebook to use it to accept encrypted HTTPS connections.
- `-e DOCKER_STACKS_JUPYTER_CMD=<jupyter command>` - Instructs the startup script to run `jupyter ${DOCKER_STACKS_JUPYTER_CMD}` instead of the default `jupyter lab` command. - `-e DOCKER_STACKS_JUPYTER_CMD=<jupyter command>` - 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. See [Switching back to the 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. This setting is helpful in container orchestration environments where setting environment variables is more straightforward than changing command line parameters.
- `-e RESTARTABLE=yes` - Runs Jupyter in a loop so that quitting Jupyter does not cause the container to exit. - `-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. This may be useful when installing extensions that require restarting Jupyter.
- `-v /some/host/folder/for/work:/home/jovyan/work` - Mounts a host machine directory as a folder in the container.
- `-v /some/host/folder/for/work:/home/jovyan/work` - Mounts a host machine directory as folder in the container. This configuration is useful for preserving notebooks and other work even after the container is destroyed.
Useful when you want to preserve notebooks and other work even after the container is destroyed.
**You must grant the within-container notebook user or group (`NB_UID` or `NB_GID`) write access to the host directory (e.g., `sudo chown 1000 /some/host/folder/for/work`).** **You must grant the within-container notebook user or group (`NB_UID` or `NB_GID`) write access to the host directory (e.g., `sudo chown 1000 /some/host/folder/for/work`).**
- `--user 5000 --group-add users` - Launches the container with a specific user ID and adds that user to the `users` group so that it can modify files in the default home directory and `/opt/conda`.
You can use these arguments as alternatives to setting `${NB_UID}` and `${NB_GID}`.
- `-e JUPYTER_ENV_VARS_TO_UNSET=ADMIN_SECRET_1,ADMIN_SECRET_2` - Unsets specified environment variables in the default startup script. - `-e JUPYTER_ENV_VARS_TO_UNSET=ADMIN_SECRET_1,ADMIN_SECRET_2` - Unsets specified environment variables in the default startup script.
The variables are unset after the hooks have executed but before the command provided to the startup script runs. The variables are unset after the hooks have been executed but before the command provided to the startup script runs.
- `-e NOTEBOOK_ARGS="--log-level='DEBUG' --dev-mode"` - Adds custom options to launch `jupyter lab` or `jupyter notebook`. This way, the user could use any option supported by `jupyter`.
- `-e NOTEBOOK_ARGS="--log-level='DEBUG' --dev-mode"` - Adds custom options to launch `jupyter lab` or `jupyter notebook`. This way any option, supported by `jupyter` could be used by the user.
## Startup Hooks ## Startup Hooks
@@ -124,7 +125,7 @@ script for execution details.
## SSL Certificates ## SSL Certificates
You may mount SSL keys and certificate files into a container and configure Jupyter Notebook to use them to accept HTTPS connections. You may mount SSL keys and certificate files into a container and configure the Jupyter Notebook to use them to accept HTTPS connections.
For example, to mount a host folder containing a `notebook.key` and `notebook.crt` and use them, you might run the following: For example, to mount a host folder containing a `notebook.key` and `notebook.crt` and use them, you might run the following:
```bash ```bash