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

📝 Replace notes with admonitions

Browse Source
This commit is contained in:
Tania Allard
2022-02-03 11:28:05 +00:00
parent 66566d9bd0
commit 1445af51f6
1 changed files with 24 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/using/troubleshooting.md
View File

@@ -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 <my-volume>`
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 <my-volume>`
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=<some-dir>` 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=<some-dir>` 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)/<my-vol>:/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 <UID>` and `--group-add users` flags instead of `-e NB_GID` and `-e NB_UID`: