From 55ced46f1e8bc00ba3a4f08bfce9f902cf6cedda Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Fri, 4 Feb 2022 12:48:04 +0300 Subject: [PATCH 01/30] Only install system packages which are useful for many people --- minimal-notebook/Dockerfile | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/minimal-notebook/Dockerfile b/minimal-notebook/Dockerfile index 4b1a4939..ba031abc 100644 --- a/minimal-notebook/Dockerfile +++ b/minimal-notebook/Dockerfile @@ -19,13 +19,9 @@ RUN apt-get update --yes && \ vim-tiny \ # git-over-ssh openssh-client \ - # TODO: check if these are needed and describe - inkscape \ - libsm6 \ - libxext-dev \ - libxrender1 \ - lmodern \ - netcat \ + # less is needed to run help in R + # see: https://github.com/jupyter/docker-stacks/issues/1588 + less \ # nbconvert dependencies # https://nbconvert.readthedocs.io/en/latest/install.html#installing-tex texlive-xetex \ From 37d349d90fea999617b10b370aff85c0d411a727 Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Fri, 4 Feb 2022 13:17:01 +0300 Subject: [PATCH 02/30] Add inkscape back with comment --- minimal-notebook/Dockerfile | 2 ++ 1 file changed, 2 insertions(+) diff --git a/minimal-notebook/Dockerfile b/minimal-notebook/Dockerfile index ba031abc..d381cd89 100644 --- a/minimal-notebook/Dockerfile +++ b/minimal-notebook/Dockerfile @@ -17,6 +17,8 @@ RUN apt-get update --yes && \ tzdata \ unzip \ vim-tiny \ + # Inkscape shall be installed to be able to convert SVG files + inkscape \ # git-over-ssh openssh-client \ # less is needed to run help in R From 9915db3098e2337239bbed3492fd38482269f537 Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Fri, 4 Feb 2022 13:17:21 +0300 Subject: [PATCH 03/30] Better comment --- minimal-notebook/Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/minimal-notebook/Dockerfile b/minimal-notebook/Dockerfile index d381cd89..11ec31e4 100644 --- a/minimal-notebook/Dockerfile +++ b/minimal-notebook/Dockerfile @@ -17,7 +17,7 @@ RUN apt-get update --yes && \ tzdata \ unzip \ vim-tiny \ - # Inkscape shall be installed to be able to convert SVG files + # Inkscape is installed to be able to convert SVG files inkscape \ # git-over-ssh openssh-client \ From f32be5097a55ab9085fc9409e93b738819a32a5b Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Fri, 4 Feb 2022 15:45:26 +0300 Subject: [PATCH 04/30] Separate docs environment (#1600) * Separate env for docs --- .github/workflows/docker-amd64.yml | 2 +- .github/workflows/docker.yml | 2 +- .github/workflows/sphinx.yml | 6 +++--- .readthedocs.yaml | 2 +- Makefile | 5 ++++- docs/contributing/lint.md | 2 +- docs/maintaining/tasks.md | 2 +- requirements-dev.txt | 3 --- requirements-docs.txt | 3 +++ 9 files changed, 15 insertions(+), 12 deletions(-) create mode 100644 requirements-docs.txt diff --git a/.github/workflows/docker-amd64.yml b/.github/workflows/docker-amd64.yml index c95ad8b2..b853e4a4 100644 --- a/.github/workflows/docker-amd64.yml +++ b/.github/workflows/docker-amd64.yml @@ -66,7 +66,7 @@ jobs: - name: Install Dev Dependencies run: | python -m pip install --upgrade pip - make -C main dev-env + make -C main install-dev-env - name: Build Docker Images run: make -C main build-all diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index 232625e4..be1d1eb0 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -83,7 +83,7 @@ jobs: - name: Install Dev Dependencies run: | python -m pip install --upgrade pip - make -C main dev-env + make -C main install-dev-env - name: Build Docker Images run: make -C main build-all-multi diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 2ceca229..617bafe4 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -7,7 +7,7 @@ on: - "docs/**" - ".readthedocs.yaml" - - "requirements-dev.txt" + - "requirements-docs.txt" push: branches: - main @@ -17,7 +17,7 @@ on: - "docs/**" - ".readthedocs.yaml" - - "requirements-dev.txt" + - "requirements-docs.txt" workflow_dispatch: jobs: @@ -39,7 +39,7 @@ jobs: - name: Install Dev Dependencies run: | python -m pip install --upgrade pip - make dev-env + make install-docs-env - name: Build Documentation run: make docs diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 678760a9..406a33fa 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -27,4 +27,4 @@ sphinx: # Optionally declare the Python requirements required to build your docs python: install: - - requirements: requirements-dev.txt + - requirements: requirements-docs.txt diff --git a/Makefile b/Makefile index d7ad2de7..4406e785 100644 --- a/Makefile +++ b/Makefile @@ -132,7 +132,7 @@ dev/%: PORT?=8888 dev/%: ## run a foreground container for a stack docker run -it --rm -p $(PORT):8888 $(DARGS) $(OWNER)/$(notdir $@) -dev-env: ## install libraries required to build docs and run tests +install-dev-env: ## install libraries required to build images and run tests @pip install -r requirements-dev.txt @@ -140,6 +140,9 @@ dev-env: ## install libraries required to build docs and run tests docs: ## build HTML documentation sphinx-build docs/ docs/_build/ +install-docs-env: ## install libraries required to build docs + @pip install -r requirements-docs.txt + hook/%: WIKI_PATH?=../wiki diff --git a/docs/contributing/lint.md b/docs/contributing/lint.md index 1c22417e..c5862bc4 100644 --- a/docs/contributing/lint.md +++ b/docs/contributing/lint.md @@ -13,7 +13,7 @@ This can be achieved by using the generic task used to install all Python develo ```sh # Install all development dependencies for the project -make dev-env +make install-dev-env # It can also be installed directly pip install pre-commit ``` diff --git a/docs/maintaining/tasks.md b/docs/maintaining/tasks.md index f490bc2a..eb569b4c 100644 --- a/docs/maintaining/tasks.md +++ b/docs/maintaining/tasks.md @@ -24,7 +24,7 @@ Pushing `Run Workflow` button will trigger this process. ## Adding a New Core Image to Docker Hub ```{note} -In general, we do not add new core images and ask contributors to either create a [recipe](../using/recipes.md) or [community stack](../using/stacks.md). +In general, we do not add new core images and ask contributors to either create a [recipe](../using/recipes.md) or [community stack](../contributing/stacks.md). ``` When there's a new stack definition, do the following before merging the PR with the new stack: diff --git a/requirements-dev.txt b/requirements-dev.txt index 73ca5eb8..23cb6bcc 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,10 +1,7 @@ docker -myst-parser packaging plumbum pre-commit pytest requests -sphinx -sphinx-copybutton tabulate diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 00000000..ba6908ee --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1,3 @@ +myst-parser +sphinx +sphinx-copybutton From d0bd1de23f483f351caa79b1867e13669884471a Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Wed, 26 Jan 2022 10:46:12 +0000 Subject: [PATCH 05/30] =?UTF-8?q?=F0=9F=93=9DAdd=20troubleshooting=20page?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/using/troubleshooting.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/using/troubleshooting.md diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md new file mode 100644 index 00000000..dcd86c48 --- /dev/null +++ b/docs/using/troubleshooting.md @@ -0,0 +1,35 @@ +# Troubleshooting Common Problems + +When troubleshooting, you may see unexpected behaviors or receive an error message. This section provide links for identifying the cause of the problem and how to resolve it. + +## Permission Issues + +### Permission denied when mounting local folders + +If you tried to start a Docker container while mounting a local volume and you get a `Permission denied` error: + +* It is likely you are trying to start your container with a command similar to: + + ```bash + docker run -it --rm \ + -p 8888:8888 \ + -v my-local-dir:/home/jovyan/work jupyter/datascience-notebook + ``` + +Here are a few things you can try: + +1. Use absolute paths when using the `-v` flag: + + ```bash + -v $(pwd)/my-local-dir:/home/jovyan/work + ``` + +2. Add the following arguments to your command: + + ```bash + docker run -it --rm \ + -p 8888:8888 \ + -e NB_UID=1000 \ + -e CHOWN_HOME=yes \ + -v my-local-dir:/home/jovyan/work jupyter/datascience-notebook + ``` From 0444595d2f9970a80a34465611144353b1ef2b87 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 31 Jan 2022 21:21:37 +0000 Subject: [PATCH 06/30] Fix structure --- docs/using/troubleshooting.md | 74 +++++++++++++++++++++++++---------- 1 file changed, 54 insertions(+), 20 deletions(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index dcd86c48..f4042df1 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -1,35 +1,69 @@ # Troubleshooting Common Problems -When troubleshooting, you may see unexpected behaviors or receive an error message. This section provide links for identifying the cause of the problem and how to resolve it. +When troubleshooting, you may see unexpected behaviors or receive an error message. This section provides links for identifying the cause of the problem and how to resolve it. ## Permission Issues -### Permission denied when mounting local folders +### Permission denied when mounting local directories -If you tried to start a Docker container while mounting a local volume and you get a `Permission denied` error: +If you are running a Docker container while mounting a local volume or host directory using the `-v` flag like so: -* It is likely you are trying to start your container with a command similar to: +```bash + docker run -it --rm \ + -v :/home/jovyan/work jupyter/datascience-notebook +``` + +you might face permissions issues when trying to access the mounted directory: + +```bash +$ ls -l foo.txt +-rw-r--r-- 1 root root 0 Jan 131 10:36 foo.txt +$ echo hi > foo.txt +-bash: foo.txt: Permission denied +``` + +**Some things to try:** + +1. Matching the container's UID/GID with the host's + + Docker handles mounting host directories differently to mounting volumes, even though the syntax is basically the same (i.e. `-v`). + + When you initialize a Docker container using the flag `-v` the host directories are bind mounted directly into the container. + Therefore, the permissions and ownership are **exactly the same** as the ones in your local host (including user ids) which may result in permissions errors like the one displayed above. + + Suppose your local user has a `UID` of `1000`. To fix the UID discrepancies between your local directories and the container's + directoriess, you need to set `NB_UID` and `NB_GID` to match the that of the local user: + + ```bash + docker run -it --rm \ + -e NB_UID=1000 \ + -e NB_GID=1000 \ + --user root \ + -v :/home/jovyan/work jupyter/datascience-notebook + ``` + + Note that you need to use the flag `--user root` to ensure that the `UID` is updated at runtime. + + The caveat with this approach is that since these changes are applied at runtime, you will need to to re-run the same + command with the appropriate flags and environment variables if you need to recreate the container. + +**Other tips:** + +- Use absolute paths when using the `-v` flag: ```bash - docker run -it --rm \ - -p 8888:8888 \ - -v my-local-dir:/home/jovyan/work jupyter/datascience-notebook + -v $(PWD)/:/home/jovyan/work ``` -Here are a few things you can try: + in this example, we use the syntax `$(PWD)` which will be replaced with the full path to the current directory. The destination path should also be an absolute path starting with a `/` such as `home/jovyan/work`. -1. Use absolute paths when using the `-v` flag: - - ```bash - -v $(pwd)/my-local-dir:/home/jovyan/work - ``` - -2. Add the following arguments to your command: +- You might want to consider using the Docker native `--user ` and `--group-add `: ```bash - docker run -it --rm \ - -p 8888:8888 \ - -e NB_UID=1000 \ - -e CHOWN_HOME=yes \ - -v my-local-dir:/home/jovyan/work jupyter/datascience-notebook + # note this will use the same UID from the user calling the command + docker run -it --rm \ + --user "$(id -u)" --group-add users \ # $(id -u) prints the UID of the user that called docker run + -v :/home/jovyan/work jupyter/datascience-notebook ``` + + this command will not only launch the container with a specific user UID, but also add the that user to the `users` group so that it can modify the files in the default `/home` and `/opt/conda` directories. From 45b396b523c42b749eb925562d06c96ce1a5d219 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Tue, 1 Feb 2022 16:21:40 +0000 Subject: [PATCH 07/30] :memo: Add user changes section --- docs/index.rst | 1 + docs/using/troubleshooting.md | 165 ++++++++++++++++++++++++++++------ test/foo | 1 + 3 files changed, 141 insertions(+), 26 deletions(-) create mode 100644 test/foo diff --git a/docs/index.rst b/docs/index.rst index f9a912f2..91271b16 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,7 @@ Table of Contents using/common using/specifics using/recipes + using/troubleshooting .. toctree:: :maxdepth: 2 diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index f4042df1..dc7d9a3d 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -4,66 +4,179 @@ When troubleshooting, you may see unexpected behaviors or receive an error messa ## Permission Issues -### Permission denied when mounting local directories +### Permission denied when mounting volumes If you are running a Docker container while mounting a local volume or host directory using the `-v` flag like so: ```bash - docker run -it --rm \ - -v :/home/jovyan/work jupyter/datascience-notebook +docker run -it --rm \ + -p 8888:8888 \ + -v : \ + jupyter/minimal-notebook:latest ``` -you might face permissions issues when trying to access the mounted directory: +you might face permissions issues when trying to access the mounted volume: ```bash -$ ls -l foo.txt --rw-r--r-- 1 root root 0 Jan 131 10:36 foo.txt -$ echo hi > foo.txt --bash: foo.txt: Permission denied +# assuming we mounted the volume in /home/jovyan/stagingarea +$ ls -ld ~/stagingarea/ +drwxr-xr-x 2 root root 4096 Feb 1 12:55 stagingarea/ + +$ touch stagingarea/kale.txt +touch: cannot touch 'stagingarea/kale.txt': Permission denied ``` **Some things to try:** -1. Matching the container's UID/GID with the host's +1. **Change ownership of the volume mount** - Docker handles mounting host directories differently to mounting volumes, even though the syntax is basically the same (i.e. `-v`). + You can change the ownership of the volume mount using the `chown` command. For example, to change the ownership of the volume mount to the jovyan user: + + ```bash + docker run -d \ + -v : \ + -p 8888:8888 \ + --user root \ + -e CHOWN_EXTRA="" \ + -e CHOWN_EXTRA_OPTS="-R" \ + jupyter/minimal-notebook + ``` + + where: + + - `CHOWN_EXTRA=`: will change the owner and group of the specified container directory (non recursive by default). You need to provide full paths starting with `/`. + - `CHOWN_EXTRA_OPTS=R`: will recursively the owner and group of of the directory specified in `CHOWN_EXTRA`. + - `--user root`: must run the container with the root user to perform the change of ownership. + + so now accessing the mount should work as expected: + + ```bash + # assuming we mounted the volume in /home/jovyan/stagingarea + $ ls -ld ~/stagingarea + drwxr-xr-x 2 jovyan users 4096 Feb 1 12:55 stagingarea/ + + $ touch stagingarea/kale.txt + $ ls -la ~/stagingarea/ + -rw-r--r-- 1 jovyan users 0 Feb 1 14:41 kale.txt + ``` + + **Note**: 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. + +2. **Matching the container's UID/GID with the host's** + + Docker handles mounting host directories differently to mounting volumes, even though the syntax is essentially the same (i.e. `-v`). When you initialize a Docker container using the flag `-v` the host directories are bind mounted directly into the container. - Therefore, the permissions and ownership are **exactly the same** as the ones in your local host (including user ids) which may result in permissions errors like the one displayed above. + Therefore, the permissions and ownership are copied over and will be **exactly the same** as the ones in your local host + (including user ids) which may result in permissions errors like the one displayed above. - Suppose your local user has a `UID` of `1000`. To fix the UID discrepancies between your local directories and the container's + Suppose your local user has a `UID` and `GID` of `1234`. To fix the UID discrepancies between your local directories and the container's directoriess, you need to set `NB_UID` and `NB_GID` to match the that of the local user: ```bash - docker run -it --rm \ - -e NB_UID=1000 \ - -e NB_GID=1000 \ - --user root \ - -v :/home/jovyan/work jupyter/datascience-notebook + $ docker run -it --rm \ + --user root \ + -p 8888:8888 \ + -e NB_UID=1234 \ + -e NB_GID=1234 \ + -v $(PWD)/test:/home/jovyan/work \ + jupyter/minimal-notebook:latest + + # you should see an output similar to this + Update jovyan's UID:GID to 1234:1234 + Running as jovyan: bash ``` - Note that you need to use the flag `--user root` to ensure that the `UID` is updated at runtime. + Some important things to notice: - The caveat with this approach is that since these changes are applied at runtime, you will need to to re-run the same - command with the appropriate flags and environment variables if you need to recreate the container. + - You must use `--user root` to ensure that the `UID` is updated at runtime + - The caveat with this approach is that since these changes are applied at runtime, you will need to to re-run the same command + with the appropriate flags and environment variables if you need to recreate the container -**Other tips:** + **Note** that this approach only updates the UID and GID of the existing jovyan user: + + ```bash + $ id + uid=1234(jovyan) gid=1234(jovyan) groups=1234(jovyan),100(users) + ``` + +If on top of changing the UID and GID you also need to create a new user (and thus ensure this user has a home directory) you can use the following command: + +```bash + docker run -it --rm \ + --user root \ + -e NB_UID=1234 \ + -e NB_GID=1234 \ + -e NB_USER=trallard \ + -e CHOWN_HOME=yes \ + -e CHOWN_HOME_OPTS="-R" \ + -w "/home/${NB_USER}" \ + -v $(PWD)/test:/home/trallard/work \ + jupyter/minimal-notebook start.sh + + # expected output + Updated the jovyan user: + - username: jovyan -> trallard + - home dir: /home/jovyan -> /home/trallard + Update trallard's UID:GID to 1234:1234 + Attempting to copy /home/jovyan to /home/trallard... + Success! + Ensuring /home/trallard is owned by 1234:1234 + Running as trallard: bash +``` + +**Additional tips and troubleshooting commands:** - Use absolute paths when using the `-v` flag: ```bash - -v $(PWD)/:/home/jovyan/work + -v $(PWD)/:/home/jovyan/work ``` in this example, we use the syntax `$(PWD)` which will be replaced with the full path to the current directory. The destination path should also be an absolute path starting with a `/` such as `home/jovyan/work`. -- You might want to consider using the Docker native `--user ` and `--group-add `: +- You might want to consider using the Docker native `--user ` and `--group-add users` flags instead of `-e NB_GID` and `-e NB_UID`: ```bash - # note this will use the same UID from the user calling the command + # note this will use the same UID from + # the user calling the command thus matching the local host + docker run -it --rm \ - --user "$(id -u)" --group-add users \ # $(id -u) prints the UID of the user that called docker run - -v :/home/jovyan/work jupyter/datascience-notebook + --user "$(id -u)" --group-add users \ # $(id -u) prints the UID of the user that called docker run + -v :/home/jovyan/work jupyter/datascience-notebook ``` this command will not only launch the container with a specific user UID, but also add the that user to the `users` group so that it can modify the files in the default `/home` and `/opt/conda` directories. + Further avoiding issues when trying to `conda install` additional packages. + +- Use `docker inspect ` and look for the [`Mounts` section](https://docs.docker.com/storage/volumes/#start-a-container-with-a-volume) to verify that the volume was created and mounted accordingly: + + ```json + # for example for a my-vol volume created with docker volume create + + "Mounts": [ + { + "Type": "volume", + "Name": "my-vol", + "Source": "/var/lib/docker/volumes/stagingarea/_data", + "Destination": "/home/jovyan/stagingarea", + "Driver": "local", + "Mode": "z", + "RW": true, + "Propagation": "" + } + ], + ``` + + diff --git a/test/foo b/test/foo new file mode 100644 index 00000000..257cc564 --- /dev/null +++ b/test/foo @@ -0,0 +1 @@ +foo From e4be6856eff2357f6939e8b38625fb8bd8e08c29 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Wed, 2 Feb 2022 12:26:11 +0000 Subject: [PATCH 08/30] :memo: Add link to common.md --- docs/using/troubleshooting.md | 170 ++++++++++++++++++++++------------ test/foo | 1 - 2 files changed, 110 insertions(+), 61 deletions(-) delete mode 100644 test/foo diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index dc7d9a3d..aa2af96b 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -1,10 +1,11 @@ # Troubleshooting Common Problems -When troubleshooting, you may see unexpected behaviors or receive an error message. This section provides links for identifying the cause of the problem and how to resolve it. +When troubleshooting, you may see unexpected behaviors or receive an error message. This section provides advice on +how to identify and mitigate the cause of the problem and how to resolve it (for the most commlonly encountered issues). -## Permission Issues +Most of the `docker run` flags used in this document are explained in detail in the [Common Features, Docker Options section](../using/common.html#Docker-Options) of the documentation. -### Permission denied when mounting volumes +## Permission denied when mounting volumes If you are running a Docker container while mounting a local volume or host directory using the `-v` flag like so: @@ -19,6 +20,7 @@ you might face permissions issues when trying to access the mounted volume: ```bash # assuming we mounted the volume in /home/jovyan/stagingarea +# root is the owner of the mounted volume $ ls -ld ~/stagingarea/ drwxr-xr-x 2 root root 4096 Feb 1 12:55 stagingarea/ @@ -26,13 +28,18 @@ $ touch stagingarea/kale.txt touch: cannot touch 'stagingarea/kale.txt': Permission denied ``` +In this case the user of the container (`jovyan`) and the owner of the mounted volume (`root`) have different permission levels and ownership over the container's directories and mounts. + **Some things to try:** 1. **Change ownership of the volume mount** - You can change the ownership of the volume mount using the `chown` command. For example, to change the ownership of the volume mount to the jovyan user: + You can change the ownership of the volume mount using the `chown` command. In the case of the docker-stacks images, you can set the `CHOWN_EXTRA` and `CHOWN_EXTRA_OPTS` environment variables. + + For example, to change the ownership of the volume mount to the jovyan user (non-privileged default user in the Docker images): ```bash + # running in detached mode - can also be run in interactive mode docker run -d \ -v : \ -p 8888:8888 \ @@ -44,11 +51,11 @@ touch: cannot touch 'stagingarea/kale.txt': Permission denied where: - - `CHOWN_EXTRA=`: will change the owner and group of the specified container directory (non recursive by default). You need to provide full paths starting with `/`. - - `CHOWN_EXTRA_OPTS=R`: will recursively the owner and group of of the directory specified in `CHOWN_EXTRA`. - - `--user root`: must run the container with the root user to perform the change of ownership. + - `CHOWN_EXTRA=`: will change the ownership and group of the specified container directory (non-recursive by default). You need to provide full paths starting with `/`. + - `CHOWN_EXTRA_OPTS="-R"`: will recursively change the ownership and group of the directory specified in `CHOWN_EXTRA`. + - `--user root`: you **must** run the container with the root user to change ownership at runtime. - so now accessing the mount should work as expected: + now accessing the mount should work as expected: ```bash # assuming we mounted the volume in /home/jovyan/stagingarea @@ -56,23 +63,28 @@ touch: cannot touch 'stagingarea/kale.txt': Permission denied drwxr-xr-x 2 jovyan users 4096 Feb 1 12:55 stagingarea/ $ touch stagingarea/kale.txt + # jovyan is now the owner of /home/jovyan/stagingarea $ ls -la ~/stagingarea/ -rw-r--r-- 1 jovyan users 0 Feb 1 14:41 kale.txt ``` - **Note**: 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. + **Additional notes:** + + - 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. + - This solution should work in most cases where you have created a docker volume (i.e. using the [`docker volume create --name ` + command](https://docs.docker.com/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** - Docker handles mounting host directories differently to mounting volumes, even though the syntax is essentially the same (i.e. `-v`). + Docker handles mounting host directories differently from mounting volumes, even though the syntax is essentially the same (i.e. `-v`). - When you initialize a Docker container using the flag `-v` the host directories are bind mounted directly into the container. - Therefore, the permissions and ownership are copied over and will be **exactly the same** as the ones in your local host + When you initialize a Docker container using the flag `-v`, the host directories are bind-mounted directly into the container. + Therefore, the permissions and ownership are copied over and will be **the same** as the ones in your local host (including user ids) which may result in permissions errors like the one displayed above. Suppose your local user has a `UID` and `GID` of `1234`. To fix the UID discrepancies between your local directories and the container's - directoriess, you need to set `NB_UID` and `NB_GID` to match the that of the local user: + directories, you can run the container with an explicit `NB_UID` and `NB_GID` to match the that of the local user: ```bash $ docker run -it --rm \ @@ -88,43 +100,93 @@ touch: cannot touch 'stagingarea/kale.txt': Permission denied Running as jovyan: bash ``` - Some important things to notice: + where: - - You must use `--user root` to ensure that the `UID` is updated at runtime - - The caveat with this approach is that since these changes are applied at runtime, you will need to to re-run the same command - with the appropriate flags and environment variables if you need to recreate the container + - `NB_IUD` 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. - **Note** that this approach only updates the UID and GID of the existing jovyan user: + **Additional notes:** + + - The caveat with this approach is that since these changes are applied at runtime, you will need to re-run the same command + with the appropriate flags and environment variables if you need to recreate the container (i.e. after removing/destroying it). + + - This approach only updates the UID and GID of the **existing `jovyan` user** instead of creating a new user, so from the above example you'd get the following: + + ```bash + $ id + uid=1234(jovyan) gid=1234(jovyan) groups=1234(jovyan),100(users) + ``` + + If you need to specify a different user check the following section in this page. + +## Permission issues after changing the UID/GIU and USER in the container + +If on top of changing the UID and GID you also **need to create a new user**, you might be experiencing any of the following issues: + +- `root` is the owner of `/home` or a mounted volume +- when starting the container, you get an error such as `Failed to change ownership of the home directory.` +- getting permission denied when trying to `conda install` packages + +**Some things to try:** + +1. **Ensure the new user has ownership of `/home` and volume mounts** + + For example, say you want to create a user `callisto` with a `GID` and `UID` of 1234, you will have to add the following flags to the docker run command: ```bash - $ id - uid=1234(jovyan) gid=1234(jovyan) groups=1234(jovyan),100(users) + docker run -it --rm \ + --user root \ + -e NB_USER=callisto \ + -e NB_UID=1234 \ + -e NB_GID=1234 \ + -e CHOWN_HOME=yes \ + -e CHOWN_HOME_OPTS="-R" \ + -w "/home/${NB_USER}" \ + -v $(PWD)/test:/home/callisto/work \ + jupyter/minimal-notebook + + # expected output + Updated the jovyan user: + - username: jovyan -> callisto + - home dir: /home/jovyan -> /home/callisto + Update callisto's UID:GID to 1234:1234 + Attempting to copy /home/jovyan to /home/callisto... + Success! + Ensuring /home/callisto is owned by 1234:1234 + Running as callisto: bash ``` -If on top of changing the UID and GID you also need to create a new user (and thus ensure this user has a home directory) you can use the following command: + where: -```bash - docker run -it --rm \ - --user root \ - -e NB_UID=1234 \ - -e NB_GID=1234 \ - -e NB_USER=trallard \ - -e CHOWN_HOME=yes \ - -e CHOWN_HOME_OPTS="-R" \ - -w "/home/${NB_USER}" \ - -v $(PWD)/test:/home/trallard/work \ - jupyter/minimal-notebook start.sh + - `-e NB_USER=callisto`: will create a new user `callisto` and automatically add it to the `users` group (does not delete jovyan) + - `-e NB_UID=1234` and `-e NB_GID=1234`: will set the `UID` and `GID` of the new user (`callisto`) to `1234` + - `-e CHOWN_HOME_OPTS="-R"` and `-e CHOWN_HOME=yes`: ensure that the new user is the owner of the `/home` directory and subdirectories + (setting `CHOWN_HOME_OPTS="-R` will ensure this change is applied recursively) + - `-w "/home/${NB_USER}"` sets the working directory to be the new user's home + - **mounting volumes**: in this case, the `-v` flag is used to mount the local volume onto the `/home` directory; if you, however, are mounting these volumes elsewhere, + you also need to use the `-e CHOWN_EXTRA=` flag to avoid any permission issues (see section above) - # expected output - Updated the jovyan user: - - username: jovyan -> trallard - - home dir: /home/jovyan -> /home/trallard - Update trallard's UID:GID to 1234:1234 - Attempting to copy /home/jovyan to /home/trallard... - Success! - Ensuring /home/trallard is owned by 1234:1234 - Running as trallard: bash -``` +2. **Dynamically assign the user ID and GID** + + The above case ensures that the `/home` directory is owned by the a newly created user with an specific `UID` and `GID`, but if you want to assign the `UID` and `GID` + of the new user dynamically you can make the following adjustments: + + ```bash + docker run -it --rm \ + --user root \ + -e NB_USER=callisto \ + -e NB_UID="$(id -u)" \ + -e NB_GID="$(id -g)" \ + -e CHOWN_HOME=yes \ + -e CHOWN_HOME_OPTS="-R" \ + -w "/home/${NB_USER}" \ + -v $(PWD)/test:/home/callisto/work \ + jupyter/minimal-notebook + ``` + + where: + + - `"$(id -u)" and "$(id -g)"` will dynamically assign the `UID` and `GID` of the new user (`callisto`) to that of the local user executing the run command **Additional tips and troubleshooting commands:** @@ -134,26 +196,26 @@ If on top of changing the UID and GID you also need to create a new user (and th -v $(PWD)/:/home/jovyan/work ``` - in this example, we use the syntax `$(PWD)` which will be replaced with the full path to the current directory. The destination path should also be an absolute path starting with a `/` such as `home/jovyan/work`. + In this example, we use the syntax `$(PWD)`, which is replaced with the full path to the current directory. The destination path should also be an absolute path starting with a `/` such as `home/jovyan/work`. - You might want to consider using the Docker native `--user ` and `--group-add users` flags instead of `-e NB_GID` and `-e NB_UID`: ```bash # note this will use the same UID from - # the user calling the command thus matching the local host + # the user calling the command, thus matching the local host docker run -it --rm \ - --user "$(id -u)" --group-add users \ # $(id -u) prints the UID of the user that called docker run + --user "$(id -u)" --group-add users \ -v :/home/jovyan/work jupyter/datascience-notebook ``` - this command will not only launch the container with a specific user UID, but also add the that user to the `users` group so that it can modify the files in the default `/home` and `/opt/conda` directories. + This command will launch the container with a specific user UID and add that user to the `users` group so that it can modify the files in the default `/home` and `/opt/conda` directories. Further avoiding issues when trying to `conda install` additional packages. - Use `docker inspect ` and look for the [`Mounts` section](https://docs.docker.com/storage/volumes/#start-a-container-with-a-volume) to verify that the volume was created and mounted accordingly: ```json - # for example for a my-vol volume created with docker volume create + # for example, for a my-vol volume created with docker volume create "Mounts": [ { @@ -168,15 +230,3 @@ If on top of changing the UID and GID you also need to create a new user (and th } ], ``` - - diff --git a/test/foo b/test/foo deleted file mode 100644 index 257cc564..00000000 --- a/test/foo +++ /dev/null @@ -1 +0,0 @@ -foo From 66566d9bd02fc8aae9fe0b9ef692fd5f030fbf89 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Wed, 2 Feb 2022 13:03:39 +0000 Subject: [PATCH 09/30] :memo: Improvements to troubleshoot --- docs/using/troubleshooting.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index aa2af96b..c902c297 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -117,6 +117,8 @@ In this case the user of the container (`jovyan`) and the owner of the mounted v uid=1234(jovyan) gid=1234(jovyan) groups=1234(jovyan),100(users) ``` + - If you pass a numeric UID, it must be in the range of 0-2147483647 + If you need to specify a different user check the following section in this page. ## Permission issues after changing the UID/GIU and USER in the container @@ -188,7 +190,7 @@ If on top of changing the UID and GID you also **need to create a new user**, yo - `"$(id -u)" and "$(id -g)"` will dynamically assign the `UID` and `GID` of the new user (`callisto`) to that of the local user executing the run command -**Additional tips and troubleshooting commands:** +## Additional tips and troubleshooting commands - Use absolute paths when using the `-v` flag: @@ -196,7 +198,8 @@ If on top of changing the UID and GID you also **need to create a new user**, yo -v $(PWD)/:/home/jovyan/work ``` - In this example, we use the syntax `$(PWD)`, which is replaced with the full path to the current directory. The destination path should also be an absolute path starting with a `/` such as `home/jovyan/work`. + In this example, we use the syntax `$(PWD)`, which is replaced with the full path to the current directory. The destination + path should also be an absolute path starting with a `/` such as `home/jovyan/work`. - You might want to consider using the Docker native `--user ` and `--group-add users` flags instead of `-e NB_GID` and `-e NB_UID`: @@ -215,7 +218,8 @@ If on top of changing the UID and GID you also **need to create a new user**, yo - Use `docker inspect ` and look for the [`Mounts` section](https://docs.docker.com/storage/volumes/#start-a-container-with-a-volume) to verify that the volume was created and mounted accordingly: ```json - # for example, for a my-vol volume created with docker volume create + # for example, for a my-vol volume created with + # docker volume create --name "Mounts": [ { From 1445af51f651b136fe599c0e8f4d9c859c32aed5 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 3 Feb 2022 11:28:05 +0000 Subject: [PATCH 10/30] :memo: Replace notes with admonitions --- docs/using/troubleshooting.md | 48 +++++++++++++++++------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index c902c297..fe669cbf 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -1,7 +1,7 @@ # Troubleshooting Common Problems When troubleshooting, you may see unexpected behaviors or receive an error message. This section provides advice on -how to identify and mitigate the cause of the problem and how to resolve it (for the most commlonly encountered issues). +how to identify and mitigate the cause of the problem and how to resolve it (for the most commonly encountered issues). Most of the `docker run` flags used in this document are explained in detail in the [Common Features, Docker Options section](../using/common.html#Docker-Options) of the documentation. @@ -29,6 +29,7 @@ touch: cannot touch 'stagingarea/kale.txt': Permission denied ``` In this case the user of the container (`jovyan`) and the owner of the mounted volume (`root`) have different permission levels and ownership over the container's directories and mounts. +The following sections cover a few of these scenarios and suggestions to fix these problems. **Some things to try:** @@ -68,12 +69,12 @@ In this case the user of the container (`jovyan`) and the owner of the mounted v -rw-r--r-- 1 jovyan users 0 Feb 1 14:41 kale.txt ``` - **Additional notes:** - - - 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. - - This solution should work in most cases where you have created a docker volume (i.e. using the [`docker volume create --name ` - command](https://docs.docker.com/storage/volumes/#create-and-manage-volumes)) and mounted it using the`-v` flag in `docker run`. + ```{admonition} Additional notes + - 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. + - This solution should work in most cases where you have created a docker volume (i.e. using the [`docker volume create --name ` + command](https://docs.docker.com/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** @@ -81,7 +82,7 @@ In this case the user of the container (`jovyan`) and the owner of the mounted v When you initialize a Docker container using the flag `-v`, the host directories are bind-mounted directly into the container. Therefore, the permissions and ownership are copied over and will be **the same** as the ones in your local host - (including user ids) which may result in permissions errors like the one displayed above. + (including user ids) which may result in permissions errors when trying to access directories or create/modify files inside. Suppose your local user has a `UID` and `GID` of `1234`. To fix the UID discrepancies between your local directories and the container's directories, you can run the container with an explicit `NB_UID` and `NB_GID` to match the that of the local user: @@ -105,21 +106,15 @@ In this case the user of the container (`jovyan`) and the owner of the mounted v - `NB_IUD` 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. - **Additional notes:** - + ````{admonition} Additional notes - The caveat with this approach is that since these changes are applied at runtime, you will need to re-run the same command with the appropriate flags and environment variables if you need to recreate the container (i.e. after removing/destroying it). - - - This approach only updates the UID and GID of the **existing `jovyan` user** instead of creating a new user, so from the above example you'd get the following: - + - If you pass a numeric UID, it must be in the range of 0-2147483647 + - This approach only updates the UID and GID of the **existing `jovyan` user** instead of creating a new user. From the above example: ```bash $ id uid=1234(jovyan) gid=1234(jovyan) groups=1234(jovyan),100(users) - ``` - - - If you pass a numeric UID, it must be in the range of 0-2147483647 - - If you need to specify a different user check the following section in this page. + ```` ## Permission issues after changing the UID/GIU and USER in the container @@ -133,7 +128,7 @@ If on top of changing the UID and GID you also **need to create a new user**, yo 1. **Ensure the new user has ownership of `/home` and volume mounts** - For example, say you want to create a user `callisto` with a `GID` and `UID` of 1234, you will have to add the following flags to the docker run command: + For example, say you want to create a user `callisto` with a `GID` and `UID` of `1234`, you will have to add the following flags to the docker run command: ```bash docker run -it --rm \ @@ -165,8 +160,13 @@ If on top of changing the UID and GID you also **need to create a new user**, yo - `-e CHOWN_HOME_OPTS="-R"` and `-e CHOWN_HOME=yes`: ensure that the new user is the owner of the `/home` directory and subdirectories (setting `CHOWN_HOME_OPTS="-R` will ensure this change is applied recursively) - `-w "/home/${NB_USER}"` sets the working directory to be the new user's home - - **mounting volumes**: in this case, the `-v` flag is used to mount the local volume onto the `/home` directory; if you, however, are mounting these volumes elsewhere, - you also need to use the `-e CHOWN_EXTRA=` flag to avoid any permission issues (see section above) + + ```{admonition} Additional notes + In the example above, the `-v` flag is used to mount the local volume onto the `/home` directory of the new user. + + However, if you are mounting a volume elsewhere, you also need to use the `-e CHOWN_EXTRA=` flag to avoid any permission + issues (see the section [Permission denied when mounting volumes](../using/troubleshooting.html#permission-denied-when-mounting-volumes) in this page). + ``` 2. **Dynamically assign the user ID and GID** @@ -188,17 +188,17 @@ If on top of changing the UID and GID you also **need to create a new user**, yo where: - - `"$(id -u)" and "$(id -g)"` will dynamically assign the `UID` and `GID` of the new user (`callisto`) to that of the local user executing the run command + - `"$(id -u)" and "$(id -g)"` will dynamically assign the `UID` and `GID` of the user executing the `docker run` command to the new user (`callisto`) ## Additional tips and troubleshooting commands -- Use absolute paths when using the `-v` flag: +- Pass absolute paths to the `-v` flag: ```bash -v $(PWD)/:/home/jovyan/work ``` - In this example, we use the syntax `$(PWD)`, which is replaced with the full path to the current directory. The destination + In this example, we use the syntax `$(PWD)`, which is replaced with the full path to the current directory at runtime. The destination path should also be an absolute path starting with a `/` such as `home/jovyan/work`. - You might want to consider using the Docker native `--user ` and `--group-add users` flags instead of `-e NB_GID` and `-e NB_UID`: From a4b5dd557f58cb443e3e6042cf01a9308f0c4ddd Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 3 Feb 2022 12:37:46 +0000 Subject: [PATCH 11/30] :memo: Add token not working section --- .../vscode-jupyter-settings.png | Bin 0 -> 13409 bytes docs/using/troubleshooting.md | 36 +++++++++++++++++- 2 files changed, 35 insertions(+), 1 deletion(-) create mode 100644 docs/_static/using/troubleshooting/vscode-jupyter-settings.png diff --git a/docs/_static/using/troubleshooting/vscode-jupyter-settings.png b/docs/_static/using/troubleshooting/vscode-jupyter-settings.png new file mode 100644 index 0000000000000000000000000000000000000000..177c385522a9f5c4200a2455519a5a9cd8312301 GIT binary patch literal 13409 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 U1l+{M@AEhBB^1PeiW&y|A3!z~)Bpeg literal 0 HcmV?d00001 diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index fe669cbf..510c1b45 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -132,6 +132,7 @@ If on top of changing the UID and GID you also **need to create a new user**, yo ```bash docker run -it --rm \ + -p 8888:8888 \ --user root \ -e NB_USER=callisto \ -e NB_UID=1234 \ @@ -175,6 +176,7 @@ If on top of changing the UID and GID you also **need to create a new user**, yo ```bash docker run -it --rm \ + -p 8888:8888 \ --user root \ -e NB_USER=callisto \ -e NB_UID="$(id -u)" \ @@ -190,7 +192,7 @@ If on top of changing the UID and GID you also **need to create a new user**, yo - `"$(id -u)" and "$(id -g)"` will dynamically assign the `UID` and `GID` of the user executing the `docker run` command to the new user (`callisto`) -## Additional tips and troubleshooting commands +## Additional tips and troubleshooting commands for permission-related errors - Pass absolute paths to the `-v` flag: @@ -208,6 +210,7 @@ If on top of changing the UID and GID you also **need to create a new user**, yo # the user calling the command, thus matching the local host docker run -it --rm \ + -p 8888:8888 \ --user "$(id -u)" --group-add users \ -v :/home/jovyan/work jupyter/datascience-notebook ``` @@ -234,3 +237,34 @@ If on top of changing the UID and GID you also **need to create a new user**, yo } ], ``` + +## Tokens are being rejected + +If you are a regular user of VSCode and the Jupyter extension you might experience either of these issues when using any of the docker-stacks images: + +- using the produced token and/or URL results in an "Invalid credentials" error on the Jupyter "Token authentication is enabled" page +- when clicking on the URL displayed on your command line logs you face a "This site cannot be reached" page on your web browser + +**Some things to try:** + +1. The first thing you want to try is to check that there are no other Jupyter processes running in the background: + + ```bash + ps aux | grep jupyter + ``` + + If there are existing processes running, you can kill them with: + + ```bash + # example output from the above command + # my-user 3412 ... --daemon-module=vscode_datascience_helpers.jupyter_daemon + + # using the pid from the above log + kill 3412 + ``` + +2. Alternatively - you might want to ensure that the "Jupyter: Auto Start" setting is turned off to avoid this issue in the future. + + You can achieve this from the `Preferences > Jupyter` menu in VScode: + + ![VSCode Preferences UI - Jupyter:Disable Jupyter Auto Start checkbox unchecked](../_static/using/troubleshooting/vscode-jupyter-settings.png) From 832c60a69bee6eecbedaaffd8fc5aa2ad31cb4d4 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 3 Feb 2022 13:02:56 +0000 Subject: [PATCH 12/30] :memo: Add conda channels troubleshoot --- docs/using/troubleshooting.md | 64 ++++++++++++++++++++++++++++------- 1 file changed, 52 insertions(+), 12 deletions(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index 510c1b45..77b4dcd2 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -1,7 +1,7 @@ # Troubleshooting Common Problems When troubleshooting, you may see unexpected behaviors or receive an error message. This section provides advice on -how to identify and mitigate the cause of the problem and how to resolve it (for the most commonly encountered issues). +how to identify and fix some of the most commonly encountered issues. Most of the `docker run` flags used in this document are explained in detail in the [Common Features, Docker Options section](../using/common.html#Docker-Options) of the documentation. @@ -28,8 +28,8 @@ $ touch stagingarea/kale.txt touch: cannot touch 'stagingarea/kale.txt': Permission denied ``` -In this case the user of the container (`jovyan`) and the owner of the mounted volume (`root`) have different permission levels and ownership over the container's directories and mounts. -The following sections cover a few of these scenarios and suggestions to fix these problems. +In this case, the user of the container (`jovyan`) and the owner of the mounted volume (`root`) have different permission levels and ownership over the container's directories and mounts. +The following sections cover a few of these scenarios and how to fix them. **Some things to try:** @@ -118,7 +118,7 @@ The following sections cover a few of these scenarios and suggestions to fix the ## Permission issues after changing the UID/GIU and USER in the container -If on top of changing the UID and GID you also **need to create a new user**, you might be experiencing any of the following issues: +If you have also **created a new user**, you might be experiencing any of the following issues: - `root` is the owner of `/home` or a mounted volume - when starting the container, you get an error such as `Failed to change ownership of the home directory.` @@ -163,7 +163,7 @@ If on top of changing the UID and GID you also **need to create a new user**, yo - `-w "/home/${NB_USER}"` sets the working directory to be the new user's home ```{admonition} Additional notes - In the example above, the `-v` flag is used to mount the local volume onto the `/home` directory of the new user. + In the example above, the `-v` flag is used to mount the local volume onto the new user's `/home` directory. However, if you are mounting a volume elsewhere, you also need to use the `-e CHOWN_EXTRA=` flag to avoid any permission issues (see the section [Permission denied when mounting volumes](../using/troubleshooting.html#permission-denied-when-mounting-volumes) in this page). @@ -200,7 +200,7 @@ If on top of changing the UID and GID you also **need to create a new user**, yo -v $(PWD)/:/home/jovyan/work ``` - In this example, we use the syntax `$(PWD)`, which is replaced with the full path to the current directory at runtime. The destination + This example uses the syntax `$(PWD)`, which is replaced with the full path to the current directory at runtime. The destination path should also be an absolute path starting with a `/` such as `home/jovyan/work`. - You might want to consider using the Docker native `--user ` and `--group-add users` flags instead of `-e NB_GID` and `-e NB_UID`: @@ -215,7 +215,7 @@ If on top of changing the UID and GID you also **need to create a new user**, yo -v :/home/jovyan/work jupyter/datascience-notebook ``` - This command will launch the container with a specific user UID and add that user to the `users` group so that it can modify the files in the default `/home` and `/opt/conda` directories. + This command will launch the container with a specific user UID and add that user to the `users` group to modify the files in the default `/home` and `/opt/conda` directories. Further avoiding issues when trying to `conda install` additional packages. - Use `docker inspect ` and look for the [`Mounts` section](https://docs.docker.com/storage/volumes/#start-a-container-with-a-volume) to verify that the volume was created and mounted accordingly: @@ -238,16 +238,54 @@ If on top of changing the UID and GID you also **need to create a new user**, yo ], ``` +## Problems installing conda packages from specific channels + +By default, the docker-stacks images have the conda channels priority set to `strict`. This may cause problems when trying to install packages from a channel with lower priority. + +```bash +$ conda config --show | grep priority +# channel_priority: strict + +# to see its meaning +$ conda config --describe channel_priority + +# checking the current channels +$ conda config --show default_channels +# default_channels: +# - https://repo.anaconda.com/pkgs/main +# - https://repo.anaconda.com/pkgs/r +``` + +**Installing packages from alternative channels:** + +You can install packages from other conda channels (e.g. bioconda) by disabling the `channel_priority` setting: + +```bash +# install by disabling channel priority at command level +$ conda install --no-channel-priority -c bioconda bioconductor-geoquery +``` + ## Tokens are being rejected -If you are a regular user of VSCode and the Jupyter extension you might experience either of these issues when using any of the docker-stacks images: +If you are a regular user of VSCode and the Jupyter extension, you might experience either of these issues when using any of the docker-stacks images: +- when clicking on the URL displayed on your command line logs, you face a "This site cannot be reached" page on your web browser - using the produced token and/or URL results in an "Invalid credentials" error on the Jupyter "Token authentication is enabled" page -- when clicking on the URL displayed on your command line logs you face a "This site cannot be reached" page on your web browser + + ```bash + # example log output from the docker run command + + [...] + Or copy and paste one of these URLs: + http://3d4cf3809e3f:8888/?token=996426e890f8dc22fa6835a44442b6026cba02ee61fee6a2 + or http://127.0.0.1:8888/?token=996426e890f8dc22fa6835a44442b6026cba02ee61fee6a2 + ``` **Some things to try:** -1. The first thing you want to try is to check that there are no other Jupyter processes running in the background: +1. **Find lingering Jupyter processes in the background** + + The first thing you want to try is to check that no other Jupyter processes are running in the background: ```bash ps aux | grep jupyter @@ -263,8 +301,10 @@ If you are a regular user of VSCode and the Jupyter extension you might experien kill 3412 ``` -2. Alternatively - you might want to ensure that the "Jupyter: Auto Start" setting is turned off to avoid this issue in the future. +2. **Turn off Jupyter auto start in VSCode** + + Alternatively - you might want to ensure that the `Jupyter: Auto Start` setting is turned off to avoid this issue in the future. You can achieve this from the `Preferences > Jupyter` menu in VScode: - ![VSCode Preferences UI - Jupyter:Disable Jupyter Auto Start checkbox unchecked](../_static/using/troubleshooting/vscode-jupyter-settings.png) + ![VSCode Preferences UI - Jupyter: Disable Jupyter Auto Start checkbox unchecked](../_static/using/troubleshooting/vscode-jupyter-settings.png) From da3cf7ea6d6b50af3e8fbb1486ace19a5f51bc3b Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Thu, 3 Feb 2022 16:27:15 +0300 Subject: [PATCH 13/30] Update docs/using/troubleshooting.md --- docs/using/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index 77b4dcd2..2d39d712 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -114,7 +114,7 @@ The following sections cover a few of these scenarios and how to fix them. ```bash $ id uid=1234(jovyan) gid=1234(jovyan) groups=1234(jovyan),100(users) - ```` + ``` ## Permission issues after changing the UID/GIU and USER in the container From 288f05f31cc96c49212853b02daa9d02ee70b887 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 3 Feb 2022 13:27:31 +0000 Subject: [PATCH 14/30] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/using/troubleshooting.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index 2d39d712..2831f617 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -115,6 +115,7 @@ The following sections cover a few of these scenarios and how to fix them. $ id uid=1234(jovyan) gid=1234(jovyan) groups=1234(jovyan),100(users) ``` + ```` ## Permission issues after changing the UID/GIU and USER in the container From c580924a672aa2954fb645a1b9bbe16582e5b305 Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Thu, 3 Feb 2022 16:29:01 +0300 Subject: [PATCH 15/30] Update docs/using/troubleshooting.md --- docs/using/troubleshooting.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index 2831f617..63b990cc 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -106,7 +106,7 @@ The following sections cover a few of these scenarios and how to fix them. - `NB_IUD` 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. - ````{admonition} Additional notes + ```{admonition} Additional notes - The caveat with this approach is that since these changes are applied at runtime, you will need to re-run the same command with the appropriate flags and environment variables if you need to recreate the container (i.e. after removing/destroying it). - If you pass a numeric UID, it must be in the range of 0-2147483647 @@ -115,7 +115,6 @@ The following sections cover a few of these scenarios and how to fix them. $ id uid=1234(jovyan) gid=1234(jovyan) groups=1234(jovyan),100(users) ``` - ```` ## Permission issues after changing the UID/GIU and USER in the container From 8371609cf8bf1b96826527652e699a15e630d4ab Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 3 Feb 2022 13:29:17 +0000 Subject: [PATCH 16/30] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/using/troubleshooting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index 63b990cc..77b4dcd2 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -106,7 +106,7 @@ The following sections cover a few of these scenarios and how to fix them. - `NB_IUD` 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. - ```{admonition} Additional notes + ````{admonition} Additional notes - The caveat with this approach is that since these changes are applied at runtime, you will need to re-run the same command with the appropriate flags and environment variables if you need to recreate the container (i.e. after removing/destroying it). - If you pass a numeric UID, it must be in the range of 0-2147483647 @@ -114,7 +114,7 @@ The following sections cover a few of these scenarios and how to fix them. ```bash $ id uid=1234(jovyan) gid=1234(jovyan) groups=1234(jovyan),100(users) - ``` + ```` ## Permission issues after changing the UID/GIU and USER in the container From 92b5fbc73398c906f9e6c62f6eb21903b29feed9 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 3 Feb 2022 14:42:01 +0000 Subject: [PATCH 17/30] Apply suggestions from code review Co-authored-by: Ayaz Salikhov --- docs/using/troubleshooting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index 77b4dcd2..5675d382 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -112,8 +112,8 @@ The following sections cover a few of these scenarios and how to fix them. - If you pass a numeric UID, it must be in the range of 0-2147483647 - This approach only updates the UID and GID of the **existing `jovyan` user** instead of creating a new user. From the above example: ```bash - $ id - uid=1234(jovyan) gid=1234(jovyan) groups=1234(jovyan),100(users) + id + # uid=1234(jovyan) gid=1234(jovyan) groups=1234(jovyan),100(users) ```` ## Permission issues after changing the UID/GIU and USER in the container From 2bdf38244b2391bdfa3f3ce37365ee513bb6f935 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 3 Feb 2022 14:48:09 +0000 Subject: [PATCH 18/30] :memo: Fixing docs - syntax and examples --- docs/using/troubleshooting.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index 5675d382..c3cd485c 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -52,7 +52,7 @@ The following sections cover a few of these scenarios and how to fix them. where: - - `CHOWN_EXTRA=`: will change the ownership and group of the specified container directory (non-recursive by default). You need to provide full paths starting with `/`. + - `CHOWN_EXTRA=,`: will change the ownership and group of the specified container directory (non-recursive by default). You need to provide full paths starting with `/`. - `CHOWN_EXTRA_OPTS="-R"`: will recursively change the ownership and group of the directory specified in `CHOWN_EXTRA`. - `--user root`: you **must** run the container with the root user to change ownership at runtime. @@ -70,10 +70,10 @@ The following sections cover a few of these scenarios and how to fix them. ``` ```{admonition} Additional notes - - 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. - - This solution should work in most cases where you have created a docker volume (i.e. using the [`docker volume create --name ` - command](https://docs.docker.com/storage/volumes/#create-and-manage-volumes)) and mounted it using the`-v` flag in `docker run`. + - 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. + - This solution should work in most cases where you have created a docker volume + (i.e. using the [`docker volume create --name `command](https://docs.docker.com/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** @@ -93,7 +93,7 @@ The following sections cover a few of these scenarios and how to fix them. -p 8888:8888 \ -e NB_UID=1234 \ -e NB_GID=1234 \ - -v $(PWD)/test:/home/jovyan/work \ + -v '$(PWD)'/test:/home/jovyan/work \ jupyter/minimal-notebook:latest # you should see an output similar to this @@ -104,12 +104,12 @@ The following sections cover a few of these scenarios and how to fix them. where: - `NB_IUD` 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 - The caveat with this approach is that since these changes are applied at runtime, you will need to re-run the same command with the appropriate flags and environment variables if you need to recreate the container (i.e. after removing/destroying it). - - If you pass a numeric UID, it must be in the range of 0-2147483647 + - If you pass a numeric UID, it **must** be in the range of 0-2147483647 - This approach only updates the UID and GID of the **existing `jovyan` user** instead of creating a new user. From the above example: ```bash id @@ -140,7 +140,7 @@ If you have also **created a new user**, you might be experiencing any of the fo -e CHOWN_HOME=yes \ -e CHOWN_HOME_OPTS="-R" \ -w "/home/${NB_USER}" \ - -v $(PWD)/test:/home/callisto/work \ + -v' $(PWD)'/test:/home/callisto/work \ jupyter/minimal-notebook # expected output From 8b4cf103ab2d0b78abb31bd98135472e5dd4066b Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 3 Feb 2022 14:59:23 +0000 Subject: [PATCH 19/30] Fix snippets --- docs/using/troubleshooting.md | 53 ++++++++++++++++++----------------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index c3cd485c..4509f225 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -21,11 +21,11 @@ you might face permissions issues when trying to access the mounted volume: ```bash # assuming we mounted the volume in /home/jovyan/stagingarea # root is the owner of the mounted volume -$ ls -ld ~/stagingarea/ -drwxr-xr-x 2 root root 4096 Feb 1 12:55 stagingarea/ +ls -ld ~/stagingarea/ +# drwxr-xr-x 2 root root 4096 Feb 1 12:55 stagingarea/ -$ touch stagingarea/kale.txt -touch: cannot touch 'stagingarea/kale.txt': Permission denied +touch stagingarea/kale.txt +# touch: cannot touch 'stagingarea/kale.txt': Permission denied ``` In this case, the user of the container (`jovyan`) and the owner of the mounted volume (`root`) have different permission levels and ownership over the container's directories and mounts. @@ -60,13 +60,13 @@ The following sections cover a few of these scenarios and how to fix them. ```bash # assuming we mounted the volume in /home/jovyan/stagingarea - $ ls -ld ~/stagingarea - drwxr-xr-x 2 jovyan users 4096 Feb 1 12:55 stagingarea/ + ls -ld ~/stagingarea + # drwxr-xr-x 2 jovyan users 4096 Feb 1 12:55 stagingarea/ - $ touch stagingarea/kale.txt + touch stagingarea/kale.txt # jovyan is now the owner of /home/jovyan/stagingarea - $ ls -la ~/stagingarea/ - -rw-r--r-- 1 jovyan users 0 Feb 1 14:41 kale.txt + # ls -la ~/stagingarea/ + # -rw-r--r-- 1 jovyan users 0 Feb 1 14:41 kale.txt ``` ```{admonition} Additional notes @@ -88,7 +88,7 @@ The following sections cover a few of these scenarios and how to fix them. directories, you can run the container with an explicit `NB_UID` and `NB_GID` to match the that of the local user: ```bash - $ docker run -it --rm \ + docker run -it --rm \ --user root \ -p 8888:8888 \ -e NB_UID=1234 \ @@ -97,8 +97,8 @@ The following sections cover a few of these scenarios and how to fix them. jupyter/minimal-notebook:latest # you should see an output similar to this - Update jovyan's UID:GID to 1234:1234 - Running as jovyan: bash + # Update jovyan's UID:GID to 1234:1234 + # Running as jovyan: bash ``` where: @@ -106,15 +106,16 @@ The following sections cover a few of these scenarios and how to fix them. - `NB_IUD` 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. - ````{admonition} Additional notes - - The caveat with this approach is that since these changes are applied at runtime, you will need to re-run the same command - with the appropriate flags and environment variables if you need to recreate the container (i.e. after removing/destroying it). - - If you pass a numeric UID, it **must** be in the range of 0-2147483647 - - This approach only updates the UID and GID of the **existing `jovyan` user** instead of creating a new user. From the above example: - ```bash - id - # uid=1234(jovyan) gid=1234(jovyan) groups=1234(jovyan),100(users) - ```` +````{admonition} Additional notes +- The caveat with this approach is that since these changes are applied at runtime, you will need to re-run the same command + with the appropriate flags and environment variables if you need to recreate the container (i.e. after removing/destroying it). + - If you pass a numeric UID, it **must** be in the range of 0-2147483647 + - This approach only updates the UID and GID of the **existing `jovyan` user** instead of creating a new user. From the above example: + ```bash + id + # uid=1234(jovyan) gid=1234(jovyan) groups=1234(jovyan),100(users) + ``` +```` ## Permission issues after changing the UID/GIU and USER in the container @@ -197,7 +198,7 @@ If you have also **created a new user**, you might be experiencing any of the fo - Pass absolute paths to the `-v` flag: ```bash - -v $(PWD)/:/home/jovyan/work + -v '$(PWD)'/:/home/jovyan/work ``` This example uses the syntax `$(PWD)`, which is replaced with the full path to the current directory at runtime. The destination @@ -243,14 +244,14 @@ If you have also **created a new user**, you might be experiencing any of the fo By default, the docker-stacks images have the conda channels priority set to `strict`. This may cause problems when trying to install packages from a channel with lower priority. ```bash -$ conda config --show | grep priority +conda config --show | grep priority # channel_priority: strict # to see its meaning -$ conda config --describe channel_priority +conda config --describe channel_priority # checking the current channels -$ conda config --show default_channels +conda config --show default_channels # default_channels: # - https://repo.anaconda.com/pkgs/main # - https://repo.anaconda.com/pkgs/r @@ -262,7 +263,7 @@ You can install packages from other conda channels (e.g. bioconda) by disabling ```bash # install by disabling channel priority at command level -$ conda install --no-channel-priority -c bioconda bioconductor-geoquery +conda install --no-channel-priority -c bioconda bioconductor-geoquery ``` ## Tokens are being rejected From 587232a61a64fc43f8baf65ce1ec3cbd23852f40 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 3 Feb 2022 15:01:10 +0000 Subject: [PATCH 20/30] :pencil2: Fix stray ' --- docs/using/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index 4509f225..4f193516 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -148,7 +148,7 @@ If you have also **created a new user**, you might be experiencing any of the fo Updated the jovyan user: - username: jovyan -> callisto - home dir: /home/jovyan -> /home/callisto - Update callisto's UID:GID to 1234:1234 + Update callisto UID:GID to 1234:1234 Attempting to copy /home/jovyan to /home/callisto... Success! Ensuring /home/callisto is owned by 1234:1234 From ab63ab3b006811c1d46aa64b2066b4f5a409587d Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 3 Feb 2022 15:06:03 +0000 Subject: [PATCH 21/30] :memo: Use different GID for examples --- docs/using/troubleshooting.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index 4f193516..d9bd2797 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -84,7 +84,7 @@ The following sections cover a few of these scenarios and how to fix them. Therefore, the permissions and ownership are copied over and will be **the same** as the ones in your local host (including user ids) which may result in permissions errors when trying to access directories or create/modify files inside. - Suppose your local user has a `UID` and `GID` of `1234`. To fix the UID discrepancies between your local directories and the container's + Suppose your local user has a `UID` and `GID` of `1234` and `5678`, respectively. To fix the UID discrepancies between your local directories and the container's directories, you can run the container with an explicit `NB_UID` and `NB_GID` to match the that of the local user: ```bash @@ -92,12 +92,12 @@ The following sections cover a few of these scenarios and how to fix them. --user root \ -p 8888:8888 \ -e NB_UID=1234 \ - -e NB_GID=1234 \ + -e NB_GID=5678 \ -v '$(PWD)'/test:/home/jovyan/work \ jupyter/minimal-notebook:latest # you should see an output similar to this - # Update jovyan's UID:GID to 1234:1234 + # Update jovyan's UID:GID to 1234:5678 # Running as jovyan: bash ``` @@ -113,7 +113,7 @@ The following sections cover a few of these scenarios and how to fix them. - This approach only updates the UID and GID of the **existing `jovyan` user** instead of creating a new user. From the above example: ```bash id - # uid=1234(jovyan) gid=1234(jovyan) groups=1234(jovyan),100(users) + # uid=1234(jovyan) gid=5678(jovyan) groups=5678(jovyan),100(users) ``` ```` From e7abdae24b5963e556aa5539aa45d0353b100ca2 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 3 Feb 2022 15:11:19 +0000 Subject: [PATCH 22/30] :pencil2: Make " consistent --- docs/using/troubleshooting.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index d9bd2797..b7fd31be 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -93,7 +93,7 @@ The following sections cover a few of these scenarios and how to fix them. -p 8888:8888 \ -e NB_UID=1234 \ -e NB_GID=5678 \ - -v '$(PWD)'/test:/home/jovyan/work \ + -v "$(PWD)"/test:/home/jovyan/work \ jupyter/minimal-notebook:latest # you should see an output similar to this @@ -141,18 +141,17 @@ If you have also **created a new user**, you might be experiencing any of the fo -e CHOWN_HOME=yes \ -e CHOWN_HOME_OPTS="-R" \ -w "/home/${NB_USER}" \ - -v' $(PWD)'/test:/home/callisto/work \ + -v "$(PWD)"/test:/home/callisto/work \ jupyter/minimal-notebook - # expected output - Updated the jovyan user: - - username: jovyan -> callisto - - home dir: /home/jovyan -> /home/callisto - Update callisto UID:GID to 1234:1234 - Attempting to copy /home/jovyan to /home/callisto... - Success! - Ensuring /home/callisto is owned by 1234:1234 - Running as callisto: bash + # Updated the jovyan user: + # - username: jovyan -> callisto + # - home dir: /home/jovyan -> /home/callisto + # Update callisto UID:GID to 1234:1234 + # Attempting to copy /home/jovyan to /home/callisto... + # Success! + # Ensuring /home/callisto is owned by 1234:1234 + # Running as callisto: bash ``` where: @@ -185,7 +184,7 @@ If you have also **created a new user**, you might be experiencing any of the fo -e CHOWN_HOME=yes \ -e CHOWN_HOME_OPTS="-R" \ -w "/home/${NB_USER}" \ - -v $(PWD)/test:/home/callisto/work \ + -v "$(PWD)"/test:/home/callisto/work \ jupyter/minimal-notebook ``` @@ -198,7 +197,7 @@ If you have also **created a new user**, you might be experiencing any of the fo - Pass absolute paths to the `-v` flag: ```bash - -v '$(PWD)'/:/home/jovyan/work + -v "$(PWD)"/:/home/jovyan/work ``` This example uses the syntax `$(PWD)`, which is replaced with the full path to the current directory at runtime. The destination From 6abd7b08c6bc6b293fddaf3df2b90865cb697c97 Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Thu, 3 Feb 2022 18:22:15 +0300 Subject: [PATCH 23/30] Update docs/using/troubleshooting.md --- docs/using/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index b7fd31be..ed99d738 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -117,7 +117,7 @@ The following sections cover a few of these scenarios and how to fix them. ``` ```` -## Permission issues after changing the UID/GIU and USER in the container +## Permission issues after changing the UID/GID and USER in the container If you have also **created a new user**, you might be experiencing any of the following issues: From 4953231f9d2bbd0feac731b10729d4327979be2d Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 3 Feb 2022 15:26:20 +0000 Subject: [PATCH 24/30] :bug: Fix snippet --- docs/using/troubleshooting.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index ed99d738..efd98d9a 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -93,7 +93,7 @@ The following sections cover a few of these scenarios and how to fix them. -p 8888:8888 \ -e NB_UID=1234 \ -e NB_GID=5678 \ - -v "$(PWD)"/test:/home/jovyan/work \ + -v "${PWD}"/test:/home/jovyan/work \ jupyter/minimal-notebook:latest # you should see an output similar to this @@ -141,7 +141,7 @@ If you have also **created a new user**, you might be experiencing any of the fo -e CHOWN_HOME=yes \ -e CHOWN_HOME_OPTS="-R" \ -w "/home/${NB_USER}" \ - -v "$(PWD)"/test:/home/callisto/work \ + -v "${PWD}"/test:/home/callisto/work \ jupyter/minimal-notebook # Updated the jovyan user: @@ -184,7 +184,7 @@ If you have also **created a new user**, you might be experiencing any of the fo -e CHOWN_HOME=yes \ -e CHOWN_HOME_OPTS="-R" \ -w "/home/${NB_USER}" \ - -v "$(PWD)"/test:/home/callisto/work \ + -v "${PWD}"/test:/home/callisto/work \ jupyter/minimal-notebook ``` @@ -197,7 +197,7 @@ If you have also **created a new user**, you might be experiencing any of the fo - Pass absolute paths to the `-v` flag: ```bash - -v "$(PWD)"/:/home/jovyan/work + -v "${PWD}"/:/home/jovyan/work ``` This example uses the syntax `$(PWD)`, which is replaced with the full path to the current directory at runtime. The destination From fc436154f7fd064b42fca2ff811c191fd5445041 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 3 Feb 2022 15:29:11 +0000 Subject: [PATCH 25/30] :heavy_minus_sign: Remove comments --- docs/using/troubleshooting.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index efd98d9a..e718a25a 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -221,9 +221,6 @@ If you have also **created a new user**, you might be experiencing any of the fo - Use `docker inspect ` and look for the [`Mounts` section](https://docs.docker.com/storage/volumes/#start-a-container-with-a-volume) to verify that the volume was created and mounted accordingly: ```json - # for example, for a my-vol volume created with - # docker volume create --name - "Mounts": [ { "Type": "volume", From 6b140174ddbad378e8c25dd93762db56b378c27a Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 3 Feb 2022 15:29:58 +0000 Subject: [PATCH 26/30] :pencil2: Comment outputs --- docs/using/troubleshooting.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index e718a25a..7c072410 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -272,10 +272,10 @@ If you are a regular user of VSCode and the Jupyter extension, you might experie ```bash # example log output from the docker run command - [...] - Or copy and paste one of these URLs: - http://3d4cf3809e3f:8888/?token=996426e890f8dc22fa6835a44442b6026cba02ee61fee6a2 - or http://127.0.0.1:8888/?token=996426e890f8dc22fa6835a44442b6026cba02ee61fee6a2 + # [...] + # Or copy and paste one of these URLs: + # http://3d4cf3809e3f:8888/?token=996426e890f8dc22fa6835a44442b6026cba02ee61fee6a2 + # or http://127.0.0.1:8888/?token=996426e890f8dc22fa6835a44442b6026cba02ee61fee6a2 ``` **Some things to try:** From 39a7497ff4e02d1024f87ff30f5de871eb275312 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 3 Feb 2022 15:30:47 +0000 Subject: [PATCH 27/30] Update docs/using/troubleshooting.md Co-authored-by: Ayaz Salikhov --- docs/using/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index 7c072410..2ab8e7e6 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -203,7 +203,7 @@ If you have also **created a new user**, you might be experiencing any of the fo This example uses the syntax `$(PWD)`, which is replaced with the full path to the current directory at runtime. The destination path should also be an absolute path starting with a `/` such as `home/jovyan/work`. -- You might want to consider using the Docker native `--user ` and `--group-add users` flags instead of `-e NB_GID` and `-e NB_UID`: +- You might want to consider using the Docker native `--user ` and `--group-add users` flags instead of `-e NB_UID` and `-e NB_GID`: ```bash # note this will use the same UID from From 9be8333d19fbadd47f411223d7c7870567cc1573 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Fri, 4 Feb 2022 17:30:46 +0000 Subject: [PATCH 28/30] :pencil2: Fix split --- docs/using/troubleshooting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index 2ab8e7e6..21c55740 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -1,6 +1,7 @@ # Troubleshooting Common Problems -When troubleshooting, you may see unexpected behaviors or receive an error message. This section provides advice on +When troubleshooting, you may see unexpected behaviors or receive an error message. +This section provides advice on how to identify and fix some of the most commonly encountered issues. Most of the `docker run` flags used in this document are explained in detail in the [Common Features, Docker Options section](../using/common.html#Docker-Options) of the documentation. @@ -12,7 +13,6 @@ If you are running a Docker container while mounting a local volume or host dire ```bash docker run -it --rm \ -p 8888:8888 \ - -v : \ jupyter/minimal-notebook:latest ``` From dab76bd6ffaea2a463e27766387d963ca4313d07 Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Sat, 5 Feb 2022 11:10:30 +0300 Subject: [PATCH 29/30] Update docs/using/troubleshooting.md --- docs/using/troubleshooting.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/using/troubleshooting.md b/docs/using/troubleshooting.md index 21c55740..c36a16b2 100644 --- a/docs/using/troubleshooting.md +++ b/docs/using/troubleshooting.md @@ -13,6 +13,7 @@ If you are running a Docker container while mounting a local volume or host dire ```bash docker run -it --rm \ -p 8888:8888 \ + -v : \ jupyter/minimal-notebook:latest ``` From 9a5700a43175937e604c77f37bba1eec552e6c37 Mon Sep 17 00:00:00 2001 From: Ayaz Salikhov Date: Sat, 5 Feb 2022 14:20:33 +0300 Subject: [PATCH 30/30] Add must, where needed --- docs/using/common.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/using/common.md b/docs/using/common.md index 6bd6fcbd..ed393504 100644 --- a/docs/using/common.md +++ b/docs/using/common.md @@ -36,7 +36,7 @@ You do so by passing arguments to the `docker run` command. The default value is `jovyan`. Setting `NB_USER` refits the `jovyan` default user and ensures that the desired user has the correct file permissions for the new home directory created at `/home/`. - For this option to take effect, you must run the container with `--user root`, set the working directory `-w "/home/${NB_USER}"` + For this option to take effect, you **must** run the container with `--user root`, set the working directory `-w "/home/${NB_USER}"` and set the environment variable `-e CHOWN_HOME=yes`. Example usage: @@ -54,7 +54,7 @@ You do so by passing arguments to the `docker run` command. - `-e NB_UID=` - Instructs the startup script to switch the numeric user ID of `${NB_USER}` to the given value. The default value is `1000`. 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.) 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. @@ -63,7 +63,7 @@ You do so by passing arguments to the `docker run` command. - `-e NB_GID=` - Instructs the startup script to change the primary group of `${NB_USER}` to `${NB_GID}` (the new group is added with a name of `${NB_GROUP}` if it is defined. Otherwise, the group is named `${NB_USER}`). This feature is useful when mounting host volumes with specific group 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 group ID.) You might consider using modern Docker options `--user` and `--group-add` instead. See bullet points regarding `--user` and `--group-add`. @@ -87,7 +87,7 @@ You do so by passing arguments to the `docker run` command. `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. 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._ ``` - `-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}`.