docker-stacks/docs/using/troubleshooting.md

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.

Permission Issues

Permission denied when mounting local directories

If you are running a Docker container while mounting a local volume or host directory using the -v flag like so:

  docker run -it --rm \
      -v <local-dir>:/home/jovyan/work jupyter/datascience-notebook

you might face permissions issues when trying to access the mounted directory:

$ 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:

     docker run -it --rm \
         -e NB_UID=1000 \
         -e NB_GID=1000 \
         --user root \
         -v <local-dir>:/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:

  -v $(PWD)/<local-dir>:/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 <UID> and --group-add <GID>:

  # 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 <local-dir>:/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.