Release 23.07

cache hook script improved
utilizing 'envsubst'
2023-07-21 13:40:25 +02:00 · 2023-06-27 10:24:02 +02:00 · 2023-04-23 20:15:04 +02:00 · 2023-04-16 12:18:59 +02:00 · 2023-03-24 14:27:03 +01:00 · 2023-03-24 14:25:24 +01:00
30 changed files with 534 additions and 183 deletions
@@ -6,6 +6,48 @@

 ***

+### 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.
+
+### Release 23.03
+
+- updated with `TigerVNC 1.13.1` bugfix release
+- also some updates in readme files
+
 ### Release 23.02

 The initial version of the project has been derived from the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] (version G3v4, release 23.02.1).
@@ -25,21 +25,21 @@ Version: G3v1

 - [Headless Debian/Xfce containers with VNC/noVNC](#headless-debianxfce-containers-with-vncnovnc)
  - [Project `accetto/debian-vnc-xfce-g3`](#project-accettodebian-vnc-xfce-g3)
-    - [Introduction](#introduction)
-    - [TL;DR](#tldr)
-      - [Installing packages](#installing-packages)
-      - [Shared memory size](#shared-memory-size)
-      - [Extending images](#extending-images)
-      - [Building images](#building-images)
-      - [Sharing devices](#sharing-devices)
-    - [Image generations](#image-generations)
-    - [Project versions](#project-versions)
-    - [Project goals](#project-goals)
-    - [Project features](#project-features)
+  - [Introduction](#introduction)
+  - [TL;DR](#tldr)
+    - [Installing packages](#installing-packages)
+    - [Shared memory size](#shared-memory-size)
+    - [Extending images](#extending-images)
+    - [Building images](#building-images)
+    - [Sharing devices](#sharing-devices)
+  - [Image generations](#image-generations)
+  - [Project versions](#project-versions)
+  - [Project goals](#project-goals)
+  - [Project features](#project-features)
  - [Issues, Wiki and Discussions](#issues-wiki-and-discussions)
  - [Credits](#credits)

-### Introduction
+## Introduction

 This repository contains resources for building Docker images based on [Debian 11][docker-debian] with [Xfce][xfce] desktop environment and [VNC][tigervnc]/[noVNC][novnc] servers for headless use.

@@ -47,7 +47,7 @@ The resources for the individual images and their variations (tags) are stored i

 The repository has been derived from the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] containing similar images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu].

-### TL;DR
+## TL;DR

 There are currently resources for the following Docker images:

@@ -60,7 +60,7 @@ There are currently resources for the following Docker images:
 - [accetto/debian-vnc-xfce-firefox-g3][accetto-docker-debian-vnc-xfce-firefox-g3]
  - [full Readme][this-readme-image-firefox]

-#### Installing packages
+### Installing packages

 I try to keep the images slim. Consequently you can sometimes encounter missing dependencies while adding more applications yourself. You can track the missing libraries on the [Debian Packages Search][debian-packages-search] page and install them subsequently.

@@ -73,7 +73,7 @@ sudo apt-get update
 sudo apt --fix-broken install
 ```

-#### Shared memory size
+### Shared memory size

 Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior.

@@ -85,7 +85,7 @@ df -h /dev/shm

 The older sibling Wiki page [Firefox multi-process][that-wiki-firefox-multiprocess] describes several ways, how to increase the shared memory size.

-#### Extending images
+### Extending images

 The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images.

@@ -93,7 +93,7 @@ Your concrete `Dockerfile` may need more statements, but the concept should be c

 The compose file `example.yml` shows how to switch to another non-root user and how to set the VNC password and resolution.

-#### Building images
+### Building images

 The fastest way to build the images:

@@ -125,9 +125,9 @@ The fastest way to build the images:
 ### and so on
 ```

-You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the files `local-builder-readme.md`, `local-building-example.md` and the [sibling Wiki][sibling-wiki] for more information.
+You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information.

-#### Sharing devices
+### Sharing devices

 Sharing the audio device for video with sound works only with `Chromium` and only on Linux:

@@ -165,21 +165,21 @@ docker run -it -P --rm \
 xhost -local:$(whoami)
 ```

-### Image generations
+## Image generations

 This is the **third generation** (G3) of my headless images. The **second generation** (G2) contains the GitHub repository [accetto/xubuntu-vnc-novnc][accetto-github-xubuntu-vnc-novnc]. The **first generation** (G1) contains the GitHub repository [accetto/ubuntu-vnc-xfce][accetto-github-ubuntu-vnc-xfce].

-### Project versions
+## Project versions

 This file describes the **first generation** (G3v1) of this project, which however corresponds to the **fourth version** (G3v4) of the **sibling project** [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3].

 Please refer to the [sibling project][accetto-github-ubuntu-vnc-xfce-g3_project-versions] to learn more about the older project versions.

-### Project goals
+## Project goals

 Please refer to the [sibling project][accetto-github-ubuntu-vnc-xfce-g3_project-goals] to learn more about the project goals.

-### Project features
+## Project features

 Please refer to the [sibling project][accetto-github-ubuntu-vnc-xfce-g3_project-features] to learn more about the project features.

@@ -205,14 +205,15 @@ Credit goes to all the countless people and companies, who contribute to open so
 <!-- [this-github]: https://github.com/accetto/debian-vnc-xfce-g3/ -->
 [this-issues]: https://github.com/accetto/debian-vnc-xfce-g3/issues

-[this-diagram-dockerfile-stages]: https://raw.githubusercontent.com/accetto/debian-vnc-xfce-g3/master/docker/doc/images/Dockerfile.xfce.png
-
 [this-dockerfile]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/docker/Dockerfile.xfce

 [this-readme-image-base]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/docker/xfce/README.md
 [this-readme-image-chromium]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/docker/xfce-chromium/README.md
 [this-readme-image-firefox]: https://github.com/accetto/debian-vnc-xfce-g3/tree/master/docker/xfce-firefox

+[this-builder-readme]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-builder.md
+[this-readme-local-building-example]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-local-building-example.md
+
 [accetto-docker-debian-vnc-xfce-g3]: https://hub.docker.com/r/accetto/debian-vnc-xfce-g3
 [accetto-docker-debian-vnc-xfce-chromium-g3]: https://hub.docker.com/r/accetto/debian-vnc-xfce-chromium-g3
 [accetto-docker-debian-vnc-xfce-firefox-g3]: https://hub.docker.com/r/accetto/debian-vnc-xfce-firefox-g3
@@ -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}"


@@ -1,4 +1,4 @@
-#!/bin/bash -e
+#!/bin/bash

 echo -e "\n==> EXECUTING @$(date -u +'%Y-%m-%d_%H-%M-%S'): ${0} $@\n"

@@ -66,7 +66,6 @@ main() {
    ### no quotes around 'params'
    docker build ${params} \
        -f "${DOCKERFILE_PATH}" \
-            --build-arg BUILDKIT_INLINE_CACHE=1 \
            --build-arg BASEIMAGE="${BASEIMAGE}" \
            --build-arg BASETAG="${BASETAG}" \
            --build-arg ARG_CREATED="${now}" \
@@ -75,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} \
            \
@@ -1,4 +1,5 @@
-#!/bin/bash -e
+#!/bin/bash
+
 ### @accetto, September 2022
 ### updated: January 2023

@@ -142,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
@@ -156,7 +162,6 @@ main() {

 declare _quiet=""
 declare _mark="\n==> G3-CACHE"
-declare _script_release_of="release_of"
 declare _cache="${_build_context}/.g3-cache"
 declare _shared_cache_path="${SHARED_G3_CACHE_PATH}"

@@ -31,7 +31,7 @@ declare _blend="${DOCKER_TAG:-$2}"
 declare _owner="${REPO_OWNER_NAME:?Need repo owner name}"

 ### utility scripts
-declare _script_release_of="release_of"
+# declare _script_release_of="release_of"   # currently unused

 ### using this repository name will prohibit the publishing
 declare _prohibited_repo_name="void"
@@ -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

@@ -104,7 +110,7 @@ case "${_branch}" in
        BASEIMAGE="${BASEIMAGE:-debian}"

        ### hardcoded settings
-        TIGERVNC_VERSION="1.13.0"
+        TIGERVNC_VERSION="1.13.1"
        TIGERVNC_DISTRO="x86_64"
        NOVNC_VERSION="1.4.0"
        WEBSOCKIFY_VERSION="0.11.0"
@@ -1,4 +1,4 @@
-#!/bin/bash -e
+#!/bin/bash

 ### 2022-09-11 Warning
 ### It seems like the README publishing is currently not always working. 
@@ -1,4 +1,4 @@
-#!/bin/bash -e
+#!/bin/bash

 echo -e "\n==> EXECUTING @$(date -u +'%Y-%m-%d_%H-%M-%S'): ${0} $@\n"

@@ -61,11 +61,11 @@ main() {
    ### no quotes around 'params'
    docker build ${params} \
        -f "${DOCKERFILE_PATH}" \
-            --build-arg BUILDKIT_INLINE_CACHE=1 \
            --build-arg BASEIMAGE="${BASEIMAGE}" \
            --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} \
            \
@@ -1,4 +1,5 @@
-#!/bin/bash -e
+#!/bin/bash
+
 ### @accetto, August 2021

 echo -e "\n==> EXECUTING @$(date -u +'%Y-%m-%d_%H-%M-%S'): ${0} $@\n"
@@ -1,4 +1,4 @@
-#!/bin/bash -e
+#!/bin/bash

 main() {
    local result=""
@@ -18,7 +18,7 @@ main() {

        echo "${result}"
    else
-        echo "Exiting '${0}' with code '1' because not able to get version of '$1'"
+        echo "Exiting '${0}' with code '1' because unable to get version of '$1'"
        return 1
    fi
 }
@@ -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

@@ -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
 }
@@ -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
@@ -90,9 +90,9 @@ The fastest way to build the images:
 ./ci-builder.sh all family latest-chromium
 ```

-You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the files `local-builder-readme.md`, `local-building-example.md` and the [sibling Wiki][sibling-wiki] for more information.
+You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information.

-Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See [readme-local-building-example.md][this-readme-local-building-example] for more information.
+Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See the [local-building-example][this-readme-local-building-example] for more information.

 #### Sharing devices

@@ -181,6 +181,7 @@ More information about these images can be found in the [full-length README][thi
 [this-readme-full]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/docker/xfce-chromium/README.md
 [this-readme-project]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/README.md

+[this-builder-readme]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-builder.md
 [this-readme-local-building-example]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-local-building-example.md

 <!-- Docker image specific -->
@@ -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)
@@ -47,7 +48,7 @@

 This repository contains resources for building Docker images based on [Debian 11][docker-debian] with [Xfce][xfce] desktop environment and [VNC][tigervnc]/[noVNC][novnc] servers for headless use and the current [Chromium][chromium] web browser.

-There is also a sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] containing similar images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu].
+There is also the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] containing similar images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu].

 ### TL;DR

@@ -102,9 +103,9 @@ The fastest way to build the images:
 ./ci-builder.sh all group latest-chromium
 ```

-You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the files `local-builder-readme.md`, `local-building-example.md` and the [sibling Wiki][sibling-wiki] for more information.
+You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information.

-Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See [readme-local-building-example.md][this-readme-local-building-example] for more information.
+Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See the [local-building-example][this-readme-local-building-example] for more information.

 #### Sharing devices

@@ -193,7 +194,7 @@ Both **named volumes** and **bind mounts** can be used. More about volumes can b

 ### Version sticker

-Version sticker serves multiple purposes that are closer described in the [sibling Wiki][sibling-wiki]. Note that the usage of the version sticker has changed between the generations of images.
+Version sticker serves multiple purposes that are closer described in the [sibling Wiki][sibling-wiki-version-stickers]. Note that the usage of the version sticker has changed between the generations of images.

 The **short version sticker value** describes the version of the image and it is persisted in its **label** during the build-time. It is also shown as its **badge** in the README file.

@@ -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

@@ -612,6 +626,7 @@ The stage diagram doesn't differ from the [sibling project][accetto-github-ubunt
 [this-readme-dockerhub]: https://hub.docker.com/r/accetto/debian-vnc-xfce-chromium-g3
 [this-readme-project]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/README.md

+[this-builder-readme]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-builder.md
 [this-readme-local-building-example]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-local-building-example.md

 <!-- Docker image specific -->
@@ -630,6 +645,8 @@ The stage diagram doesn't differ from the [sibling project][accetto-github-ubunt

 [sibling-diagram-dockerfile-stages]: https://raw.githubusercontent.com/accetto/ubuntu-vnc-xfce-g3/master/docker/doc/images/Dockerfile.xfce.png

+[sibling-wiki-version-stickers]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki/Concepts-of-dockerfiles
+
 <!-- Previous generations -->

 [accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/
@@ -93,9 +93,9 @@ The fastest way to build the images:
 ./ci-builder.sh all group latest-firefox
 ```

-You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the files `local-builder-readme.md`, `local-building-example.md` and the [sibling Wiki][sibling-wiki] for more information.
+You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information.

-Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC` or `Firefox Plus features`. See [readme-local-building-example.md][this-readme-local-building-example] for more information.
+Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC` or `Firefox Plus features`. See the [local-building-example][this-readme-local-building-example] for more information.

 #### Sharing devices

@@ -142,7 +142,7 @@ The main features and components of the images in the default configuration are:
 - current version of [tini][tini] as the entry-point initial process (PID 1)
 - support for overriding both the container user and the group
 - support of **version sticker** (see the [full-length README][this-readme-full] on the **GitHub**)
- current version of [Firefox][firefox] web browser and some additional **Firefox plus features** described in the [full-length README][this-readme-full] on the GitHub
+- current version of [Firefox ESR (Extended Support Release)][firefox] web browser and some additional **Firefox plus features** described in the [full-length README][this-readme-full] on the GitHub

 The history of notable changes is documented in the [CHANGELOG][this-changelog].

@@ -173,6 +173,7 @@ More information about these images can be found in the [full-length README][thi
 [this-readme-full]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/docker/xfce-firefox/README.md
 [this-readme-project]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/README.md

+[this-builder-readme]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-builder.md
 [this-readme-local-building-example]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-local-building-example.md

 <!-- Docker image specific -->
@@ -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)
@@ -56,7 +57,7 @@ There is no single-process Firefox image in this repository any more and the **m

 This repository contains resources for building Docker images based on [Debian 11][docker-debian] with [Xfce][xfce] desktop environment and [VNC][tigervnc]/[noVNC][novnc] servers for headless use and the current [Firefox][firefox] web browser.

-There is also a sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] containing similar images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu].
+There is also the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] containing similar images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu].

 ### TL;DR

@@ -111,9 +112,9 @@ The fastest way to build the images:
 ./ci-builder.sh all group latest-firefox
 ```

-You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the files `local-builder-readme.md`, `local-building-example.md` and the [sibling Wiki][sibling-wiki] for more information.
+You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information.

-Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC` or `Firefox Plus features`. See [readme-local-building-example.md][this-readme-local-building-example] for more information.
+Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC` or `Firefox Plus features`. See the [local-building-example][this-readme-local-building-example] for more information.

 #### Sharing devices

@@ -160,7 +161,7 @@ The main features and components of the images in the default configuration are:
 - current version of [tini][tini] as the entry-point initial process (PID 1)
 - support for overriding both the container user and the group
 - support of **version sticker** (see below)
- current version of [Firefox][firefox] web browser and some additional **Firefox plus features** described below
+- current version of [Firefox ESR (Extended Support Release)][firefox] web browser and some additional **Firefox plus features** described below

 The history of notable changes is documented in the [CHANGELOG][this-changelog].

@@ -191,7 +192,7 @@ Both **named volumes** and **bind mounts** can be used. More about volumes can b

 ### Version sticker

-Version sticker serves multiple purposes that are closer described in the [sibling Wiki][sibling-wiki]. Note that the usage of the version sticker has changed between the generations of images.
+Version sticker serves multiple purposes that are closer described in the [sibling Wiki][sibling-wiki-version-stickers]. Note that the usage of the version sticker has changed between the generations of images.

 The **short version sticker value** describes the version of the image and it is persisted in its **label** during the build-time. It is also shown as its **badge** in the README file.

@@ -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

@@ -668,6 +682,7 @@ The stage diagram doesn't differ from the [sibling project][accetto-github-ubunt
 [this-readme-dockerhub]: https://hub.docker.com/r/accetto/debian-vnc-xfce-firefox-g3
 [this-readme-project]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/README.md

+[this-builder-readme]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-builder.md
 [this-readme-local-building-example]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-local-building-example.md

 <!-- Docker image specific -->
@@ -686,6 +701,8 @@ The stage diagram doesn't differ from the [sibling project][accetto-github-ubunt

 [sibling-diagram-dockerfile-stages]: https://raw.githubusercontent.com/accetto/ubuntu-vnc-xfce-g3/master/docker/doc/images/Dockerfile.xfce.png

+[sibling-wiki-version-stickers]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki/Concepts-of-dockerfiles
+
 <!-- Previous generations -->

 [accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/
@@ -8,3 +8,4 @@ Path=
 Terminal=true
 StartupNotify=true
 GenericName=Copy FF Preferences
+Exec=${HOME}/firefox.plus/copy_firefox_user_preferences.sh
@@ -87,9 +87,9 @@ The fastest way to build the images:
 ./ci-builder.sh all group latest
 ```

-You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the files `local-builder-readme.md`, `local-building-example.md` and the [sibling Wiki][sibling-wiki] for more information.
+You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information.

-Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See [readme-local-building-example.md][this-readme-local-building-example] for more information.
+Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See the [local-building-example][this-readme-local-building-example] for more information.

 #### Sharing devices

@@ -166,6 +166,7 @@ More information about these images can be found in the [full-length README][thi
 [this-readme-full]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/docker/xfce/README.md
 [this-readme-project]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/README.md

+[this-builder-readme]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-builder.md
 [this-readme-local-building-example]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-local-building-example.md

 <!-- Docker image specific -->
@@ -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)
@@ -47,7 +48,7 @@

 This repository contains resources for building Docker images based on [Debian 11][docker-debian] with [Xfce][xfce] desktop environment and [VNC][tigervnc]/[noVNC][novnc] servers for headless use.

-There is also a sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] containing similar images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu].
+There is also the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] containing similar images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu].

 ### TL;DR

@@ -102,9 +103,9 @@ The fastest way to build the images:
 ./ci-builder.sh all group latest
 ```

-You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the files `local-builder-readme.md`, `local-building-example.md` and the [sibling Wiki][sibling-wiki] for more information.
+You can still execute the individual hook scripts as before (see the folder `/docker/hooks/`). However, the provided utilities `builder.sh` and `ci-builder.sh` are more convenient. Before pushing the images to the **Docker Hub** you have to prepare and source the file `secrets.rc` (see `example-secrets.rc`). The script `builder.sh` builds the individual images. The script `ci-builder.sh` can build various groups of images or all of them at once. Check the [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information.

-Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See [readme-local-building-example.md][this-readme-local-building-example] for more information.
+Note that selected features that are enabled by default can be explicitly disabled via environment variables. This allows to build even smaller images by excluding, for example, `noVNC`. See the [local-building-example][this-readme-local-building-example] for more information.

 #### Sharing devices

@@ -181,7 +182,7 @@ Both **named volumes** and **bind mounts** can be used. More about volumes can b

 ### Version sticker

-Version sticker serves multiple purposes that are closer described in the [sibling Wiki][sibling-wiki]. Note that the usage of the version sticker has changed between the generations of images.
+Version sticker serves multiple purposes that are closer described in the [sibling Wiki][sibling-wiki-version-stickers]. Note that the usage of the version sticker has changed between the generations of images.

 The **short version sticker value** describes the version of the image and it is persisted in its **label** during the build-time. It is also shown as its **badge** in the README file.

@@ -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

@@ -600,6 +614,7 @@ The stage diagram doesn't differ from the [sibling project][accetto-github-ubunt
 [this-readme-dockerhub]: https://hub.docker.com/r/accetto/debian-vnc-xfce-g3
 [this-readme-project]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/README.md

+[this-builder-readme]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-builder.md
 [this-readme-local-building-example]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-local-building-example.md

 <!-- Docker image specific -->
@@ -617,6 +632,8 @@ The stage diagram doesn't differ from the [sibling project][accetto-github-ubunt

 [sibling-diagram-dockerfile-stages]: https://raw.githubusercontent.com/accetto/ubuntu-vnc-xfce-g3/master/docker/doc/images/Dockerfile.xfce.png

+[sibling-wiki-version-stickers]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki/Concepts-of-dockerfiles
+
 <!-- Previous generations -->

 [accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/
@@ -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
@@ -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"
@@ -14,12 +25,11 @@ FROM ${BASEIMAGE}:${BASETAG}
 USER 0

 ### update the apt cache and install your new packages
-### e.g. vim editor, gimp etc.
+### e.g. vim editor
 RUN \
    apt-get update \
    && apt-get install -y --no-install-recommends \
        vim \
-        # gimp \
    && apt-get -y autoremove \
    && rm -rf /var/lib/apt/lists/*

@@ -28,13 +38,13 @@ RUN \
 # COPY ./bashrc "${HOME}"/.bashrc
 # COPY ./firefox.plus/user.js "${HOME}"/firefox.plus/

-### sometimes you need to set the file permisions again
-### e.g. if a newly installed app added some files
-# RUN "${STARTUPDIR}"/set_user_permissions.sh "${HOME}"
+### 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
@@ -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
@@ -54,8 +54,9 @@ export DOCKER_BUILDKIT=1
 # ### used by the 'post_push' hook script, which normally removes the helper files
 # # export KEEP_HELPER_FILES=0
 ### explicitly disable features that are enabled by default
-# export FEATURES_NOVNC=0
-# export FEATURES_FIREFOX_PLUS=0
+# # export FEATURES_NOVNC=0
+# # export FEATURES_FIREFOX_PLUS=0
+# # export FEATURES_OVERRIDING_ENVV=0

 #endregion

@@ -86,9 +87,10 @@ export DOCKER_BUILDKIT=1
 # export FORCE_BUILDING=0
 # ### used by the 'post_push' hook script, which normally removes the helper files
 # export KEEP_HELPER_FILES=0
-### explicitly disable features that are enabled by default
-# export FEATURES_NOVNC=0
-# export FEATURES_FIREFOX_PLUS=0
+# ### explicitly disable features that are enabled by default
+# # export FEATURES_NOVNC=0
+# # export FEATURES_FIREFOX_PLUS=0
+# # export FEATURES_OVERRIDING_ENVV=0

 #endregion

@@ -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
@@ -2,7 +2,10 @@

 - [Utility `builder.sh`](#utility-buildersh)
  - [Introduction](#introduction)
-  - [Prerequisites](#prerequisites)
+  - [Preparation](#preparation)
+    - [Ensure file attributes after cloning](#ensure-file-attributes-after-cloning)
+    - [Set environment variables before building](#set-environment-variables-before-building)
+    - [Ensure `wget` utility](#ensure-wget-utility)
  - [Executing complete pipeline](#executing-complete-pipeline)
  - [Executing individual pipeline steps](#executing-individual-pipeline-steps)
    - [What about the 'cache' helper script](#what-about-the-cache-helper-script)
@@ -38,22 +41,85 @@ The script creates a complete execution log.

 The `<docker-cli-options>` are passed to the Docker CLI commands used internally depending on the usage mode (see below).

-## Prerequisites
+## Preparation

-Before building and publishing the images prepare and source a file containing the necessary environment variables. You can use the provided file `example-secrets.rc` as a template.
+### Ensure file attributes after cloning

-If you name your file `secrets.rc` and you store it into the folder `docker/hooks/`, then it will sourced automatically by the hook script `env.rc`.
+It may be necessary to repair the executable files attributes after cloning the repository (by `git clone`).

-Otherwise you can source it in the terminal manually, for example:
+You can do that by executing the following commands from the project's root directory:

 ```shell
-source secrets.rc
+find . -type f -name "*.sh" -exec chmod +x '{}' \;
+chmod +x docker/hooks/*
+```
+
+For example, if the files in the folder `docker/hooks` would not be executable, then you would get errors similar to this:
+
+```shell
+$ ./builder.sh latest build
+
+==> EXECUTING @2023-03-05_16-42-57: ./builder.sh 
+
+./builder.sh: line 84: ./docker/hooks/build: Permission denied
+```
+
+### Set environment variables before building
+
+Open a terminal windows and change the current directory to the root of the project (where the license file is).
+
+Make a copy of the secrets example file, modify it and then source it in the terminal:
+
+```shell
+### make a copy and then modify it
+cp examples/example-secrets.rc secrets.rc
+
+### source the secrets
+source ./secrets.rc

 ### or also

-. secrets.rc
+. ./secrets.rc
 ```

+**TIP**: If you copy a file named `secrets.rc` into the folder `docker/hooks/`, then it will be automatically sourced by the hook script `env.rc`.
+
+Be aware that the following environment variables are mandatory and must be always set:
+
+- `REPO_OWNER_NAME`
+- `BUILDER_REPO`
+
+Ensure that your `secrets.rc` file contains at least the lines similar to these:
+
+```shell
+export REPO_OWNER_NAME="accetto"
+export BUILDER_REPO="headless-debian-g3"
+```
+
+You can use your own names if you wish.
+
+Alternatively you can modify the hook script file env.rc like this:
+
+```shell
+### original lines
+declare _owner="${REPO_OWNER_NAME:?Need repo owner name}"
+DOCKER_REPO="${_owner}/${BUILDER_REPO:?Need builder repo name}"
+
+### modified lines
+declare _owner="${REPO_OWNER_NAME:-accetto}"
+DOCKER_REPO="${_owner}/${BUILDER_REPO:-headless-debian-g3}"
+```
+
+Again, you can use your own names if you wish.
+
+You can also use other ways to set the variables.
+
+### Ensure `wget` utility
+
+If you are on Windows, you can encounter the problem of missing `wget` utility. It is used by refreshing the `g3-cache` and it's available on Linux by default.
+
+On Windows you have generally two choices. You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. Make sure to update also the `PATH` environment variable appropriately.
+
 ## Executing complete pipeline

 Building the individual images and publishing them to the **Docker Hub**:
@@ -86,7 +152,7 @@ You can also provide additional parameters for the internally used Docker `build
 ### docker build --no-cache ...
 ```

-The optional `<docker-cli-options>` are passed only to the `pre_build` hook script, which passes them to the internally used `docker build` command.
+The optional `<docker-cli-options>` are passed only to the `pre_build` hook script, which passes them to the internally used `docker build` command. The `cache` hook script, however, doesn't use any Docker CLI commands.

 ## Executing individual pipeline steps

@@ -2,7 +2,10 @@

 - [Utility `ci-builder.sh`](#utility-ci-buildersh)
  - [Introduction](#introduction)
-  - [Prerequisites](#prerequisites)
+  - [Preparation](#preparation)
+    - [Ensure file attributes after cloning](#ensure-file-attributes-after-cloning)
+    - [Set environment variables before building](#set-environment-variables-before-building)
+    - [Ensure `wget` utility](#ensure-wget-utility)
  - [Usage modes](#usage-modes)
    - [Group mode](#group-mode)
      - [Group mode examples](#group-mode-examples)
@@ -10,7 +13,7 @@
      - [Family mode examples](#family-mode-examples)
    - [Log processing](#log-processing)
      - [Digest command](#digest-command)
-      - [Stickers commands](#stickers-commands)
+      - [Stickers command](#stickers-command)
      - [Timing command](#timing-command)
      - [Errors command](#errors-command)
  - [Additional building parameters](#additional-building-parameters)
@@ -69,22 +72,85 @@ The optional parameter `--no-cache` will be passed to the internally used script

 The optional parameter `--log-all` will cause that the script's output will be written into the log file in all cases. Normally the command line errors or the **log processing mode** commands are not logged. 

-## Prerequisites
+## Preparation

-Before building and publishing the images prepare and source a file containing the necessary environment variables. You can use the provided file `example-secrets.rc` as a template.
+### Ensure file attributes after cloning

-If you name your file `secrets.rc` and you store it into the folder `docker/hooks/`, then it will sourced automatically by the hook script `env.rc`.
+It may be necessary to repair the executable files attributes after cloning the repository (by `git clone`).

-Otherwise you can source it in the terminal manually, for example:
+You can do that by executing the following commands from the project's root directory:

 ```shell
-source secrets.rc
+find . -type f -name "*.sh" -exec chmod +x '{}' \;
+chmod +x docker/hooks/*
+```
+
+For example, if the files in the folder `docker/hooks` would not be executable, then you would get errors similar to this:
+
+```shell
+$ ./builder.sh latest build
+
+==> EXECUTING @2023-03-05_16-42-57: ./builder.sh 
+
+./builder.sh: line 84: ./docker/hooks/build: Permission denied
+```
+
+### Set environment variables before building
+
+Open a terminal windows and change the current directory to the root of the project (where the license file is).
+
+Make a copy of the secrets example file, modify it and then source it in the terminal:
+
+```shell
+### make a copy and then modify it
+cp examples/example-secrets.rc secrets.rc
+
+### source the secrets
+source ./secrets.rc

 ### or also

-. secrets.rc
+. ./secrets.rc
 ```

+**TIP**: If you copy a file named `secrets.rc` into the folder `docker/hooks/`, then it will be automatically sourced by the hook script `env.rc`.
+
+Be aware that the following environment variables are mandatory and must be always set:
+
+- `REPO_OWNER_NAME`
+- `BUILDER_REPO`
+
+Ensure that your `secrets.rc` file contains at least the lines similar to these:
+
+```shell
+export REPO_OWNER_NAME="accetto"
+export BUILDER_REPO="headless-debian-g3"
+```
+
+You can use your own names if you wish.
+
+Alternatively you can modify the hook script file env.rc like this:
+
+```shell
+### original lines
+declare _owner="${REPO_OWNER_NAME:?Need repo owner name}"
+DOCKER_REPO="${_owner}/${BUILDER_REPO:?Need builder repo name}"
+
+### modified lines
+declare _owner="${REPO_OWNER_NAME:-accetto}"
+DOCKER_REPO="${_owner}/${BUILDER_REPO:-headless-debian-g3}"
+```
+
+Again, you can use your own names if you wish.
+
+You can also use other ways to set the variables.
+
+### Ensure `wget` utility
+
+If you are on Windows, you can encounter the problem of missing `wget` utility. It is used by refreshing the `g3-cache` and it's available on Linux by default.
+
+On Windows you have generally two choices. You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. Make sure to update also the `PATH` environment variable appropriately.
+
 ## Usage modes

 ### Group mode
@@ -131,11 +197,13 @@ The dependency in this context is meant more technically than conceptually.

 The following example will help to understand the concept.

-The image `accetto/ubuntu-vnc-xfce-g3:latest-fugo` added some additional features to the image `accetto/ubuntu-vnc-xfce-g3:latest`, but otherwise were both images identical.
+This project currently does not include any images that are in such a relation. Therefore it will be explained using the images from the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3].

-In such case a conclusion can be made, that if the `latest` tag does not need a refresh, then also the `latest-fugo` tag doesn't need it and it can be skipped.
+The image `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` added some additional features to the image `accetto/ubuntu-vnc-xfce-firefox-g3:latest`, but otherwise were both images identical.

-There had been a similar dependency between the images `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` and `accetto/ubuntu-vnc-xfce-firefox-g3:latest`.
+In such case a conclusion can be made, that if the `latest` tag does not need a refresh, then also the `latest-plus` tag doesn't need it and its building can be skipped.
+
+There had been a similar dependency between the images `accetto/ubuntu-vnc-xfce-g3:latest` and `accetto/ubuntu-vnc-xfce-g3:latest-fugo`.

 This kind of family-like relation allows to refresh the images more efficiently by skipping the "children" if the "parent" doesn't need a re-build.

@@ -203,7 +271,7 @@ Built new 'headless-debian-g3:latest-chromium'.
 Built new 'headless-debian-g3:latest-firefox'.
 ```

-#### Stickers commands
+#### Stickers command

 The `stickers` command extracts the information about the **version stickers** of the ephemeral helper images that have been built by the `pre_build` hook script. That does not mean that the final persistent images have also been built (and optionally also published).

@@ -2,6 +2,7 @@

 - [Custom `g3-cache`](#custom-g3-cache)
  - [Introduction](#introduction)
+    - [Ensure `wget` utility](#ensure-wget-utility)
  - [Local `g3-cache`](#local-g3-cache)
  - [Shared g3-cache](#shared-g3-cache)
  - [Helper script `cache`](#helper-script-cache)
@@ -12,12 +13,18 @@ The custom `g3-cache` has been introduced in the **second version** (G3v2) of th

 The local `g3-cache` is an additional cache used by the building pipeline and it should not be confused with the **Docker builder cache** maintained by the [Docker Build][docker-doc-docker-build] itself.

-The `g3-cache`stores the selected pre-downloaded packages used by the Dockerfiles, that would be otherwise repeatedly downloaded from the external sources by each build.
+The `g3-cache` stores the selected pre-downloaded packages used by the Dockerfiles, that would be otherwise repeatedly downloaded from the external sources by each build.

 It results in a significantly higher performance by building sets of images or by repeated builds.

 You can learn more about the concept on the sibling Wiki page ["Concepts of `g3-cache`"][sibling-wiki-concepts-of-g3-cache] and about the implementation on the sibling Wiki page ["How `g3-cache` works"][sibling-wiki-how-g3-cache-works].

+### Ensure `wget` utility
+
+If you are on Windows, you can encounter the problem of missing `wget` utility. It is used by refreshing the `g3-cache` and it's available on Linux by default.
+
+On Windows you have generally two choices. You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. Make sure to update also the `PATH` environment variable appropriately.
+
 ## Local `g3-cache`

 The local `g3-cache` of this project has the following **cache sections**:
@@ -3,6 +3,9 @@
 - [Local building example](#local-building-example)
  - [Introduction](#introduction)
  - [Preparation](#preparation)
+    - [Ensure file attributes after cloning](#ensure-file-attributes-after-cloning)
+    - [Set environment variables before building](#set-environment-variables-before-building)
+    - [Ensure `wget` utility](#ensure-wget-utility)
  - [Building pipeline](#building-pipeline)
  - [Three ways of building images](#three-ways-of-building-images)
    - [Building and publishing sets of images](#building-and-publishing-sets-of-images)
@@ -25,15 +28,38 @@ The **Docker Hub** has removed the **auto-building feature** from the free plan

 This page describes how to build the images locally and optionally also push them to the **Docker Hub**.

-The **second version** (G3v2) of the building pipeline in the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] made it really easy, even if you want to build a set of images or all of them at once.
+The **second version** (G3v2) of the building pipeline introduced in the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] made it really easy, even if you want to build a set of images or all of them at once.

 ## Preparation

+### Ensure file attributes after cloning
+
+It may be necessary to repair the executable files attributes after cloning the repository (by `git clone`).
+
+You can do that by executing the following commands from the project's root directory:
+
+```shell
+find . -type f -name "*.sh" -exec chmod +x '{}' \;
+chmod +x docker/hooks/*
+```
+
+For example, if the files in the folder `docker/hooks` would not be executable, then you would get errors similar to this:
+
+```shell
+$ ./builder.sh latest build
+
+==> EXECUTING @2023-03-05_16-42-57: ./builder.sh 
+
+./builder.sh: line 84: ./docker/hooks/build: Permission denied
+```
+
+### Set environment variables before building
+
 Open a terminal windows and change the current directory to the root of the project (where the license file is).

 Make a copy of the secrets example file, modify it and then source it in the terminal:

-```bash
+```shell
 ### make a copy and then modify it
 cp examples/example-secrets.rc secrets.rc

@@ -47,6 +73,42 @@ source ./secrets.rc

 **TIP**: If you copy a file named `secrets.rc` into the folder `docker/hooks/`, then it will be automatically sourced by the hook script `env.rc`.

+Be aware that the following environment variables are mandatory and must be always set:
+
+- `REPO_OWNER_NAME`
+- `BUILDER_REPO`
+
+Ensure that your `secrets.rc` file contains at least the lines similar to these:
+
+```shell
+export REPO_OWNER_NAME="accetto"
+export BUILDER_REPO="headless-debian-g3"
+```
+
+You can use your own names if you wish.
+
+Alternatively you can modify the hook script file env.rc like this:
+
+```shell
+### original lines
+declare _owner="${REPO_OWNER_NAME:?Need repo owner name}"
+DOCKER_REPO="${_owner}/${BUILDER_REPO:?Need builder repo name}"
+
+### modified lines
+declare _owner="${REPO_OWNER_NAME:-accetto}"
+DOCKER_REPO="${_owner}/${BUILDER_REPO:-headless-debian-g3}"
+```
+
+Again, you can use your own names if you wish.
+
+You can also use other ways to set the variables.
+
+### Ensure `wget` utility
+
+If you are on Windows, you can encounter the problem of missing `wget` utility. It is used by refreshing the `g3-cache` and it's available on Linux by default.
+
+On Windows you have generally two choices. You can build your images inside the `WSL` environment or you can download the `wget.exe` application for Windows. Make sure to update also the `PATH` environment variable appropriately.
+
 ## Building pipeline

 The actual building pipeline consists of the following hook scripts stored in the folder `docker/hooks`:
@@ -58,7 +120,7 @@ The actual building pipeline consists of the following hook scripts stored in th

 The hook scripts are executed exactly in that order.

-The **second version** (G3v2) of the pipeline in the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] has added also the helper script `cache`, which ist stored in the same folder. It is used by the hook scripts `pre_build` and `build` and it refreshes the local `g3-cache`. It can be also executed  stand-alone.
+The **second version** (G3v2) of the pipeline introduced in the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] has added also the helper script `cache`, which ist stored in the same folder. It is used by the hook scripts `pre_build` and `build` and it refreshes the local `g3-cache`. It can be also executed  stand-alone.

 Utilizing the local `g3-cache` brings a significant boost in the building performance and much shorter building times.

@@ -66,7 +128,7 @@ There is also the helper script `util-readme.sh`, stored in the folder `utils/`.

 ## Three ways of building images

-Since the **second version** (G3v2) of the building pipeline in the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] there are the following ways of building the images:
+Since the **second version** (G3v2) of the building pipeline introduced in the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] there are the following ways of building the images:

 - Building sets of images by executing the helper script `ci-builder.sh`
 - Building the individual images by executing the helper script `builder.sh`
@@ -204,7 +266,7 @@ Both scripts insert the additional parameters just after the `docker build` part
 For example, if the additional parameters `--target stage_xfce --no-cache` are provided to the script `docker/hooks/build`, then the result Docker command line will begin like this:

 ```shell
-docker build --target stage_xfce --no-cache -f ./docker/Dockerfile.xfce.22-04 ...
+docker build --target stage_xfce --no-cache -f ./docker/Dockerfile.xfce ...
 ```

 However, there is a special handling of the parameter `--target`.
@@ -248,7 +310,7 @@ It allows to build even smaller images by excluding `noVNC` or `Firefox Plus fea
 If the environment variable `FEATURES_NOVNC` is explicitly set to zero (by `export FEATURES_NOVNC="0"`), then

 - image will not include `noVNC`
- image tag will get the `-vnc` suffix (e.g. `latest-vnc`, `20.04-firefox-vnc` etc.)
+- image tag will get the `-vnc` suffix (e.g. `latest-vnc`, `latest-firefox-vnc` etc.)

 ### Disabling `Firefox Plus`
Author	SHA1	Message	Date
accetto	31cf33a0d2	Release 23.07	2023-07-21 13:40:25 +02:00
accetto	2db4715a6c	cache hook script improved	2023-06-27 10:24:02 +02:00
accetto	a913a81d56	utilizing 'envsubst'	2023-04-23 20:15:04 +02:00
accetto	7e7f4e90b0	added HINTS comment to Dockerfile.extend example	2023-04-16 12:18:59 +02:00
accetto	1ee0df9e7f	Release 23.03.2	2023-03-24 14:27:03 +01:00
accetto	3068f748b0	readme files updated	2023-03-24 14:25:24 +01:00
accetto	724108bbbd	user generator script improved	2023-03-24 14:20:53 +01:00
accetto	6b82b06f62	'initial_sudo_password' moved from HOME to STARTUPDIR	2023-03-24 14:18:32 +01:00
accetto	7d1417aed5	Release 23.03.1	2023-03-12 18:39:11 +01:00
accetto	b0d7a185c6	Release 23.03	2023-03-06 19:23:09 +01:00
accetto	2c42363e7e	readme files updated	2023-03-06 18:29:12 +01:00
accetto	63f22ae69b	updated with TigerVNC 1.13.1 bugfix release	2023-03-06 18:12:39 +01:00
accetto	52ed4490ff	link explaining version stickers updated	2023-02-26 11:39:40 +01:00
accetto	9254d67843	minor fixes in readme files	2023-02-25 19:13:48 +01:00
accetto	182d071e2c	fix in Firefox readme files	2023-02-25 09:32:02 +01:00