mirror of
https://github.com/jupyter/docker-stacks.git
synced 2025-10-14 05:22:56 +00:00
Fix some minor issues in docs
This commit is contained in:
@@ -53,6 +53,6 @@ If there's agreement that the feature belongs in one or more of the core stacks:
|
|||||||
make build/<somestack>
|
make build/<somestack>
|
||||||
```
|
```
|
||||||
|
|
||||||
3. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request)(PR) with your changes.
|
3. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) (PR) with your changes.
|
||||||
4. Watch for GitHub to report a build success or failure for your PR on GitHub.
|
4. Watch for GitHub to report a build success or failure for your PR on GitHub.
|
||||||
5. Discuss changes with the maintainers and address any build issues.
|
5. Discuss changes with the maintainers and address any build issues.
|
||||||
|
@@ -1,6 +1,6 @@
|
|||||||
# Project Issues
|
# Project Issues
|
||||||
|
|
||||||
We appreciate your taking the time to report an issue you encountered using the Jupyter Docker Stacks.
|
We appreciate you taking the time to report an issue you encountered while using the Jupyter Docker Stacks.
|
||||||
Please review the following guidelines when reporting your problem.
|
Please review the following guidelines when reporting your problem.
|
||||||
|
|
||||||
- If you believe you've found a security vulnerability in any of the Jupyter projects included in Jupyter Docker Stacks images,
|
- If you believe you've found a security vulnerability in any of the Jupyter projects included in Jupyter Docker Stacks images,
|
||||||
|
@@ -27,10 +27,10 @@ pre-commit install
|
|||||||
### Run
|
### Run
|
||||||
|
|
||||||
Now, _pre-commit_ (and so configured hooks) will run automatically on `git commit` on each changed file.
|
Now, _pre-commit_ (and so configured hooks) will run automatically on `git commit` on each changed file.
|
||||||
However, it is also possible to trigger it against all files.
|
However, you can also run it against all files manually.
|
||||||
|
|
||||||
```{note}
|
```{note}
|
||||||
Hadolint pre-commit uses Docker to run, so `docker` should be running while running this command.
|
Hadolint pre-commit uses Docker to run, so `docker` should be running while executing this command.
|
||||||
```
|
```
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
@@ -58,7 +58,7 @@ The following rules are ignored by default for all images in the `.hadolint.yaml
|
|||||||
- [`DL3008`][dl3008]: System packages are always updated (`apt-get`) to the latest version.
|
- [`DL3008`][dl3008]: System packages are always updated (`apt-get`) to the latest version.
|
||||||
- [`DL3013`][dl3013]: We always install the latest packages using `pip`
|
- [`DL3013`][dl3013]: We always install the latest packages using `pip`
|
||||||
|
|
||||||
The preferred way to do it for other rules is to flag ignored ones in the `Dockerfile`.
|
The preferred way to ignore other rules is to flag them in the `Dockerfile`.
|
||||||
|
|
||||||
> It is also possible to ignore rules by using a special comment directly above the Dockerfile instruction you want to make an exception for.
|
> It is also possible to ignore rules by using a special comment directly above the Dockerfile instruction you want to make an exception for.
|
||||||
> Ignore rule comments look like `# hadolint ignore=DL3001,SC1081`.
|
> Ignore rule comments look like `# hadolint ignore=DL3001,SC1081`.
|
||||||
|
@@ -12,8 +12,8 @@ We pin major.minor version of Python, so this will stay the same even after invo
|
|||||||
## Outdated packages
|
## Outdated packages
|
||||||
|
|
||||||
To help identify packages that can be updated, you can use the following helper tool.
|
To help identify packages that can be updated, you can use the following helper tool.
|
||||||
It will list all the outdated packages installed in the `Dockerfile` --
|
It will list all the outdated packages installed in the `Dockerfile`.
|
||||||
dependencies are filtered to focus only on requested packages.
|
Dependencies are filtered to display only the requested packages.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
make check-outdated/base-notebook
|
make check-outdated/base-notebook
|
||||||
|
@@ -1,6 +1,6 @@
|
|||||||
# New Recipes
|
# New Recipes
|
||||||
|
|
||||||
We welcome contributions of [recipes](../using/recipes.md), and short examples of using, configuring, or extending the Docker Stacks for inclusion in the documentation site.
|
We welcome contributions of [recipes](../using/recipes.md), which are short examples of using, configuring, or extending the Docker Stacks for inclusion in the documentation site.
|
||||||
Follow the process below to add a new recipe:
|
Follow the process below to add a new recipe:
|
||||||
|
|
||||||
1. Open the `docs/using/recipes.md` source file.
|
1. Open the `docs/using/recipes.md` source file.
|
||||||
|
@@ -35,8 +35,8 @@ This will serve as both the git repository name and the part of the Docker image
|
|||||||
stack_name [my-jupyter-stack]:
|
stack_name [my-jupyter-stack]:
|
||||||
```
|
```
|
||||||
|
|
||||||
Enter the user or organization name under which this stack will reside on Quay.io.
|
Enter the user or organization name under which this stack will reside on Docker Hub.
|
||||||
You must have access to manage this Quay.io organization to push images here.
|
You must have access to manage this Docker Hub organization to push images here.
|
||||||
|
|
||||||
```text
|
```text
|
||||||
stack_org [my-project]:
|
stack_org [my-project]:
|
||||||
@@ -150,5 +150,5 @@ Finally, if you'd like to add a link to your project to this documentation site,
|
|||||||
1. Fork the [jupyter/docker-stacks](https://github.com/jupyter/docker-stacks) GitHub repository.
|
1. Fork the [jupyter/docker-stacks](https://github.com/jupyter/docker-stacks) GitHub repository.
|
||||||
2. Open the `docs/using/selecting.md` source file and locate the **Community Stacks** section in your fork.
|
2. Open the `docs/using/selecting.md` source file and locate the **Community Stacks** section in your fork.
|
||||||
3. Add a table entry with a link to your project, a binder link, and a short description of what your Docker image contains.
|
3. Add a table entry with a link to your project, a binder link, and a short description of what your Docker image contains.
|
||||||
4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request)(PR) with your changes.
|
4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) (PR) with your changes.
|
||||||
Maintainers will respond and work with you to address any formatting or content issues.
|
Maintainers will respond and work with you to address any formatting or content issues.
|
||||||
|
@@ -35,7 +35,7 @@ You do so by passing arguments to the `docker run` command.
|
|||||||
|
|
||||||
- `-e NB_USER=<username>` - The desired username and associated home folder.
|
- `-e NB_USER=<username>` - The desired username and associated home folder.
|
||||||
The default value is `jovyan`.
|
The 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` redefines the `jovyan` default user and ensures that the desired user has the correct file permissions
|
||||||
for the new home directory created at `/home/<username>`.
|
for the new home directory created at `/home/<username>`.
|
||||||
For this option to take effect, you **must** run the container with `--user root`, set the working directory `-w "/home/<username>"`
|
For this option to take effect, you **must** run the container with `--user root`, set the working directory `-w "/home/<username>"`
|
||||||
and set the environment variable `-e CHOWN_HOME=yes`.
|
and set the environment variable `-e CHOWN_HOME=yes`.
|
||||||
@@ -90,7 +90,7 @@ You do so by passing arguments to the `docker run` command.
|
|||||||
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}
|
```{note}
|
||||||
`NB_UMASK` when set only applies to the Jupyter process itself -
|
When `NB_UMASK` is set, it only applies to the Jupyter process itself -
|
||||||
you cannot use it to set a `umask` for additional files created during `run-hooks.sh`.
|
you cannot use it to set a `umask` for additional files created during `run-hooks.sh`.
|
||||||
For example, via `pip` or `conda`.
|
For example, via `pip` or `conda`.
|
||||||
If you need to set a `umask` for these, you **must** set the `umask` value for each command.
|
If you need to set a `umask` for these, you **must** set the `umask` value for each command.
|
||||||
@@ -122,7 +122,7 @@ You do so by passing arguments to the `docker run` command.
|
|||||||
- `-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 installing 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 a folder in the container.
|
||||||
This configuration is useful for preserving notebooks and other work even after the container is destroyed.
|
This configuration is useful for preserving notebooks and other work even after the container has been 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`).**
|
||||||
- `-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 been 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.
|
||||||
@@ -136,7 +136,7 @@ You do so by passing arguments to the `docker run` command.
|
|||||||
You can further customize the container environment by adding shell scripts (`*.sh`) to be sourced
|
You can further customize the container environment by adding shell scripts (`*.sh`) to be sourced
|
||||||
or executables (`chmod +x`) to be run to the paths below:
|
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/start-notebook.d/` - handled **before** any of the standard options noted above is applied
|
||||||
- `/usr/local/bin/before-notebook.d/` - handled **after** all 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 Server launches
|
and ran right before the Server launches
|
||||||
|
|
||||||
@@ -246,7 +246,7 @@ This script is handy when you derive a new Dockerfile from this image and instal
|
|||||||
|
|
||||||
The default Python 3.x [Conda environment](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html) resides in `/opt/conda`.
|
The default Python 3.x [Conda environment](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html) resides in `/opt/conda`.
|
||||||
The `/opt/conda/bin` directory is part of the default `jovyan` user's `${PATH}`.
|
The `/opt/conda/bin` directory is part of the default `jovyan` user's `${PATH}`.
|
||||||
That directory is also searched for binaries when run using `sudo` (`sudo my_binary` will search for `my_binary` in `/opt/conda/bin/`
|
That directory is also searched for binaries when run using `sudo` (`sudo my_binary` will search for `my_binary` in `/opt/conda/bin/`).
|
||||||
|
|
||||||
The `jovyan` user has full read/write access to the `/opt/conda` directory.
|
The `jovyan` user has full read/write access to the `/opt/conda` directory.
|
||||||
You can use either `mamba`, `pip`, or `conda` (`mamba` is recommended) to install new packages without any additional permissions.
|
You can use either `mamba`, `pip`, or `conda` (`mamba` is recommended) to install new packages without any additional permissions.
|
||||||
|
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
## How to persist user data
|
## How to persist user data
|
||||||
|
|
||||||
There are 2 types of data, which you might want to persist.
|
There are two types of data, which you might want to persist.
|
||||||
|
|
||||||
1. If you want to persist your environment (i.e. packages installed by `mamba`, `conda`, `pip`, `apt-get`, and so on),
|
1. If you want to persist your environment (i.e. packages installed by `mamba`, `conda`, `pip`, `apt-get`, and so on),
|
||||||
then you should create an inherited image and install packages only once while building your Dockerfile.
|
then you should create an inherited image and install packages only once while building your Dockerfile.
|
||||||
@@ -22,7 +22,7 @@ There are 2 types of data, which you might want to persist.
|
|||||||
You can find [an example of using a bind mount here](./running.md#example-2).
|
You can find [an example of using a bind mount here](./running.md#example-2).
|
||||||
There is also [a mount troubleshooting section](./troubleshooting.md#permission-denied-when-mounting-volumes) if you experience any issues.
|
There is also [a mount troubleshooting section](./troubleshooting.md#permission-denied-when-mounting-volumes) if you experience any issues.
|
||||||
|
|
||||||
## Why we do not add your favorite package
|
## Why we don't add your favorite package
|
||||||
|
|
||||||
We have lots of users with different packages they want to use.
|
We have lots of users with different packages they want to use.
|
||||||
Adding them all is impossible, so we have several images to choose from.
|
Adding them all is impossible, so we have several images to choose from.
|
||||||
|
@@ -60,7 +60,7 @@ docker run -it --rm \
|
|||||||
The default version of `Python` that ships with the image may not be the version you want.
|
The default version of `Python` that ships with the image may not be the version you want.
|
||||||
The instructions below permit adding a conda environment with a different `Python` version and making it accessible to Jupyter.
|
The instructions below permit adding a conda environment with a different `Python` version and making it accessible to Jupyter.
|
||||||
You may also use older images like `jupyter/base-notebook:python-3.10`.
|
You may also use older images like `jupyter/base-notebook:python-3.10`.
|
||||||
A list of all tags can be found [here](https://github.com/jupyter/docker-stacks/wiki)
|
A list of all tags can be found [here](https://github.com/jupyter/docker-stacks/wiki).
|
||||||
|
|
||||||
```{literalinclude} recipe_code/custom_environment.dockerfile
|
```{literalinclude} recipe_code/custom_environment.dockerfile
|
||||||
:language: docker
|
:language: docker
|
||||||
@@ -400,7 +400,7 @@ docker run -it --rm \
|
|||||||
## Enable nbclassic-extension spellchecker for markdown (or any other nbclassic-extension)
|
## Enable nbclassic-extension spellchecker for markdown (or any other nbclassic-extension)
|
||||||
|
|
||||||
```{note}
|
```{note}
|
||||||
This recipe only works for NBCassic with Jupyter Notebook < 7.
|
This recipe only works for NBClassic with Jupyter Notebook < 7.
|
||||||
It is recommended to use [jupyterlab-spellchecker](https://github.com/jupyterlab-contrib/spellchecker) in modern environments.
|
It is recommended to use [jupyterlab-spellchecker](https://github.com/jupyterlab-contrib/spellchecker) in modern environments.
|
||||||
```
|
```
|
||||||
|
|
||||||
|
@@ -244,7 +244,7 @@ It contains:
|
|||||||
We provide CUDA accelerated versions of the `pytorch-notebook` and `tensorflow-notebook` images.
|
We provide CUDA accelerated versions of the `pytorch-notebook` and `tensorflow-notebook` images.
|
||||||
Prepend a CUDA prefix (versioned prefix like `cuda12-` for `pytorch-notebook` or just `cuda-` for `tensorflow-notebook`) to the image tag
|
Prepend a CUDA prefix (versioned prefix like `cuda12-` for `pytorch-notebook` or just `cuda-` for `tensorflow-notebook`) to the image tag
|
||||||
to allow PyTorch or TensorFlow operations to use compatible NVIDIA GPUs for accelerated computation.
|
to allow PyTorch or TensorFlow operations to use compatible NVIDIA GPUs for accelerated computation.
|
||||||
We only build `pytorch-notebook` for last two major versions of CUDA.
|
We only build `pytorch-notebook` for the last two major versions of CUDA.
|
||||||
The `tensorflow-notebook` image only supports the latest CUDA version listed in the [officially tested build configurations](https://www.tensorflow.org/install/source#gpu).
|
The `tensorflow-notebook` image only supports the latest CUDA version listed in the [officially tested build configurations](https://www.tensorflow.org/install/source#gpu).
|
||||||
|
|
||||||
For example, you could use the image `quay.io/jupyter/pytorch-notebook:cuda12-python-3.11.8` or `quay.io/jupyter/tensorflow-notebook:cuda-latest`.
|
For example, you could use the image `quay.io/jupyter/pytorch-notebook:cuda12-python-3.11.8` or `quay.io/jupyter/tensorflow-notebook:cuda-latest`.
|
||||||
|
@@ -77,7 +77,7 @@ The following sections cover a few of these scenarios and how to fix them.
|
|||||||
- If you are mounting your volume inside the `/home/` directory, you can use the `-e CHOWN_HOME=yes` and `CHOWN_HOME_OPTS="-R"` flags
|
- If you are mounting your volume inside the `/home/` directory, you can use the `-e CHOWN_HOME=yes` and `CHOWN_HOME_OPTS="-R"` flags
|
||||||
instead of the `-e CHOWN_EXTRA` and `-e CHOWN_EXTRA_OPTS` in the example above.
|
instead of the `-e CHOWN_EXTRA` and `-e CHOWN_EXTRA_OPTS` in the example above.
|
||||||
- This solution should work in most cases where you have created a docker volume
|
- This solution should work in most cases where you have created a docker volume
|
||||||
(i.e. using the [`docker volume create --name <my-volume>`command](https://docs.docker.com/engine/storage/volumes/#create-and-manage-volumes)) and mounted it using the `-v` flag in `docker run`.
|
(i.e. using the [`docker volume create --name <my-volume>` command](https://docs.docker.com/engine/storage/volumes/#create-and-manage-volumes)) and mounted it using the `-v` flag in `docker run`.
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **Matching the container's UID/GID with the host's**
|
2. **Matching the container's UID/GID with the host's**
|
||||||
@@ -108,7 +108,7 @@ The following sections cover a few of these scenarios and how to fix them.
|
|||||||
|
|
||||||
where:
|
where:
|
||||||
|
|
||||||
- `NB_IUD` and `NB_GID` should match the local user's UID and GID.
|
- `NB_UID` and `NB_GID` should match the local user's UID and GID.
|
||||||
- You **must** use `--user root` to ensure that the `UID` and `GID` are updated at runtime.
|
- You **must** use `--user root` to ensure that the `UID` and `GID` are updated at runtime.
|
||||||
|
|
||||||
````{admonition} Additional notes
|
````{admonition} Additional notes
|
||||||
@@ -273,7 +273,7 @@ conda config --show default_channels
|
|||||||
You can install packages from other conda channels (e.g. `bioconda`) by disabling the `channel_priority` setting:
|
You can install packages from other conda channels (e.g. `bioconda`) by disabling the `channel_priority` setting:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# install by disabling channel priority at еру command level
|
# install by disabling channel priority at the command level
|
||||||
conda install --no-channel-priority -c bioconda bioconductor-geoquery
|
conda install --no-channel-priority -c bioconda bioconductor-geoquery
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Reference in New Issue
Block a user