README.md, CUDA.md: Update section 'Run container'

#1

Author: benz0li

CUDA.md

@@ -98,22 +98,26 @@ Create an empty directory:
 ```bash
 mkdir jupyterlab-jovyan
 sudo chown 1000:100 jupyterlab-jovyan
-cd jupyterlab-jovyan
 ```
 
 It will be *bind mounted* as the JupyterLab user's home directory and
 automatically populated on first run.
 
 ### Run container
 
+| :exclamation: Always mount the user's **entire** home directory.<br>Mounting a subfolder prevents the container from starting.[^1] |
+|------------------------------------------------------------------------------------------------------------------------------------|
+
+[^1]: The only exception is the use case described at [Jupyter Docker Stacks > Quick Start > Example 2](https://github.com/jupyter/docker-stacks#quick-start).
+
 self built:
 
 ```bash
 docker run -it --rm \
   --gpus '"device=all"' \
   -p 8888:8888 \
   -u root \
-  -v "${PWD}":/home/jovyan \
+  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
   -e NB_UID=$(id -u) \
   -e NB_GID=$(id -g) \
   -e CHOWN_HOME=yes \
@@ -128,7 +132,7 @@ docker run -it --rm \
   --gpus '"device=all"' \
   -p 8888:8888 \
   -u root \
-  -v "${PWD}":/home/jovyan \
+  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
   -e NB_UID=$(id -u) \
   -e NB_GID=$(id -g) \
   -e CHOWN_HOME=yes \
@@ -141,8 +145,8 @@ docker run -it --rm \
 * [`glcr.b-data.ch/jupyterlab/cuda/python/base`](https://gitlab.b-data.ch/jupyterlab/cuda/python/base/container_registry)
 * [`glcr.b-data.ch/jupyterlab/cuda/python/scipy`](https://gitlab.b-data.ch/jupyterlab/cuda/python/scipy/container_registry)
 
-The use of the `-v` flag in the command mounts the current working directory on
-the host (`${PWD}` in the command) as `/home/jovyan` in the container.
+The use of the `-v` flag in the command mounts the empty directory on the host
+(`${PWD}/jupyterlab-jovyan` in the command) as `/home/jovyan` in the container.
 
 `-e NB_UID=$(id -u) -e NB_GID=$(id -g)` instructs the startup script to switch
 the user ID and the primary group ID of `${NB_USER}` to the user and group ID of
@@ -163,7 +167,7 @@ The server logs appear in the terminal.
 docker run -it --rm \
   --gpus '"device=all"' \
   -p 8888:8888 \
-  -v "${PWD}":/home/jovyan \
+  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
   IMAGE[:MAJOR[.MINOR[.PATCH]]]
 ```
 

README.md

@@ -120,21 +120,25 @@ Create an empty directory:
 ```bash
 mkdir jupyterlab-jovyan
 sudo chown 1000:100 jupyterlab-jovyan
-cd jupyterlab-jovyan
 ```
 
 It will be *bind mounted* as the JupyterLab user's home directory and
 automatically populated on first run.
 
 ### Run container
 
+| :exclamation: Always mount the user's **entire** home directory.<br>Mounting a subfolder prevents the container from starting.[^1] |
+|------------------------------------------------------------------------------------------------------------------------------------|
+
+[^1]: The only exception is the use case described at [Jupyter Docker Stacks > Quick Start > Example 2](https://github.com/jupyter/docker-stacks#quick-start).
+
 self built:
 
 ```bash
 docker run -it --rm \
   -p 8888:8888 \
   -u root \
-  -v "${PWD}":/home/jovyan \
+  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
   -e NB_UID=$(id -u) \
   -e NB_GID=$(id -g) \
   -e CHOWN_HOME=yes \
@@ -148,7 +152,7 @@ from the project's GitLab Container Registries:
 docker run -it --rm \
   -p 8888:8888 \
   -u root \
-  -v "${PWD}":/home/jovyan \
+  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
   -e NB_UID=$(id -u) \
   -e NB_GID=$(id -g) \
   -e CHOWN_HOME=yes \
@@ -161,8 +165,8 @@ docker run -it --rm \
 * [`glcr.b-data.ch/jupyterlab/python/base`](https://gitlab.b-data.ch/jupyterlab/python/base/container_registry)
 * [`glcr.b-data.ch/jupyterlab/python/scipy`](https://gitlab.b-data.ch/jupyterlab/python/scipy/container_registry)
 
-The use of the `-v` flag in the command mounts the current working directory on
-the host (`${PWD}` in the command) as `/home/jovyan` in the container.
+The use of the `-v` flag in the command mounts the empty directory on the host
+(`${PWD}/jupyterlab-jovyan` in the command) as `/home/jovyan` in the container.
 
 `-e NB_UID=$(id -u) -e NB_GID=$(id -g)` instructs the startup script to switch
 the user ID and the primary group ID of `${NB_USER}` to the user and group ID of
@@ -182,7 +186,7 @@ The server logs appear in the terminal.
 ```bash
 docker run -it --rm \
   -p 8888:8888 \
-  -v "${PWD}":/home/jovyan \
+  -v "${PWD}/jupyterlab-jovyan":/home/jovyan \
   IMAGE[:MAJOR[.MINOR[.PATCH]]]
 ```