Enable bind mounting a subfolder of the home directory

- Resolve #1

Author: benz0li

CUDA.md

@@ -106,15 +106,12 @@ docker run --rm \
 ```
 
 It will be *bind mounted* as the JupyterLab user's home directory and
-automatically populated on first run.
+automatically populated.  
+:exclamation: *Bind mounting* a subfolder of the home directory is only possible
+for images with Python version ≥ 3.12.2.
 
 ### 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

README.md

@@ -154,15 +154,12 @@ docker run --rm \
 ```
 
 It will be *bind mounted* as the JupyterLab user's home directory and
-automatically populated on first run.
+automatically populated.  
+:exlamation: *Bind mounting* a subfolder of the home directory is only possible
+for images with Python version ≥ 3.12.2.
 
 ### 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
@@ -255,10 +252,10 @@ docker run -it --rm \
 
 | Extension                       | Environment variable                                                                                                                                                |
 |:--------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| GitHub Pull Requests and Issues | `GITHUB_TOKEN`: Personal access token with scopes `repo` and `user`.[^2]                                                                                            |
+| GitHub Pull Requests and Issues | `GITHUB_TOKEN`: Personal access token with scopes `repo` and `user`.[^1]                                                                                            |
 | GitLab Workflow                 | `GITLAB_WORKFLOW_INSTANCE_URL`: GitLab instance URL (e.g. https://gitlab.com).<br>`GITLAB_WORKFLOW_TOKEN`: Personal access token with scopes `api` and `read_user`. |
 
-[^2]: *Device activation* may require a one-time login from the extension's sidebar.
+[^1]: *Device activation* may require a one-time login from the extension's sidebar.
 
 ## Similar projects
 

base/latest.Dockerfile

@@ -177,6 +177,11 @@ RUN dpkgArch="$(dpkg --print-architecture)" \
   fi \
   ## Add user
   && useradd -l -m -s $(which zsh) -N -u ${NB_UID} ${NB_USER} \
+  ## Mark home directory as populated
+  && touch /home/${NB_USER}/.populated \
+  && chown ${NB_UID}:${NB_GID} /home/${NB_USER}/.populated \
+  && chmod go+w /home/${NB_USER}/.populated \
+  ## Create backup directory for home directory
   && mkdir -p /var/backups/skel \
   && chown ${NB_UID}:${NB_GID} /var/backups/skel \
   ## Install Tini
@@ -277,6 +282,8 @@ RUN sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master
   && echo "[[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh" >> ${HOME}/.zshrc \
   ## Create user's private bin
   && mkdir -p ${HOME}/.local/bin \
+  ## Record population timestamp
+  && date -uIseconds > ${HOME}/.populated \
   ## Create backup of home directory
   && cp -a ${HOME}/. /var/backups/skel
 

base/scripts/usr/local/bin/start-notebook.d/10-populate.sh

@@ -4,10 +4,22 @@
 
 set -e
 
-if [ "$(ls -A "/home/jovyan" 2> /dev/null)" == "" ]; then
-  _log "Populating home dir /home/jovyan..."
-  if cp -a /var/backups/skel/. /home/jovyan; then
-    _log "Success!"
+if [ ! -f /home/jovyan/.populated ]; then
+  # Create list of missing files (top level only)
+  fd="$(comm -13 <(cd /home/jovyan; ls -A) <(cd /var/backups/skel; ls -A) \
+    | paste -sd ',' -)"
+  # Handle case when only marker is missing
+  if [[ "${fd}" == ".populated" ]]; then
+    sf="${fd}"
+  else
+    sf="{${fd}}"
+  fi
+  _log "Populating home dir: /home/jovyan"
+  _log "Copying files/directories (recursively):"
+  _log "- ${fd}"
+  if eval "cp -a /var/backups/skel/${sf} /home/jovyan"; then
+    date -uIseconds > /home/jovyan/.populated
+    _log "Done populating home dir"
   else
     _log "ERROR: Failed to copy data from /var/backups/skel to /home/jovyan!"
     exit 1

base/scripts/usr/local/bin/start.sh

@@ -139,12 +139,23 @@ if [ "$(id -u)" == 0 ] ; then
                     exit 1
                 fi
             fi
-        # The home directory could be bind mounted. Populate it if it is empty
-        elif [[ "$(ls -A "/home/${NB_USER}${DOMAIN:+@$DOMAIN}" 2> /dev/null)" == "" ]]; then
-            _log "Populating home dir /home/${NB_USER}${DOMAIN:+@$DOMAIN}..."
-            # shellcheck disable=SC2086
-            if cp ${CP_OPTS:--a} /home/jovyan/. "/home/${NB_USER}${DOMAIN:+@$DOMAIN}/"; then
-                _log "Success!"
+        # The home directory could be bind mounted. Populate it.
+        elif [[ ! -f "/home/${NB_USER}${DOMAIN:+@$DOMAIN}/.populated" ]]; then
+            # Create list of missing files (top level only)
+            fd="$(comm -13 <(cd  "/home/${NB_USER}${DOMAIN:+@$DOMAIN}"; ls -A) <(cd /home/jovyan; ls -A) \
+                | paste -sd ',' -)"
+            # Handle case when only marker is missing
+            if [[ "${fd}" == ".populated" ]]; then
+                sf="${fd}"
+            else
+                sf="{${fd}}"
+            fi
+            _log "Populating home dir: /home/${NB_USER}${DOMAIN:+@$DOMAIN}"
+            _log "Copying files/directories (recursively):"
+            _log "- ${fd}"
+            if eval "cp ${CP_OPTS:--a} /home/jovyan/${sf} /home/${NB_USER}${DOMAIN:+@$DOMAIN}"; then
+                date -uIseconds > "/home/${NB_USER}${DOMAIN:+@$DOMAIN}/.populated"
+                _log "Done populating home dir"
             else
                 _log "ERROR: Failed to copy data from /home/jovyan to /home/${NB_USER}${DOMAIN:+@$DOMAIN}!"
                 exit 1
@@ -159,10 +170,18 @@ if [ "$(id -u)" == 0 ] ; then
         fi
     fi
 
+    # Trigger changing ownership of the desired user's home folder
+    if [[ "${CP_OPTS}" == "" && "$(stat -c '%u:%g' "/home/${NB_USER}${DOMAIN:+@$DOMAIN}")" != "$(id -u "${NB_USER}"):$(id -g "${NB_USER}")" ]]; then
+        if [[ "${CHOWN_HOME}" != "1" && "${CHOWN_HOME}" != "yes" ]]; then
+            export CHOWN_HOME="1"
+            trg_msg="(Automatic) "
+        fi
+    fi
+
     # Optionally ensure the desired user get filesystem ownership of it's home
     # folder and/or additional folders
     if [[ "${CHOWN_HOME}" == "1" || "${CHOWN_HOME}" == "yes" ]]; then
-        _log "Ensuring /home/${NB_USER}${DOMAIN:+@$DOMAIN} is owned by ${NB_UID}:${NB_GID} ${CHOWN_HOME_OPTS:+(chown options: ${CHOWN_HOME_OPTS})}"
+        _log "${trg_msg}Ensuring /home/${NB_USER}${DOMAIN:+@$DOMAIN} is owned by ${NB_UID}:${NB_GID} ${CHOWN_HOME_OPTS:+(chown options: ${CHOWN_HOME_OPTS})}"
         if [[ ! -L "/home/${NB_USER}${DOMAIN:+@$DOMAIN}/mnt" || ("$(stat -c '%u:%g' "/home/${NB_USER}${DOMAIN:+@$DOMAIN}/mnt")" != "$(id -u "${NB_USER}"):$(id -g "${NB_USER}")") ]]; then
             # shellcheck disable=SC2086
             chown ${CHOWN_HOME_OPTS} "${NB_UID}:${NB_GID}" "/home/${NB_USER}${DOMAIN:+@$DOMAIN}"
@@ -178,6 +197,14 @@ if [ "$(id -u)" == 0 ] ; then
             fi
         fi
     fi
+    if [[ "${CP_OPTS}" == "" && "${sf}" != "" ]]; then
+        if [[ "$(stat -c '%u:%g' "/home/${NB_USER}${DOMAIN:+@$DOMAIN}/.populated")" != "$(id -u "${NB_USER}"):$(id -g "${NB_USER}")" ]]; then
+            _log "(Automatic) Ensuring the following files/directories in /home/${NB_USER}${DOMAIN:+@$DOMAIN} are owned by ${NB_UID}:${NB_GID} (chown options: -R):"
+            _log "- ${fd}"
+            # shellcheck disable=SC2086
+            eval "chown -R ${NB_UID}:${NB_GID} /home/${NB_USER}${DOMAIN:+@$DOMAIN}/${sf}"
+        fi
+    fi
     if [ -n "${CHOWN_EXTRA}" ]; then
         for extra_dir in $(echo "${CHOWN_EXTRA}" | tr ',' ' '); do
             _log "Ensuring ${extra_dir} is owned by ${NB_UID}:${NB_GID} ${CHOWN_EXTRA_OPTS:+(chown options: ${CHOWN_EXTRA_OPTS})}"