Release 23.07

CHANGELOG.md

@@ -6,6 +6,39 @@
 
 ***
 
+### Release 23.07
+
+This release introduces a new feature `FEATURES_OVERRIDING_ENVV`, which controls the overriding or adding of environment variables at the container startup-time.
+Meaning, after the container has already been created.
+
+The feature is enabled by default.
+It can be disabled by setting the variable `FEATURES_OVERRIDING_ENVV` to zero when the container is created or the image is built.
+Be aware that any other value than zero, even if unset or empty, enables the feature.
+
+If `FEATURES_OVERRIDING_ENVV=1`, then the container startup script will look for the file `$HOME/.override/.override_envv.rc` and source all the lines that begin with the string 'export ' at the first position and contain the '=' character.
+
+The overriding file can be provided from outside the container using *bind mounts* or *volumes*.
+
+The lines that have been actually sourced can be reported into the container's log if the startup parameter `--verbose` or `--debug` is provided.
+
+This feature is an enhanced implementation of the previously available functionality known as **Overriding VNC/noVNC parameters at the container startup-time**.
+
+Therefore this is a **breaking change** for the users that already use the VNC/noVNC overriding.
+They need to move the content from the previous file `$HOME"/.vnc_override.rc` into the new file `$HOME/.override/.override_envv.rc`.
+
+### Release 23.03.2
+
+This release mitigates the problems with the edge use case, when users bind the whole `$HOME` directory to an external folder on the host computer.
+
+Please note that I recommend to avoid doing that. If you really want to, then your best bet is using the Docker volumes. That is the only option I've found, which works across the environments. In the sibling discussion thread [#39](https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions/39) I've described the way, how to initialize a bound `$HOME` folder, if you really want to give it a try.
+
+Main changes:
+
+- file `.initial_sudo_password` has been moved from the `$HOME` to the `$STARTUPDIR` folder
+- file `.initial_sudo_password` is not deleted, but cleared after the container user is created
+- startup scripts have been adjusted and improved
+- readme files have been updated
+
 ### Release 23.03.1
 
 This is a maintenance release aiming to improve the scripts and documentation.

docker/Dockerfile.xfce

@@ -44,6 +44,7 @@ RUN \
     --mount=type=cache,from=stage_cache,sharing=locked,source=/var/cache/apt,target=/var/cache/apt \
     --mount=type=cache,from=stage_cache,sharing=locked,source=/var/lib/apt,target=/var/lib/apt \
     DEBIAN_FRONTEND=noninteractive apt-get install -y \
+        gettext-base \
         gir1.2-rsvg-2.0 \
         jq \
         nano \
@@ -292,7 +293,7 @@ COPY ./xfce-firefox/src/firefox.plus/home/readme*.md "${HOME}"/
 
 RUN \
     chmod 744 "${HOME}"/firefox.plus/*.sh \
-    && echo "Exec=${HOME}/firefox.plus/copy_firefox_user_preferences.sh" >> "${HOME}/Desktop/Copy FF Preferences.desktop" \
+    && envsubst <"${HOME}/Desktop/Copy FF Preferences.desktop" >/tmp/esub.tmp && mv -f /tmp/esub.tmp "${HOME}/Desktop/Copy FF Preferences.desktop" \
     && install -o root -g root -m 644 "${HOME}"/firefox.plus/accetto.svg /usr/share/icons/hicolor/scalable/apps/ \
     && gtk-update-icon-cache -f /usr/share/icons/hicolor 
     
@@ -309,9 +310,11 @@ FROM ${ARG_MERGE_STAGE_BROWSER_BASE} as merge_stage_browser
 ###############
 
 FROM ${ARG_FINAL_STAGE_BASE} as stage_final
+ARG ARG_FEATURES_OVERRIDING_ENVV
 ARG ARG_SUDO_INITIAL_PW
 
 ENV \
+    FEATURES_OVERRIDING_ENVV="${ARG_FEATURES_OVERRIDING_ENVV:+1}" \
     FEATURES_VERSION_STICKER=1 \
     STARTUPDIR="/dockerstartup"
 
@@ -325,18 +328,18 @@ COPY ./xfce/src/home/readme*.md "${HOME}"/
 ### Note that the line 'chmod 666 /etc/passwd /etc/group' sets the "softer" permissions only temporary.
 ### It allows the user generator startup script to configure the user and the group correctly.
 ### The script will set the permissions of both files back to the default '644'.
-### The script will aslo delete the file '.initial_sudo_password' after using it.
-### However, note that the initial sudo password will be persisted in the image history.
+### The script will also clear the file '.initial_sudo_password' after using it.
+### However, note that the initial sudo password will still be persisted in the image history.
 ### You have to change it inside the container, if you want to keep it really secret.
 ### Note that all this will not be done, if the startup script will not be executed.
-
 RUN \
     chmod 666 /etc/passwd /etc/group \
     &&  echo "${HEADLESS_USER_NAME}:x:${HEADLESS_USER_ID}:${HEADLESS_USER_GROUP_ID}:Default:${HOME}:/bin/bash" >> /etc/passwd \
     &&  echo "${HEADLESS_USER_NAME}  ALL=(ALL:ALL) ALL" | sudo tee /etc/sudoers.d/"${HEADLESS_USER_NAME}" \
-    &&  echo "${ARG_SUDO_INITIAL_PW:-headless}" > "${HOME}"/.initial_sudo_password \
-    &&  echo "${HEADLESS_USER_NAME}:$(cat "${HOME}"/.initial_sudo_password)" | chpasswd \
+    &&  echo "${ARG_SUDO_INITIAL_PW:-headless}" > "${STARTUPDIR}"/.initial_sudo_password \
+    &&  echo "${HEADLESS_USER_NAME}:$(cat "${STARTUPDIR}"/.initial_sudo_password)" | chpasswd \
     &&  ln -s "${HOME}"/readme.md "${HOME}"/Desktop/README \
+    &&  envsubst <"${HOME}"/Desktop/versionsticker.desktop >/tmp/esub.tmp && mv -f /tmp/esub.tmp "${HOME}"/Desktop/versionsticker.desktop \
     && "${STARTUPDIR}"/set_user_permissions.sh "${STARTUPDIR}" "${HOME}"
 
 

docker/hooks/build

@@ -74,6 +74,7 @@ main() {
             --build-arg ARG_VCS_REF="$(git rev-parse --short HEAD)" \
             \
             ${FEATURES_BUILD_SLIM:+--build-arg ARG_APT_NO_RECOMMENDS=1} \
+            ${FEATURES_OVERRIDING_ENVV:+--build-arg ARG_FEATURES_OVERRIDING_ENVV=1} \
             ${FEATURES_SCREENSHOOTING:+--build-arg ARG_FEATURES_SCREENSHOOTING=1} \
             ${FEATURES_THUMBNAILING:+--build-arg ARG_FEATURES_THUMBNAILING=1} \
             \

docker/hooks/cache

@@ -143,13 +143,18 @@ cache_websockify() {
 main() {
 
     if [[ "${FEATURES_VNC}" == "1" ]] ; then
+
         cache_tigervnc
+        if [[ $? -ne 0 ]] ; then return 1; fi
     fi
 
     if [[ "${FEATURES_NOVNC}" == "1" ]] ; then
 
         cache_novnc
+        if [[ $? -ne 0 ]] ; then return 1; fi
+
         cache_websockify
+        if [[ $? -ne 0 ]] ; then return 1; fi
     fi
 
     echo

docker/hooks/env.rc

@@ -73,9 +73,11 @@ if [[ $# -ge 2 ]] ; then shift 2 ; fi
 ### FEATURES_NOVNC: if 'noVNC' and 'websockify' should be included
 ### FEATURES_SCREENSHOOTING: if 'xfce4-screenshooter' and 'ristretto' should be included
 ### FEATURES_THUMBNAILING: if 'tumbler' should be included
+### FEATURES_OVERRIDING_ENVV: if overriding environment variables at container startup time should be enabled
 ### Remark: There are also 'FEATURES_*' variables that are always set, e.g. 'FEATURES_VERSION_STICKER=1'.
 
 ### These features influence the content of almost all stages:
+### Warning! Anything except '0' means '1', even unset or emty.
 if [[ "${FEATURES_BUILD_SLIM}" == "0" ]] ; then FEATURES_BUILD_SLIM="" ; else FEATURES_BUILD_SLIM=1 ; fi
 
 ### These features influence the content of the related stages:
@@ -86,6 +88,10 @@ if [[ "${FEATURES_THUMBNAILING}" == "1" ]] ; then FEATURES_THUMBNAILING=1 ; else
 if [[ "${FEATURES_CHROMIUM}" == "1" ]] ; then FEATURES_CHROMIUM=1 ; else FEATURES_CHROMIUM="" ; fi
 if [[ "${FEATURES_FIREFOX}" == "1" ]] ; then FEATURES_FIREFOX=1 ; else FEATURES_FIREFOX="" ; fi
 
+### These features influence container behaviour at startup time
+### Warning! Anything except '0' means '1', even unset or emty.
+if [[ "${FEATURES_OVERRIDING_ENVV}" == "0" ]] ; then FEATURES_OVERRIDING_ENVV="" ; else FEATURES_OVERRIDING_ENVV=1 ; fi
+
 ### These features are always enabled and cannot be disabled via environment variables
 FEATURES_VNC=1
 

docker/hooks/pre_build

@@ -65,6 +65,7 @@ main() {
             --build-arg BASETAG="${BASETAG}" \
             \
             ${FEATURES_BUILD_SLIM:+--build-arg ARG_APT_NO_RECOMMENDS=1} \
+            ${FEATURES_OVERRIDING_ENVV:+--build-arg ARG_FEATURES_OVERRIDING_ENVV=1} \
             ${FEATURES_SCREENSHOOTING:+--build-arg ARG_FEATURES_SCREENSHOOTING=1} \
             ${FEATURES_THUMBNAILING:+--build-arg ARG_FEATURES_THUMBNAILING=1} \
             \

docker/src/xfce-startup/startup.sh

@@ -61,6 +61,31 @@ execute_command() {
     fi
 }
 
+envv_override() {
+
+    local envv_override_file="${HOME}"/.override/.override_envv.rc
+    local tmp=""
+
+    ### only if the file is not empty
+    if [[ -s "${envv_override_file}" ]] ; then
+
+        tmp=$( mktemp )
+
+        ### only lines that begin with 'export ' and contain '='
+        ( grep -E '^export\s[^=]+[=]{1}' "${envv_override_file}" 2>/dev/null 1>"${tmp}" )
+
+        if [[ "${_verbose}" == "1" ]] ; then
+
+            echo "Sourcing from file '${envv_override_file}'"
+            cat "${tmp}"
+            echo "End of file '${envv_override_file}'"
+        fi
+
+        source "${tmp}"
+        rm -f "${tmp}"
+    fi
+}
+
 main() {
 
     ### option interdependencies
@@ -74,6 +99,11 @@ main() {
         _arg_skip_novnc="on"
     fi
 
+    if [[ "${_verbose}" == "1" ]] ; then
+
+        echo -e "\nContainer '$(hostname)' started @$(date -u +'%Y-%m-%d_%H-%M-%S')"
+    fi
+
     ### option "--debug"
     if [[ "${_arg_debug}" == "on" ]] ; then
 
@@ -87,8 +117,17 @@ main() {
         echo "ls -la ." ; ls -la .
     fi
 
+    ### override environment variables only if enabled
+    if [[ "${FEATURES_OVERRIDING_ENVV}" == "1" ]] ; then
+    
+        envv_override
+    fi
+
     ### create container user
-    generate_container_user
+    if [[ -s "${STARTUPDIR}"/.initial_sudo_password ]] ; then
+    
+        generate_container_user
+    fi
 
     if [[ "$?" != "0" ]] ; then
 

docker/src/xfce-startup/user_generator.rc

@@ -69,16 +69,19 @@ generate_container_user() {
             fi
         fi
 
-        ### make the newly created user the owner of the following folders including their content
-        cat "${HOME}"/.initial_sudo_password | sudo -S chown -R "${user_id}:${group_id}" "${STARTUPDIR}" "${HOME}" 2>/dev/null
+        if [[ -s "${STARTUPDIR}"/.initial_sudo_password ]] ; then
 
-        ### set the file permissions of the following  to the system default and 
-        ### note that this will also disable this user generator for the future runs (see the outer if-condition above)
-        cat "${HOME}"/.initial_sudo_password | sudo -S chmod 644 /etc/passwd /etc/group 2>/dev/null
+            ### make the newly created user the owner of the following folders including their content
+            cat "${STARTUPDIR}"/.initial_sudo_password | sudo -S chown -R "${user_id}:${group_id}" "${STARTUPDIR}" "${HOME}" 2>/dev/null
 
-        ### remove the file containing the initial sudo password
-        ### be aware that the initial sudo password is still part of the Docker image (see the image history and ARG_SUDO_PW)
-        ### however, you can change it afterwards inside the container
-        cat "${HOME}"/.initial_sudo_password | sudo -S rm -f "${HOME}"/.initial_sudo_password 2>/dev/null
+            ### set the file permissions of the following  to the system default and 
+            ### note that this will also disable this user generator for the future runs (see the outer if-condition above)
+            cat "${STARTUPDIR}"/.initial_sudo_password | sudo -S chmod 644 /etc/passwd /etc/group 2>/dev/null
+
+            ### remove the file containing the initial sudo password
+            ### be aware that the initial sudo password is still part of the Docker image (see the image history and ARG_SUDO_PW)
+            ### however, you can change it afterwards inside the container
+            cat "${STARTUPDIR}"/.initial_sudo_password | sudo -S echo -n "" > "${STARTUPDIR}"/.initial_sudo_password
+        fi
     fi
 }

docker/src/xfce-startup/vnc_startup.rc

@@ -1,18 +1,3 @@
-declare _tmp
-declare _vnc_override_file
-
-_vnc_override_file="${HOME}"/.vnc_override.rc
-
-### if the vnc-override file exists, then import and source
-### only the lines beginning with 'export ' (at position 1)
-if [[ -f "${_vnc_override_file}" ]] ; then
-
-    _tmp=$( mktemp )
-    ( grep -E '^export\s+' "${_vnc_override_file}" 2>/dev/null 1>"${_tmp}" )
-    source "${_tmp}"
-    rm -f "${_tmp}"
-fi
-
 start_vnc () {
     local vnc_ip
     local passwd_path
@@ -69,7 +54,7 @@ start_vnc () {
         echo $(head /dev/urandom | tr -dc A-Za-z0-9 | head -c 20) | vncpasswd -f > "${passwd_path}"
     fi
 
-    echo "${VNC_PW}" | vncpasswd -f >> "${passwd_path}"
+    echo "${VNC_PW}" | vncpasswd -f > "${passwd_path}"
     chmod 600 "${passwd_path}"
 
     ### create VNC configuration file

docker/xfce-chromium/README.md

@@ -26,6 +26,7 @@
     - [Volumes](#volumes)
     - [Version sticker](#version-sticker)
   - [Using headless containers](#using-headless-containers)
+    - [Overriding environment variables](#overriding-environment-variables)
     - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters)
   - [Container user account](#container-user-account)
     - [Overriding container user parameters](#overriding-container-user-parameters)
@@ -237,6 +238,21 @@ It is also possible to provide the password through the links:
 - `http://mynas:26901/vnc_lite.html?password=headless`
 - `http://mynas:26901/vnc.html?password=headless`
 
+### Overriding environment variables
+
+If the environment variable `FEATURES_OVERRIDING_ENVV=1`, which is the case by default, then the container startup script will look for the file `$HOME/.override/.override_envv.rc` and source all the lines that begin with the string 'export ' at the first position and contain the '=' character.
+
+You can provide the overriding file from outside the container using *bind mounts* or *volumes*.
+
+This feature allows overriding or adding environment variables at the **container startup-time**.
+It means, even after the container has already been created.
+
+You can disable this behavior by setting the variable `FEATURES_OVERRIDING_ENVV` to zero when the container is created or the image is built.
+
+The lines that have been actually sourced can be reported into the container's log if the startup parameter `--verbose` or `--debug` is provided.
+
+Look below for the example how to override the VNC/noVNC parameters at the container startup-time.
+
 ### Overriding VNC/noVNC parameters
 
 The VNC/noVNC parameters are controlled by related environment variables embedded into the image.
@@ -271,7 +287,7 @@ For example:
 docker build --build-arg DISPLAY=:2 --build-arg ARG_VNC_PORT=6902  ...
 ```
 
-**At container startup-time** you can override the environment variable values by using the `docker run -e` option. Please note that in this case you have to use the actual environment variable names, not the build argument names (e.g. `VNC_PORT` instead of `ARG_VNC_PORT`).
+**At container creation-time** you can override the environment variable values by using the `docker run -e` option. Please note that in this case you have to use the actual environment variable names, not the build argument names (e.g. `VNC_PORT` instead of `ARG_VNC_PORT`).
 
 For example:
 
@@ -279,29 +295,25 @@ For example:
 docker run -e VNC_PORT=6902 ...
 ```
 
-**At VNC/noVNC startup-time** you can override the environment variable values by binding an external file exporting the variables to the dedicated mounting point `${HOME}/.vnc_override.rc` (a single file, not a directory).
+**At container startup-time** you can override the VNC/noVNC variables using the feature `FEATURES_OVERRIDING_ENVV' described above.
 
 For example, the following command would bind the file `my_own_vnc_parameters.rc` from the directory `/home/joe` to the container:
 
 ```shell
-docker run -v /home/joe/my_own_vnc_parameters.rc:/home/headless/.vnc_override.rc
+docker run -v /home/joe/my_own_vnc_parameters.rc:/home/headless/.override/.override_envv.rc
 ```
 
-The content of the file should be similar to the provided example file `example-vnc-override.rc`:
+The content of the file should be similar to the provided example file `example-override-envv.rc`:
 
 ```shell
-### only lines beginning with 'export ' (at position 1) will be imported and sourced
-;export VNC_COL_DEPTH=32
-;export VNC_VIEW_ONLY=true
-;export VNC_PW=secret
+### only the lines beginning with 'export ' at the first position and containing '=' will be sourced
 export VNC_RESOLUTION=1024x768
-export DISPLAY=:2
-export VNC_PORT=5902
-export NOVNC_PORT=6902
-;export NOVNC_HEARTBEAT=25
+export VNC_PW=secret
+#export DISPLAY=:2
+#export VNC_COL_DEPTH=32
 ```
 
-Please note that only the lines beginning with `export` at the first position will be imported.
+Please note that only the lines beginning with the string 'export ' at the first position and containing the '=' character will be imported.
 
 By providing the variable values the following rules apply:
 
@@ -397,9 +409,11 @@ During this one-time task the startup script needs to modify the container files
 
 The created user gets permissions for `sudo` and the ownership to the content of the home and startup folders.
 
-The temporary file `~/.initial_sudo_password` is also deleted after creating the user.
+The temporary file `${STARTUPDIR}/.initial_sudo_password` is cleared after creating the user.
 
-There is the script `~/tests/test-01.sh` that allows quick check of the current permissions.
+However, note that the initial `sudo` password will still be persisted in the image history. You have to change it inside the container, if you want to keep it really secret.
+
+There is the test script `~/tests/test-01.sh` that allows quick check of the current permissions.
 
 #### Other considerations
 

docker/xfce-firefox/README.md

@@ -26,6 +26,7 @@
     - [Volumes](#volumes)
     - [Version sticker](#version-sticker)
   - [Using headless containers](#using-headless-containers)
+    - [Overriding environment variables](#overriding-environment-variables)
     - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters)
   - [Container user account](#container-user-account)
     - [Overriding container user parameters](#overriding-container-user-parameters)
@@ -235,6 +236,21 @@ It is also possible to provide the password through the links:
 - `http://mynas:26901/vnc_lite.html?password=headless`
 - `http://mynas:26901/vnc.html?password=headless`
 
+### Overriding environment variables
+
+If the environment variable `FEATURES_OVERRIDING_ENVV=1`, which is the case by default, then the container startup script will look for the file `$HOME/.override/.override_envv.rc` and source all the lines that begin with the string 'export ' at the first position and contain the '=' character.
+
+You can provide the overriding file from outside the container using *bind mounts* or *volumes*.
+
+This feature allows overriding or adding environment variables at the **container startup-time**.
+It means, even after the container has already been created.
+
+You can disable this behavior by setting the variable `FEATURES_OVERRIDING_ENVV` to zero when the container is created or the image is built.
+
+The lines that have been actually sourced can be reported into the container's log if the startup parameter `--verbose` or `--debug` is provided.
+
+Look below for the example how to override the VNC/noVNC parameters at the container startup-time.
+
 ### Overriding VNC/noVNC parameters
 
 The VNC/noVNC parameters are controlled by related environment variables embedded into the image.
@@ -269,7 +285,7 @@ For example:
 docker build --build-arg DISPLAY=:2 --build-arg ARG_VNC_PORT=6902  ...
 ```
 
-**At container startup-time** you can override the environment variable values by using the `docker run -e` option. Please note that in this case you have to use the actual environment variable names, not the build argument names (e.g. `VNC_PORT` instead of `ARG_VNC_PORT`).
+**At container creation-time** you can override the environment variable values by using the `docker run -e` option. Please note that in this case you have to use the actual environment variable names, not the build argument names (e.g. `VNC_PORT` instead of `ARG_VNC_PORT`).
 
 For example:
 
@@ -277,29 +293,25 @@ For example:
 docker run -e VNC_PORT=6902 ...
 ```
 
-**At VNC/noVNC startup-time** you can override the environment variable values by binding an external file exporting the variables to the dedicated mounting point `${HOME}/.vnc_override.rc` (a single file, not a directory).
+**At container startup-time** you can override the VNC/noVNC variables using the feature `FEATURES_OVERRIDING_ENVV' described above.
 
 For example, the following command would bind the file `my_own_vnc_parameters.rc` from the directory `/home/joe` to the container:
 
 ```shell
-docker run -v /home/joe/my_own_vnc_parameters.rc:/home/headless/.vnc_override.rc
+docker run -v /home/joe/my_own_vnc_parameters.rc:/home/headless/.override/.override_envv.rc
 ```
 
-The content of the file should be similar to the provided example file `example-vnc-override.rc`:
+The content of the file should be similar to the provided example file `example-override-envv.rc`:
 
 ```shell
-### only lines beginning with 'export ' (at position 1) will be imported and sourced
-;export VNC_COL_DEPTH=32
-;export VNC_VIEW_ONLY=true
-;export VNC_PW=secret
+### only the lines beginning with 'export ' at the first position and containing '=' will be sourced
 export VNC_RESOLUTION=1024x768
-export DISPLAY=:2
-export VNC_PORT=5902
-export NOVNC_PORT=6902
-;export NOVNC_HEARTBEAT=25
+export VNC_PW=secret
+#export DISPLAY=:2
+#export VNC_COL_DEPTH=32
 ```
 
-Please note that only the lines beginning with `export` at the first position will be imported.
+Please note that only the lines beginning with the string 'export ' at the first position and containing the '=' character will be imported.
 
 By providing the variable values the following rules apply:
 
@@ -395,9 +407,11 @@ During this one-time task the startup script needs to modify the container files
 
 The created user gets permissions for `sudo` and the ownership to the content of the home and startup folders.
 
-The temporary file `~/.initial_sudo_password` is also deleted after creating the user.
+The temporary file `${STARTUPDIR}/.initial_sudo_password` is cleared after creating the user.
 
-There is the script `~/tests/test-01.sh` that allows quick check of the current permissions.
+However, note that the initial `sudo` password will still be persisted in the image history. You have to change it inside the container, if you want to keep it really secret.
+
+There is the test script `~/tests/test-01.sh` that allows quick check of the current permissions.
 
 #### Other considerations
 

docker/xfce-firefox/src/firefox.plus/home/Desktop/Copy FF Preferences.desktop

@@ -8,3 +8,4 @@ Path=
 Terminal=true
 StartupNotify=true
 GenericName=Copy FF Preferences
+Exec=${HOME}/firefox.plus/copy_firefox_user_preferences.sh

docker/xfce/README.md

@@ -26,6 +26,7 @@
     - [Volumes](#volumes)
     - [Version sticker](#version-sticker)
   - [Using headless containers](#using-headless-containers)
+    - [Overriding environment variables](#overriding-environment-variables)
     - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters)
   - [Container user account](#container-user-account)
     - [Overriding container user parameters](#overriding-container-user-parameters)
@@ -225,6 +226,21 @@ It is also possible to provide the password through the links:
 - `http://mynas:26901/vnc_lite.html?password=headless`
 - `http://mynas:26901/vnc.html?password=headless`
 
+### Overriding environment variables
+
+If the environment variable `FEATURES_OVERRIDING_ENVV=1`, which is the case by default, then the container startup script will look for the file `$HOME/.override/.override_envv.rc` and source all the lines that begin with the string 'export ' at the first position and contain the '=' character.
+
+You can provide the overriding file from outside the container using *bind mounts* or *volumes*.
+
+This feature allows overriding or adding environment variables at the **container startup-time**.
+It means, even after the container has already been created.
+
+You can disable this behavior by setting the variable `FEATURES_OVERRIDING_ENVV` to zero when the container is created or the image is built.
+
+The lines that have been actually sourced can be reported into the container's log if the startup parameter `--verbose` or `--debug` is provided.
+
+Look below for the example how to override the VNC/noVNC parameters at the container startup-time.
+
 ### Overriding VNC/noVNC parameters
 
 The VNC/noVNC parameters are controlled by related environment variables embedded into the image.
@@ -259,7 +275,7 @@ For example:
 docker build --build-arg DISPLAY=:2 --build-arg ARG_VNC_PORT=6902  ...
 ```
 
-**At container startup-time** you can override the environment variable values by using the `docker run -e` option. Please note that in this case you have to use the actual environment variable names, not the build argument names (e.g. `VNC_PORT` instead of `ARG_VNC_PORT`).
+**At container creation-time** you can override the environment variable values by using the `docker run -e` option. Please note that in this case you have to use the actual environment variable names, not the build argument names (e.g. `VNC_PORT` instead of `ARG_VNC_PORT`).
 
 For example:
 
@@ -267,29 +283,25 @@ For example:
 docker run -e VNC_PORT=6902 ...
 ```
 
-**At VNC/noVNC startup-time** you can override the environment variable values by binding an external file exporting the variables to the dedicated mounting point `${HOME}/.vnc_override.rc` (a single file, not a directory).
+**At container startup-time** you can override the VNC/noVNC variables using the feature `FEATURES_OVERRIDING_ENVV' described above.
 
 For example, the following command would bind the file `my_own_vnc_parameters.rc` from the directory `/home/joe` to the container:
 
 ```shell
-docker run -v /home/joe/my_own_vnc_parameters.rc:/home/headless/.vnc_override.rc
+docker run -v /home/joe/my_own_vnc_parameters.rc:/home/headless/.override/.override_envv.rc
 ```
 
-The content of the file should be similar to the provided example file `example-vnc-override.rc`:
+The content of the file should be similar to the provided example file `example-override-envv.rc`:
 
 ```shell
-### only lines beginning with 'export ' (at position 1) will be imported and sourced
-;export VNC_COL_DEPTH=32
-;export VNC_VIEW_ONLY=true
-;export VNC_PW=secret
+### only the lines beginning with 'export ' at the first position and containing '=' will be sourced
 export VNC_RESOLUTION=1024x768
-export DISPLAY=:2
-export VNC_PORT=5902
-export NOVNC_PORT=6902
-;export NOVNC_HEARTBEAT=25
+export VNC_PW=secret
+#export DISPLAY=:2
+#export VNC_COL_DEPTH=32
 ```
 
-Please note that only the lines beginning with `export` at the first position will be imported.
+Please note that only the lines beginning with the string 'export ' at the first position and containing the '=' character will be imported.
 
 By providing the variable values the following rules apply:
 
@@ -385,9 +397,11 @@ During this one-time task the startup script needs to modify the container files
 
 The created user gets permissions for `sudo` and the ownership to the content of the home and startup folders.
 
-The temporary file `~/.initial_sudo_password` is also deleted after creating the user.
+The temporary file `${STARTUPDIR}/.initial_sudo_password` is cleared after creating the user.
 
-There is the script `~/tests/test-01.sh` that allows quick check of the current permissions.
+However, note that the initial `sudo` password will still be persisted in the image history. You have to change it inside the container, if you want to keep it really secret.
+
+There is the test script `~/tests/test-01.sh` that allows quick check of the current permissions.
 
 #### Other considerations
 

docker/xfce/src/home/Desktop/versionsticker.desktop

@@ -3,8 +3,8 @@ Version=1.0
 Type=Application
 Name=Version Sticker
 Comment=Verbose version sticker
-Exec=bash -c 'echo "Wait..." ; /dockerstartup/version_sticker.sh -f -V ; read -p "Press ENTER..."'
-Path=/dockerstartup
+Exec=bash -c 'echo "Wait..." ; ${STARTUPDIR}/version_sticker.sh -f -V ; read -p "Press ENTER..."'
+Path=${STARTUPDIR}
 Terminal=true
 StartupNotify=false
 Icon=application-certificate

examples/Dockerfile.extend

@@ -2,6 +2,17 @@
 
 ### This is an example of extending the images.
 
+### HINTS
+### Sometimes you can get building errors related to cache handling.
+### One of the following usually helps:
+### (1) Use the '--no-cache' option
+###     > docker build ... --no-cache
+### (2) Purge the builder cache before and/or between builds
+###     > docker builder prune
+### (3) Re-open the terminal and/or Visual Studio Code
+### (4) Remove the line containing 'rm -rf /var/lib/apt/lists/*'
+###     from your extending Dockerfile (like this one)
+
 ### choose a base image and tag
 ARG BASEIMAGE="accetto/debian-vnc-xfce-g3"
 # ARG BASEIMAGE="accetto/debian-vnc-xfce-chromium-g3"
@@ -27,9 +38,13 @@ RUN \
 # COPY ./bashrc "${HOME}"/.bashrc
 # COPY ./firefox.plus/user.js "${HOME}"/firefox.plus/
 
+### avoid the pitfall of failing startup under some circumstances
+### permissions will be set to the system defaults on the first container start
+RUN chmod 666 /etc/passwd /etc/group
+
 ### usually you want to swich back to a non-root user
 ### alternatively you can do it in a compose file (see 'example.yml')
-USER 1000
+USER "${HEADLESS_USER_ID}"
 
 ### note that some applications refuse to be installed under the root user
 ### those you have to install after switching the user

examples/example-override-envv.rc

@@ -0,0 +1,5 @@
+### only the lines beginning with 'export ' at the first position and containing '=' will be sourced
+export VNC_RESOLUTION=1024x768
+export VNC_PW=secret
+#export DISPLAY=:2
+#export VNC_COL_DEPTH=32

examples/example-secrets.rc

@@ -56,6 +56,7 @@ export DOCKER_BUILDKIT=1
 ### explicitly disable features that are enabled by default
 # # export FEATURES_NOVNC=0
 # # export FEATURES_FIREFOX_PLUS=0
+# # export FEATURES_OVERRIDING_ENVV=0
 
 #endregion
 
@@ -89,6 +90,7 @@ export DOCKER_BUILDKIT=1
 # ### explicitly disable features that are enabled by default
 # # export FEATURES_NOVNC=0
 # # export FEATURES_FIREFOX_PLUS=0
+# # export FEATURES_OVERRIDING_ENVV=0
 
 #endregion
 

examples/example-vnc-override.rc

@@ -1,9 +0,0 @@
-### only lines beginning with 'export ' (at position 1) will be imported and sourced
-;export VNC_COL_DEPTH=32
-;export VNC_VIEW_ONLY=true
-;export VNC_PW=secret
-export VNC_RESOLUTION=1024x768
-export DISPLAY=:2
-export VNC_PORT=5902
-export NOVNC_PORT=6902
-;export NOVNC_HEARTBEAT=25