Merge branch 'master' of https://gitea.akanealw.com/akanealw/debian-vnc-xfce-g3

.gitignore

@@ -23,6 +23,6 @@
 avanti*
 debug*
 scrap*
-secret*
+#secret*
 TODO*
 *.log

CHANGELOG.md

@@ -2,10 +2,97 @@
 
 ## Project `accetto/debian-vnc-xfce-g3`
 
-[Docker Hub][this-docker] - [Git Hub][this-github] - [sibling Wiki][sibling-wiki] - [sibling Discussions][sibling-discussions]
+[User Guide][this-user-guide] - [Docker Hub][this-docker] - [Git Hub][this-github] - [sibling Wiki][sibling-wiki] - [sibling Discussions][sibling-discussions]
 
 ***
 
+### Release 23.12
+
+This is a maintenance release.
+
+- Updated Dockerfiles
+  - file `.bashrc` is created earlier (stage `merge_stage_vnc`)
+- Updated file `example-secrets.rc`
+  - removed the initialization of the variables `FORCE_BUILDING` and `FORCE_PUBLISHING_BUILDER_REPO` (unset means `0`)
+  - the variables are still used as before, but now they can be set individually for each building/publishing run
+
+### Release 23.11
+
+- Added file `$HOME/.bashrc` to all images.
+It contains examples of custom aliases
+  - `ll` - just `ls -l`
+  - `cls` - clears the terminal window
+  - `ps1` - sets the command prompt text
+
+- Added more 'die-fast' error handling into the building and publishing scripts.
+They exit immediately if the image building or pushing commands fail.
+
+### Release 23.08.1 (Milestone)
+
+This release brings new images based on the current **Debian 12**.
+The images based on the previous **Debian 11** will still be published into the same repositories.
+
+Other changes:
+
+- hook scripts `env.rc`, `push` and `post_push` have been updated
+- handling of multiple deployment tags per image has been improved and it covers also publishing into the builder repository now
+  - also less image pollution by publishing
+- file `readme-local-building-example.md` got a new section `Tips and examples`, containing
+  - `How to deploy all images into one repository`
+
+Main updated components:
+
+- `Debian` to version **12.1**
+- `Xfce` desktop to version **4.18**
+- `Mousepad` to version **0.5.10**
+- `nano` to version **7.2**
+- `Python` to version **3.11.2**
+
+### Release 23.08
+
+This release brings updated and significantly shortened README files, because most of the content has been moved into the new [User guide][this-user-guide].
+
+### Release 23.07.1
+
+This release brings some enhancements in the Dockerfile and the script `user_generator.rc` with the aim to better support extending the images.
+
+### 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
@@ -17,13 +104,14 @@ The initial version of the project has been derived from the sibling project [ac
 
 ***
 
+[this-user-guide]: https://accetto.github.io/user-guide-g3/
+
 [this-docker]: https://hub.docker.com/u/accetto/
 
 [this-github]: https://github.com/accetto/debian-vnc-xfce-g3/
 
 [accetto-github-ubuntu-vnc-xfce-g3]: https://github.com/accetto/ubuntu-vnc-xfce-g3
 
-<!-- Sibling projects -->
-
 [sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki
+
 [sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions

README.md

@@ -6,7 +6,7 @@ Version: G3v1
 
 ***
 
-[Docker Hub][this-docker] - [Changelog][this-changelog] - [sibling Wiki][sibling-wiki] - [sibling Discussions][sibling-discussions]
+[User Guide][this-user-guide] - [Docker Hub][this-docker] - [Changelog][this-changelog] - [sibling Wiki][sibling-wiki] - [sibling Discussions][sibling-discussions]
 
 ![badge-github-release][badge-github-release]
 ![badge-github-release-date][badge-github-release-date]
@@ -18,156 +18,76 @@ Version: G3v1
 ![badge-github-commits][badge-github-commits]
 ![badge-github-last-commit][badge-github-last-commit]
 
-<!-- ![badge-github-workflow-dockerhub-autobuild][badge-github-workflow-dockerhub-autobuild] -->
-<!-- ![badge-github-workflow-dockerhub-post-push][badge-github-workflow-dockerhub-post-push] -->
-
 ***
 
 - [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)
+    - [Building images](#building-images)
     - [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)
+    - [Getting help](#getting-help)
+    - [Credits](#credits)
 
 ### 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.
+This GitHub repository contains resources and tools for building Docker images for headless working.
 
-The resources for the individual images and their variations (tags) are stored in the subfolders of the **master** branch. Each image has its own README file describing its features and usage.
+The images are based on the current [Debian 12][docker-debian] and the previous [Debian 11][docker-debian] and include [Xfce][xfce] desktop, [TigerVNC][tigervnc] server and [noVNC][novnc] client.
+The popular web browsers [Chromium][chromium] and [Firefox][firefox] are also included.
 
-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].
+This [User guide][this-user-guide] describes the images and how to use them.
 
-### TL;DR
+The content of this GitHub project is intended for developers and image builders.
 
-There are currently resources for the following Docker images:
+Ordinary users can simply use the images available in the following repositories on Docker Hub:
 
 - [accetto/debian-vnc-xfce-g3][accetto-docker-debian-vnc-xfce-g3]
-  - [full Readme][this-readme-image-base]
-  - [Dockerfile][this-dockerfile] (common for all images)
-  - [sibling Dockerfile stages diagram][sibling-diagram-dockerfile-stages] (common for all images)
 - [accetto/debian-vnc-xfce-chromium-g3][accetto-docker-debian-vnc-xfce-chromium-g3]
-  - [full Readme][this-readme-image-chromium]
 - [accetto/debian-vnc-xfce-firefox-g3][accetto-docker-debian-vnc-xfce-firefox-g3]
-  - [full Readme][this-readme-image-firefox]
 
-#### Installing packages
+This project 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].
 
-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.
+### Building images
 
-You can also try to fix it by executing the following (the default `sudo` password is **headless**):
+You can execute the individual hook scripts in the folder [/docker/hooks/][this-folder-docker-hooks].
+However, the provided utilities are more convenient.
 
-```shell
-### apt cache needs to be updated only once
-sudo apt-get update
+The script [builder.sh][this-readme-builder] builds individual images.
+The script [ci-builder.sh][this-readme-ci-builder] can build various groups of images or all of them at once.
 
-sudo apt --fix-broken install
-```
+Before building the images you have to prepare and source the file `secrets.rc` (see [example-secrets.rc][this-example-secrets-file]).
 
-#### Shared memory size
+Features that are enabled by default can be explicitly disabled via environment variables.
+This allows building even smaller images by excluding the individual features (e.g. noVNC).
 
-Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior.
+The resources for building the individual images and their variations (tags) are in the subfolders of the [/docker/][this-folder-docker] folder.
 
-You can check the current shared memory size by executing the following command inside the container:
+The individual README files contain quick examples of building the images:
 
-```shell
-df -h /dev/shm
-```
+- [accetto/debian-vnc-xfce-g3][this-readme-debian-vnc-xfce-g3]
+- [accetto/debian-vnc-xfce-chromium-g3][this-readme-debian-vnc-xfce-chromium-g3]
+- [accetto/debian-vnc-xfce-firefox-g3][this-readme-debian-vnc-xfce-firefox-g3]
 
-The older sibling Wiki page [Firefox multi-process][that-wiki-firefox-multiprocess] describes several ways, how to increase the shared memory size.
+Each image also has a separate README file intended for Docker Hub.
+The final files should be generated by the utility [util-readme.sh][this-readme-util-readme-examples] and then copied to Docker Hub manually.
 
-#### Extending images
+The following resources describe the image building subject in details:
 
-The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images.
-
-Your concrete `Dockerfile` may need more statements, but the concept should be clear.
-
-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
-
-The fastest way to build the images:
-
-```shell
-### PWD = project root
-### prepare and source the 'secrets.rc' file first (see 'example-secrets.rc')
-
-### examples of building and publishing the individual images
-./builder.sh latest all
-./builder.sh latest-chromium all
-./builder.sh latest-firefox all
-
-### just building the images, skipping the publishing and the version sticker update
-./builder.sh latest build
-./builder.sh latest-chromium build
-./builder.sh latest-firefox build
-
-### examples of building and publishing the groups of images
-./ci-builder.sh all group latest
-./ci-builder.sh all group latest-chromium
-./ci-builder.sh all group latest-firefox
-
-### or all the images at once
-./ci-builder.sh all group complete
-
-### or skipping the publishing to the Docker Hub
-./ci-builder.sh all-no-push group complete
-
-### 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 [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 the audio device for video with sound works only with `Chromium` and only on Linux:
-
-```shell
-docker run -it -P --rm \
-  --device /dev/snd:/dev/snd:rw \
-  --group-add audio \
-accetto/debian-vnc-xfce-chromium-g3:latest
-```
-
-Sharing the display with the host works only on Linux:
-
-```shell
-xhost +local:$(whoami)
-
-docker run -it -P --rm \
-    -e DISPLAY=${DISPLAY} \
-    --device /dev/dri/card0 \
-    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
-    accetto/debian-vnc-xfce-g3:latest --skip-vnc
-
-xhost -local:$(whoami)
-```
-
-Sharing the X11 socket with the host works only on Linux:
-
-```shell
-xhost +local:$(whoami)
-
-docker run -it -P --rm \
-    --device /dev/dri/card0 \
-    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
-    accetto/debian-vnc-xfce-g3:latest
-
-xhost -local:$(whoami)
-```
+- [readme-local-building-example.md][this-readme-local-building-example]
+- [readme-builder.md][this-readme-builder]
+- [readme-ci-builder.md][this-readme-ci-builder]
+- [readme-g3-cache.md][this-readme-g3-cache]
+- [readme-util-readme-examples.md][this-readme-util-readme-examples]
+- [sibling Wiki][sibling-wiki]
 
 ### 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].
+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
 
@@ -183,72 +103,83 @@ Please refer to the [sibling project][accetto-github-ubuntu-vnc-xfce-g3_project-
 
 Please refer to the [sibling project][accetto-github-ubuntu-vnc-xfce-g3_project-features] to learn more about the project features.
 
-***
+### Getting help
 
-## Issues, Wiki and Discussions
+If you have found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and the [sibling Wiki][sibling-wiki] first.
+Please do not overlook the closed issues.
 
-If you have found a problem or you just have a question, please check the [Issues][this-issues] and the [sibling Wiki][sibling-wiki] first. Please do not overlook the closed issues.
-
-If you do not find a solution, you can file a new issue. The better you describe the problem, the bigger the chance it'll be solved soon.
+If you do not find a solution, you can file a new issue.
+The better you describe the problem, the bigger the chance it'll be solved soon.
 
 If you have a question or an idea and you don't want to open an issue, you can use the [sibling Discussions][sibling-discussions].
 
-## Credits
+### Credits
 
 Credit goes to all the countless people and companies, who contribute to open source community and make so many dreamy things real.
 
 ***
 
+[this-user-guide]: https://accetto.github.io/user-guide-g3/
+
 [this-docker]: https://hub.docker.com/u/accetto/
 
 [this-changelog]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/CHANGELOG.md
-<!-- [this-github]: https://github.com/accetto/debian-vnc-xfce-g3/ -->
+
 [this-issues]: https://github.com/accetto/debian-vnc-xfce-g3/issues
 
-[this-dockerfile]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/docker/Dockerfile.xfce
+[this-folder-docker]: https://github.com/accetto/debian-vnc-xfce-g3/tree/master/docker
 
-[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-folder-docker-hooks]: https://github.com/accetto/debian-vnc-xfce-g3/tree/master/docker/hooks
+
+[this-example-secrets-file]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/examples/example-secrets.rc
+
+[this-readme-debian-vnc-xfce-g3]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/docker/xfce/README.md
+
+[this-readme-debian-vnc-xfce-chromium-g3]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/docker/xfce-chromium/README.md
+
+[this-readme-debian-vnc-xfce-firefox-g3]: 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
 
+[this-readme-builder]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-builder.md
+
+[this-readme-ci-builder]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-ci-builder.md
+
+[this-readme-g3-cache]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/readme-g3-cache.md
+
+[this-readme-util-readme-examples]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/utils/readme-util-readme-examples.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
 
-<!-- sibling projects -->
-
 [accetto-github-ubuntu-vnc-xfce-g3]: https://github.com/accetto/ubuntu-vnc-xfce-g3
+
 [sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki
+
 [sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions
 
 [accetto-github-ubuntu-vnc-xfce-g3_project-versions]: https://github.com/accetto/ubuntu-vnc-xfce-g3#project-versions
+
 [accetto-github-ubuntu-vnc-xfce-g3_project-goals]: https://github.com/accetto/ubuntu-vnc-xfce-g3#project-goals
+
 [accetto-github-ubuntu-vnc-xfce-g3_project-features]: https://github.com/accetto/ubuntu-vnc-xfce-g3#changes-and-new-features
 
-[sibling-diagram-dockerfile-stages]: https://raw.githubusercontent.com/accetto/ubuntu-vnc-xfce-g3/master/docker/doc/images/Dockerfile.xfce.png
-
-<!-- previous generations -->
-
-[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess
 [accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/
-[accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce
 
-<!-- external links -->
+[accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce
 
 [docker-debian]: https://hub.docker.com/_/debian/
 [docker-ubuntu]: https://hub.docker.com/_/ubuntu/
 
-[debian-packages-search]: https://packages.debian.org/index
-
+[chromium]: https://www.chromium.org/Home
+[firefox]: https://www.mozilla.org
 [novnc]: https://github.com/kanaka/noVNC
 [tigervnc]: http://tigervnc.org
 [xfce]: http://www.xfce.org
 
-<!-- github badges -->
-
 [badge-github-release]: https://badgen.net/github/release/accetto/debian-vnc-xfce-g3?icon=github&label=release
 
 [badge-github-release-date]: https://img.shields.io/github/release-date/accetto/debian-vnc-xfce-g3?logo=github

build-base-and-push-to-gitea.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+./builder.sh latest pre_build
+./builder.sh latest build
+docker push repo.aknlw.com/akanealw/debian-vnc-xfce:latest

build-chromium-and-push-to-gitea.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+./builder.sh latest-chromium pre_build
+./builder.sh latest-chromium build
+docker push repo.aknlw.com/akanealw/debian-vnc-xfce:latest-chromium

build-firefox-and-push-to-gitea.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+./builder.sh latest-firefox pre_build
+./builder.sh latest-firefox build
+docker push repo.aknlw.com/akanealw/debian-vnc-xfce:latest-firefox-default

builder.sh

@@ -1,6 +1,6 @@
 #!/bin/bash -e
 ### @accetto, August 2021
-### updated: September 2022, January 2023
+### updated: August 2023
 
 ### depends on the hook scripts
 ### set the environment variables first, e.g. 'source .secrets'
@@ -12,7 +12,7 @@ die() {
     local -i code=${2:-1}
     local place="${3:-$0}"
 
-    echo -e "EXITING '${place}' with code ${code}: ${message}" >&2
+    echo -e "EXITING at line "${BASH_LINENO[0]}" in '${place}' with code ${code}: ${message}" >&2
     exit ${code}
 }
 
@@ -44,7 +44,7 @@ This script can:
 
 Usage: $0 <blend> <command> [<docker-cli-options>]
 
-blend   := (latest[-chromium|-firefox])
+blend   := (latest|bookworm|bullseye)[-chromium|-firefox])
 command := (all|all-no-push)|(pre_build|build|push|post_push|cache)
 
 The <docker-cli-options> (e.g. '--no-cache') are passed to the Docker CLI commands used internally.

ci-builder.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 ### do not use '-e'
 ### @accetto, September 2022
-### updated: January 2023
+### updated: August 2023
 
 ### depends on the script 'builder.sh'
 ### set the environment variables first, e.g. 'source .secrets'
@@ -13,7 +13,7 @@ die() {
     local -i code=${2:-1}
     local place="${3:-$0}"
 
-    echo -e "\nEXITING '${place}' with code ${code}: ${message}\n" >&2
+    echo -e "\nEXITING at line "${BASH_LINENO[0]}" in '${place}' with code ${code}: ${message}\n" >&2
     exit ${code}
 }
 
@@ -101,9 +101,9 @@ Usage: <script> <mode> <argument> [<optional-argument>]...
 <command>      := (all|all-no-push)
 <mode>         := (group|family)
 <blend>        := pivotal
-                  |(complete[-latest|-chromium|-firefox])
-                  |(latest[-chromium|-firefox])
-<parent-blend> := (complete)|(latest[-chromium|-firefox])
+                  |(complete[-latest|-bookworm|-bullseye|-chromium|-firefox])
+                  |(latest|bookworm|bullseye[-chromium|-firefox])
+<parent-blend> := (complete)|(latest|bookworm|bullseye[-chromium|-firefox])
 <child-suffix> := depends on context, e.g. '-ver1|-ver2' (currently none supported)
 
 Group mode : All images are processed independently.
@@ -253,6 +253,7 @@ main() {
         help | --help | -h )
         
             show_unlogged_help
+            return 0
             ;;
 
         log )
@@ -288,28 +289,48 @@ main() {
                         pivotal )
 
                             clear_log
-                            build_group "${command}" "latest" "latest-chromium" "latest-firefox"
+                            build_group "${command}" "latest" "bullseye" "latest-firefox" "bullseye-firefox" "latest-chromium" "bullseye-chromium"
                             ;;
 
-                        complete | complete-latest )
+                        complete )
 
                             clear_log
-                            build_group "${command}" "latest" "latest-chromium" "latest-firefox"
+                            build_group "${command}" "latest" "bullseye" "latest-firefox" "bullseye-firefox" "latest-chromium" "bullseye-chromium"
+                            ;;
+
+                        complete-latest )
+
+                            clear_log
+                            build_group "${command}" "latest" "latest-firefox" "latest-chromium"
+                            ;;
+
+                        complete-bookworm )
+
+                            clear_log
+                            build_group "${command}" "bookworm" "bookworm-firefox" "bookworm-chromium"
+                            ;;
+
+                        complete-bullseye )
+
+                            clear_log
+                            build_group "${command}" "bullseye" "bullseye-firefox" "bullseye-chromium"
                             ;;
 
                         complete-chromium )
 
                             clear_log
-                            build_group "${command}" "latest-chromium"
+                            build_group "${command}" "latest-chromium" "bullseye-chromium"
                             ;;
 
                         complete-firefox )
 
                             clear_log
-                            build_group "${command}" "latest-firefox"
+                            build_group "${command}" "latest-firefox" "bullseye-firefox"
                             ;;
 
-                        latest | latest-chromium | latest-firefox )
+                        latest | latest-chromium | latest-firefox \
+                        | bookworm | bookworm-chromium | bookworm-firefox \
+                        | bullseye | bullseye-chromium | bullseye-firefox )
 
                             clear_log
                             build_group "${command}" "${subject}" $@
@@ -330,11 +351,13 @@ main() {
                             clear_log
 
                             build_family "${command}" "latest"
-                            build_family "${command}" "latest-chromium"
                             build_family "${command}" "latest-firefox"
+                            build_family "${command}" "latest-chromium"
                             ;;
 
-                        latest | latest-chromium | latest-firefox )
+                        latest | latest-chromium | latest-firefox \
+                        | bookworm | bookworm-chromium | bookworm-firefox \
+                        | bullseye | bullseye-chromium | bullseye-firefox )
 
                             clear_log
                             build_family "${command}" "${subject}" $@

docker/.dockerignore

@@ -2,3 +2,4 @@
 !src
 !xfce*
 !.g3-cache
+

docker/Dockerfile.xfce.11

@@ -8,9 +8,9 @@ ARG ARG_MERGE_STAGE_BROWSER_BASE=merge_stage_vnc
 ARG ARG_FINAL_STAGE_BASE=merge_stage_browser
 
 ARG ARG_HEADLESS_USER_ID=1000
-ARG ARG_HEADLESS_USER_NAME=headless
+ARG ARG_HEADLESS_USER_NAME=akanealw
 ARG ARG_HEADLESS_USER_GROUP_ID=1000
-ARG ARG_HEADLESS_USER_GROUP_NAME=headless
+ARG ARG_HEADLESS_USER_GROUP_NAME=akanealw
 ARG ARG_SUDO_INITIAL_PW=headless
 
 
@@ -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 \
@@ -90,7 +91,9 @@ RUN \
     --mount=type=cache,from=stage_cache,sharing=locked,source=/var/lib/apt,target=/var/lib/apt \
     DEBIAN_FRONTEND=noninteractive apt-get install -y "${ARG_APT_NO_RECOMMENDS:+--no-install-recommends}" \
         xfce4 \
-        xfce4-terminal
+        xfce4-terminal \
+        gnome-themes-extra \
+        gnome-themes-extra-data 
 
 
 ###############
@@ -208,7 +211,6 @@ RUN echo \
         <meta charset=\"utf-8\"/>\n\
     </head>\n\
     <body>\n\
-        <p><a href=\"vnc_lite.html\">noVNC Lite Client</a></p>\n\
         <p><a href=\"vnc.html\">noVNC Full Client</a></p>\n\
     </body>\n\
 </html>" \
@@ -236,6 +238,9 @@ ENV \
 
 WORKDIR "${HOME}"
 
+### add '.bashrc' and similar resources
+COPY ./src/home "${HOME}"/
+
 
 ##################
 ### stage_chromium
@@ -292,7 +297,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 +314,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 +332,19 @@ 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_GROUP_NAME}:x:${HEADLESS_USER_GROUP_ID}:" >> /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/Dockerfile.xfce.12

@@ -0,0 +1,385 @@
+# syntax=docker/dockerfile:experimental
+
+ARG BASEIMAGE=debian
+ARG BASETAG=12-slim
+
+ARG ARG_MERGE_STAGE_VNC_BASE=stage_vnc
+ARG ARG_MERGE_STAGE_BROWSER_BASE=merge_stage_vnc
+ARG ARG_FINAL_STAGE_BASE=merge_stage_browser
+
+ARG ARG_HEADLESS_USER_ID=1000
+ARG ARG_HEADLESS_USER_NAME=akanealw
+ARG ARG_HEADLESS_USER_GROUP_ID=1000
+ARG ARG_HEADLESS_USER_GROUP_NAME=akanealw
+ARG ARG_SUDO_INITIAL_PW=headless
+
+
+###############
+### stage_cache
+###############
+
+FROM ${BASEIMAGE}:${BASETAG} as stage_cache
+
+### refresh the 'apt' cache
+RUN rm -f /etc/apt/apt.conf.d/docker-clean ; \
+    echo 'Binary::apt::APT::Keep-Downloaded-Packages "true" ;' > /etc/apt/apt.conf.d/keep-cache
+RUN apt-get update
+
+### embed the local '.g3-cache' from the build context
+### note that the bound cache '/tmp/cache2' is ephemeral and all written data will be discarded automatically
+### therefore copy its content into the another permanent cache '/tmp/g3-cache'
+RUN \
+    --mount=type=bind,target=/tmp/cache2 \
+    mkdir -p /tmp/g3-cache \
+    && if [ -d /tmp/cache2/.g3-cache/ ] ; then cp -r /tmp/cache2/.g3-cache/* /tmp/g3-cache/ ; fi
+
+
+####################
+### stage_essentials
+####################
+
+FROM ${BASEIMAGE}:${BASETAG} as stage_essentials
+
+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 \
+        procps \
+        psmisc \
+        sudo \
+        tini \
+        wget
+
+
+#################
+### stage_xserver
+#################
+
+FROM stage_essentials as stage_xserver
+ARG ARG_APT_NO_RECOMMENDS
+
+ENV \
+    FEATURES_BUILD_SLIM_XSERVER="${ARG_APT_NO_RECOMMENDS:+1}" \
+    NO_AT_BRIDGE=1
+
+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 "${ARG_APT_NO_RECOMMENDS:+--no-install-recommends}" \
+        dbus-x11 \
+        xauth \
+        xinit \
+        x11-xserver-utils \
+        xdg-utils
+
+
+##############
+### stage_xfce
+##############
+
+FROM stage_xserver as stage_xfce
+ARG ARG_APT_NO_RECOMMENDS
+
+ENV FEATURES_BUILD_SLIM_XFCE="${ARG_APT_NO_RECOMMENDS:+1}"
+
+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 "${ARG_APT_NO_RECOMMENDS:+--no-install-recommends}" \
+        xfce4 \
+        xfce4-terminal \
+        gnome-themes-extra \
+        gnome-themes-extra-data 
+
+
+###############
+### stage_tools
+###############
+
+FROM stage_xfce as stage_tools
+ARG ARG_APT_NO_RECOMMENDS
+ARG ARG_FEATURES_SCREENSHOOTING
+ARG ARG_FEATURES_THUMBNAILING
+
+ENV \
+    FEATURES_BUILD_SLIM_TOOLS="${ARG_APT_NO_RECOMMENDS:+1}" \
+    FEATURES_SCREENSHOOTING="${ARG_FEATURES_SCREENSHOOTING:+1}" \
+    FEATURES_THUMBNAILING="${ARG_FEATURES_THUMBNAILING:+1}"
+
+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 "${ARG_APT_NO_RECOMMENDS:+--no-install-recommends}" \
+        mousepad \
+        python3 \
+        systemctl \
+        "${ARG_FEATURES_SCREENSHOOTING:+ristretto}" \
+        "${ARG_FEATURES_SCREENSHOOTING:+xfce4-screenshooter}" \
+        "${ARG_FEATURES_THUMBNAILING:+tumbler}"
+
+
+#############
+### stage_vnc
+#############
+
+FROM stage_tools as stage_vnc
+ARG ARG_VNC_COL_DEPTH
+ARG ARG_VNC_DISPLAY
+ARG ARG_VNC_PORT
+ARG ARG_VNC_PW
+ARG ARG_VNC_RESOLUTION
+ARG ARG_VNC_VIEW_ONLY
+ARG ARG_TIGERVNC_DISTRO
+ARG ARG_TIGERVNC_VERSION
+
+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 \
+    --mount=type=cache,from=stage_cache,sharing=locked,source=/tmp/g3-cache/,target=/tmp/g3-cache/ \
+    TIGERVNC_VERSION="${ARG_TIGERVNC_VERSION}" \
+    TIGERVNC_DISTRO="${ARG_TIGERVNC_DISTRO}" \
+    &&  if [ ! -s /tmp/g3-cache/tigervnc/tigervnc-"${TIGERVNC_VERSION}"."${TIGERVNC_DISTRO}".tar.gz ] ; then  \
+            wget --show-progress --progress=bar:force:noscroll \
+                -q https://sourceforge.net/projects/tigervnc/files/stable/"${TIGERVNC_VERSION}"/tigervnc-"${TIGERVNC_VERSION}"."${TIGERVNC_DISTRO}".tar.gz \
+                -P /tmp/g3-cache/tigervnc ; \
+        fi \
+    &&  tar xzf /tmp/g3-cache/tigervnc/tigervnc-"${TIGERVNC_VERSION}"."${TIGERVNC_DISTRO}".tar.gz --strip 1 -C / \
+    &&  ln -s /usr/libexec/vncserver /usr/bin/vncserver \
+    &&  sed -i 's/exec(@cmd);/print "@cmd";\nexec(@cmd);/g' /usr/libexec/vncserver
+
+ENV \
+    DISPLAY="${ARG_VNC_DISPLAY:-:1}" \
+    FEATURES_VNC=1 \
+    VNC_COL_DEPTH="${ARG_VNC_COL_DEPTH:-24}" \
+    VNC_PORT="${ARG_VNC_PORT:-5901}" \
+    VNC_PW="${ARG_VNC_PW:-headless}" \
+    VNC_RESOLUTION="${ARG_VNC_RESOLUTION:-1360x768}" \
+    VNC_VIEW_ONLY="${ARG_VNC_VIEW_ONLY:-false}"
+
+EXPOSE "${VNC_PORT}"
+
+
+###############
+### stage_novnc
+###############
+
+FROM stage_vnc as stage_novnc
+ARG ARG_APT_NO_RECOMMENDS
+ARG ARG_NOVNC_PORT
+ARG ARG_NOVNC_VERSION
+ARG ARG_WEBSOCKIFY_VERSION
+
+ENV \
+    FEATURES_BUILD_SLIM_NOVNC="${ARG_APT_NO_RECOMMENDS:+1}" \
+    FEATURES_NOVNC=1 \
+    NOVNC_HOME="/usr/libexec/noVNCdim" \
+    NOVNC_PORT="${ARG_NOVNC_PORT:-6901}"
+
+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 \
+    --mount=type=cache,from=stage_cache,sharing=locked,source=/tmp/g3-cache/,target=/tmp/g3-cache/ \
+    DEBIAN_FRONTEND=noninteractive apt-get install -y "${ARG_APT_NO_RECOMMENDS:+--no-install-recommends}" \
+        python3-numpy \
+    &&  mkdir -p "${NOVNC_HOME}"/utils/websockify \
+    &&  NOVNC_VERSION="${ARG_NOVNC_VERSION}" \
+    &&  WEBSOCKIFY_VERSION="${ARG_WEBSOCKIFY_VERSION}" \
+    &&  if [ ! -s /tmp/g3-cache/novnc/v"${NOVNC_VERSION}".tar.gz ] ; then \
+            wget --show-progress --progress=bar:force:noscroll \
+                -q https://github.com/novnc/noVNC/archive/v"${NOVNC_VERSION}".tar.gz \
+                -P /tmp/g3-cache/novnc ; \
+        fi \
+    &&  if [ ! -s /tmp/g3-cache/websockify/v"${WEBSOCKIFY_VERSION}".tar.gz ] ; then \
+            wget --show-progress --progress=bar:force:noscroll \
+                -q https://github.com/novnc/websockify/archive/v"${WEBSOCKIFY_VERSION}".tar.gz \
+                -P /tmp/g3-cache/websockify ; \
+        fi \
+    &&  tar xzf /tmp/g3-cache/novnc/v"${NOVNC_VERSION}".tar.gz --strip 1 -C "${NOVNC_HOME}" \
+    &&  tar xzf /tmp/g3-cache/websockify/v"${WEBSOCKIFY_VERSION}".tar.gz --strip 1 -C "${NOVNC_HOME}"/utils/websockify \
+    &&  chmod 755 -v "${NOVNC_HOME}"/utils/novnc_proxy
+
+### add 'index.html' for choosing noVNC client
+RUN echo \
+"<!DOCTYPE html>\n\
+<html>\n\
+    <head>\n\
+        <title>noVNC</title>\n\
+        <meta charset=\"utf-8\"/>\n\
+    </head>\n\
+    <body>\n\
+        <p><a href=\"vnc.html\">noVNC Full Client</a></p>\n\
+    </body>\n\
+</html>" \
+> "${NOVNC_HOME}"/index.html
+
+EXPOSE "${NOVNC_PORT}"
+
+
+###################
+### merge_stage_vnc
+###################
+
+FROM ${ARG_MERGE_STAGE_VNC_BASE} as merge_stage_vnc
+ARG ARG_HEADLESS_USER_ID
+ARG ARG_HEADLESS_USER_NAME
+ARG ARG_HEADLESS_USER_GROUP_ID
+ARG ARG_HEADLESS_USER_GROUP_NAME
+
+ENV \
+    HEADLESS_USER_ID="${ARG_HEADLESS_USER_ID}" \
+    HEADLESS_USER_NAME="${ARG_HEADLESS_USER_NAME}" \
+    HEADLESS_USER_GROUP_ID="${ARG_HEADLESS_USER_GROUP_ID}" \
+    HEADLESS_USER_GROUP_NAME="${ARG_HEADLESS_USER_GROUP_NAME}" \
+    HOME="${ARG_HOME:-/home/${ARG_HEADLESS_USER_NAME}}"
+
+WORKDIR "${HOME}"
+
+### add '.bashrc' and similar resources
+COPY ./src/home "${HOME}"/
+
+
+##################
+### stage_chromium
+##################
+
+FROM merge_stage_vnc as stage_chromium
+ARG ARG_APT_NO_RECOMMENDS
+
+ENV \
+    FEATURES_BUILD_SLIM_CHROMIUM="${ARG_APT_NO_RECOMMENDS:+1}" \
+    FEATURES_CHROMIUM=1
+
+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 "${ARG_APT_NO_RECOMMENDS:+--no-install-recommends}" \
+        chromium
+
+COPY ./xfce-chromium/src/home/Desktop "${HOME}"/Desktop/
+COPY ./xfce-chromium/src/home/readme*.md "${HOME}"/
+
+
+#################
+### stage_firefox
+#################
+
+FROM merge_stage_vnc as stage_firefox
+ARG ARG_APT_NO_RECOMMENDS
+
+ENV \
+    FEATURES_BUILD_SLIM_FIREFOX="${ARG_APT_NO_RECOMMENDS:+1}" \
+    FEATURES_FIREFOX=1
+
+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 "${ARG_APT_NO_RECOMMENDS:+--no-install-recommends}" \
+        firefox-esr
+
+COPY ./xfce-firefox/src/home/Desktop "${HOME}"/Desktop/
+
+
+### ##################
+### stage_firefox_plus
+### ##################
+
+FROM stage_firefox as stage_firefox_plus
+
+ENV FEATURES_FIREFOX_PLUS=1
+
+COPY ./xfce-firefox/src/firefox.plus/home/Desktop "${HOME}"/Desktop/
+COPY ./xfce-firefox/src/firefox.plus/resources "${HOME}"/firefox.plus/
+COPY ./xfce-firefox/src/firefox.plus/home/readme*.md "${HOME}"/
+
+RUN \
+    chmod 744 "${HOME}"/firefox.plus/*.sh \
+    && 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 
+    
+
+#######################
+### merge_stage_browser
+#######################
+
+FROM ${ARG_MERGE_STAGE_BROWSER_BASE} as merge_stage_browser
+
+
+###############
+### FINAL STAGE
+###############
+
+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"
+
+COPY ./src/xfce-startup "${STARTUPDIR}"/
+COPY ./src/tests "${HOME}"/tests/
+
+COPY ./xfce/src/home/config "${HOME}"/.config/
+COPY ./xfce/src/home/Desktop "${HOME}"/Desktop/
+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 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_GROUP_NAME}:x:${HEADLESS_USER_GROUP_ID}:" >> /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}" > "${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}"
+
+
+USER "${HEADLESS_USER_ID}"
+
+ENTRYPOINT [ "/usr/bin/tini", "--", "/dockerstartup/startup.sh" ]
+
+# RUN chmod 644 /etc/passwd /etc/group
+# ENTRYPOINT [ "/usr/bin/tini", "--", "tail", "-f", "/dev/null" ]
+
+
+##################
+### METADATA STAGE
+##################
+
+FROM stage_final as stage_metadata
+ARG ARG_CREATED
+ARG ARG_DOCKER_TAG
+ARG ARG_VCS_REF
+ARG ARG_VERSION_STICKER
+
+LABEL \
+    org.opencontainers.image.authors="accetto" \
+    org.opencontainers.image.created="${ARG_CREATED}" \
+    org.opencontainers.image.description="Headless Debian/Xfce/VNC/noVNC containers with Internet browsers" \
+    org.opencontainers.image.documentation="https://github.com/accetto/debian-vnc-xfce-g3" \
+    org.opencontainers.image.source="https://github.com/accetto/debian-vnc-xfce-g3" \
+    org.opencontainers.image.title="accetto/debian-vnc-xfce-g3" \
+    org.opencontainers.image.url="https://github.com/accetto/debian-vnc-xfce-g3" \
+    org.opencontainers.image.vendor="https://github.com/accetto" \
+    org.opencontainers.image.version="${ARG_DOCKER_TAG}"
+
+LABEL \
+    org.label-schema.vcs-url="https://github.com/accetto/debian-vnc-xfce-g3" \
+    org.label-schema.vcs-ref="${ARG_VCS_REF}"
+
+LABEL \
+    any.accetto.version-sticker="${ARG_VERSION_STICKER}"

docker/hooks/build

@@ -1,4 +1,4 @@
-#!/bin/bash -e
+#!/bin/bash
 
 echo -e "\n==> EXECUTING @$(date -u +'%Y-%m-%d_%H-%M-%S'): ${0} $@\n"
 
@@ -62,11 +62,10 @@ main() {
     now="$(date --utc +%FT%TZ)"
     echo "Current timestamp: ${now}" ; echo
 
+    ### no quotes around ${params}!
     set -x
-    ### 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} \
             \
@@ -91,7 +91,11 @@ main() {
             ${FEATURES_FIREFOX_PLUS:+--build-arg ARG_MERGE_STAGE_BROWSER_BASE="stage_firefox_plus"} \
             \
         -t "${DOCKER_REPO}:${DOCKER_TAG}${target_stage:+_${target_stage}}" "${_build_context}"
+
+    exit_code=$?
     set +x
+    
+    if [[ ${exit_code} -ne 0 ]] ; then die "Failed to build image '${DOCKER_REPO}:${DOCKER_TAG}'" ${exit_code} ; fi
 }
 
 main $@

docker/hooks/cache

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

docker/hooks/env.rc

@@ -5,7 +5,7 @@ die() {
     local -i code=${2:-1}
     local place="${3:-$0}"
 
-    echo -e "EXITING '${place}' with code ${code}: ${message}" >&2
+    echo -e "EXITING at line "${BASH_LINENO[0]}" in '${place}' with code ${code}: ${message}" >&2
     exit ${code}
 }
 
@@ -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"
@@ -49,7 +49,8 @@ DOCKER_REPO="${_owner}/${BUILDER_REPO:?Need builder repo name}"
 
 declare _deploy_repo
 
-### array of the image tags to be deployed
+### arrays of the image tags to be deployed
+declare -a _deploy_builder_tags
 declare -a _deploy_tags
 declare _deploytag
 
@@ -73,9 +74,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 empty.
 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 +89,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 empty.
+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
 
@@ -118,10 +125,16 @@ case "${_branch}" in
         ### choose the Dockerfile
         case "${_blend}" in
 
-            latest | latest-chromium | latest-firefox)
+            latest | latest-chromium | latest-firefox | bookworm | bookworm-chromium | bookworm-firefox)
+
+                BASETAG="12-slim"
+                DOCKERFILE_PATH="${_build_context}/Dockerfile.xfce.12"
+                ;;
+            
+            bullseye | bullseye-chromium | bullseye-firefox)
 
                 BASETAG="11-slim"
-                DOCKERFILE_PATH="${_build_context}/Dockerfile.xfce"
+                DOCKERFILE_PATH="${_build_context}/Dockerfile.xfce.11"
                 ;;
 
             * )
@@ -132,7 +145,10 @@ case "${_branch}" in
         ### set the building parameters
         case "${_blend}" in
 
-            latest | latest-chromium | latest-firefox )
+            latest | latest-chromium | latest-firefox \
+            | bookworm | bookworm-chromium | bookworm-firefox \
+            | bullseye | bullseye-chromium | bullseye-firefox \
+            )
 
                 ### this feature is enabled by default
                 ### however, it can be disabled via environment variables (export FEATURES_NOVNC=0)
@@ -185,8 +201,36 @@ case "${_branch}" in
                 fi
 
                 ### normalize deployment tags
-                DOCKER_TAG="${_blend}"
-                _deploy_tags=( "latest" )
+                case "${_blend}" in
+
+                    latest | latest-* )
+
+                        ### latest -> 12
+                        DOCKER_TAG="${_blend}"
+                        _deploy_tags=( "latest" "12" )
+                        _deploy_builder_tags=( "${_blend}" "${_blend/latest/12}" )
+                        ;;
+                
+                    bookworm | bookworm-* )
+
+                        ### bookworm -> 12
+                        DOCKER_TAG="${_blend/bookworm/12}"
+                        _deploy_tags=( "latest" "12" )
+                        _deploy_builder_tags=( "${_blend/bookworm/latest}" "${_blend/bookworm/12}" )
+                        ;;
+                
+                    bullseye | bullseye-* )
+
+                        ### bullseye -> 11
+                        DOCKER_TAG="${_blend/bullseye/11}"
+                        _deploy_tags=( "11" )
+                        _deploy_builder_tags=( "${_blend/bullseye/11}" )
+                        ;;
+
+                    * )
+                        die "Unsupported blend '${_blend}'"
+                        ;;
+                esac
 
                 ### add optional suffixes to deployment tags
 
@@ -217,4 +261,4 @@ case "${_branch}" in
     * )
         die "Unsupported branch '${_branch}'"
         ;;
-esac
+esac

docker/hooks/post_push

@@ -1,4 +1,4 @@
-#!/bin/bash -e
+#!/bin/bash
 
 ### 2022-09-11 Warning
 ### It seems like the README publishing is currently not always working. 
@@ -23,6 +23,7 @@ main() {
     local version_sticker_verbose
     local repo_building="${DOCKER_REPO##*/}"
     local repo_deploy="${_deploy_repo##*/}"
+    local keeper_repo_tag="${_deploy_builder_tags[0]}"
 
     ### debugging support
     # dump_environment
@@ -33,18 +34,21 @@ main() {
         if [[ -n "${GIST_TOKEN}" && -n "${GIST_ID}" && -n "${DEPLOY_GIST_ID}" ]] ; then
         
             if [[ ( -n "${repo_deploy}" && "${repo_deploy}" != "${_prohibited_repo_name}" ) \
-            || ( "${FORCE_PUBLISHING_BUILDER_REPO}" == "1" && -n "${repo_building}" && "${repo_building}" != "${_prohibited_repo_name}" ) ]] ; \
+            || ( "${FORCE_PUBLISHING_BUILDER_REPO:-0}" == "1" && -n "${repo_building}" && "${repo_building}" != "${_prohibited_repo_name}" ) ]] ; \
             then
 
                 ### get values for badges from the image metadata (labels)
-                created=$( get_label "${DOCKER_REPO}:${DOCKER_TAG}" "org.opencontainers.image.created" )
-                version_sticker=$( get_label "${DOCKER_REPO}:${DOCKER_TAG}" "any.accetto.version-sticker" )
+                created=$( get_label "${DOCKER_REPO}:${keeper_repo_tag}" "org.opencontainers.image.created" )
+                version_sticker=$( get_label "${DOCKER_REPO}:${keeper_repo_tag}" "any.accetto.version-sticker" )
                 version_sticker_verbose=$( cat "${_build_context}/${_scrap_version_sticker_verbose_current}" )
 
                 ### update badge endpoints in the builder repository gist
-                update_gist "${GIST_ID}" "${_gist_key_created}" "${DOCKER_REPO}" "${DOCKER_TAG}" "${created}"
-                update_gist "${GIST_ID}" "${_gist_key_version_sticker}" "${DOCKER_REPO}" "${DOCKER_TAG}" "${version_sticker}"
-                update_gist "${GIST_ID}" "${_gist_key_version_sticker_verbose}" "${DOCKER_REPO}" "${DOCKER_TAG}" "${version_sticker_verbose}"
+                for t in "${_deploy_builder_tags[@]}" ; do
+
+                    update_gist "${GIST_ID}" "${_gist_key_created}" "${DOCKER_REPO}" "${t}" "${created}"
+                    update_gist "${GIST_ID}" "${_gist_key_version_sticker}" "${DOCKER_REPO}" "${t}" "${version_sticker}"
+                    update_gist "${GIST_ID}" "${_gist_key_version_sticker_verbose}" "${DOCKER_REPO}" "${t}" "${version_sticker_verbose}"
+                done
 
             else
                 echo "Skipping builder gist update because of null or prohibited target repositories."
@@ -57,7 +61,7 @@ main() {
 
                     ### note that the builder and deployment repositories could be identical
                     ### in that case skip the tag which has been already published above
-                    if [[ "${DOCKER_REPO}" != "${_deploy_repo}" || "${DOCKER_TAG}" != "${t}" ]] ; then
+                    if [[ "${DOCKER_REPO}" != "${_deploy_repo}" || "${keeper_repo_tag}" != "${t}" ]] ; then
 
                         update_gist "${DEPLOY_GIST_ID}" "${_gist_key_created}" "${_deploy_repo}" "${t}" "${created}"
                         update_gist "${DEPLOY_GIST_ID}" "${_gist_key_version_sticker}" "${_deploy_repo}" "${t}" "${version_sticker}"

docker/hooks/pre_build

@@ -1,4 +1,4 @@
-#!/bin/bash -e
+#!/bin/bash
 
 echo -e "\n==> EXECUTING @$(date -u +'%Y-%m-%d_%H-%M-%S'): ${0} $@\n"
 
@@ -13,7 +13,7 @@ main() {
     local version_sticker
     local -i exit_code=0
 
-    local should_build=${FORCE_BUILDING}
+    local should_build=${FORCE_BUILDING:-0}
     local build_prohibited=${PROHIBIT_BUILDING}
     local cache_script="cache"
 
@@ -57,15 +57,16 @@ main() {
     fi
 
     ### build a temporary helper image for getting the current version sticker values
+
+    ### no quotes around ${params}!
     set -x
-    ### 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} \
             \
@@ -82,8 +83,12 @@ main() {
             ${FEATURES_FIREFOX_PLUS:+--build-arg ARG_MERGE_STAGE_BROWSER_BASE="stage_firefox_plus"} \
             \
         -t "${DOCKER_REPO}":"${DOCKER_TAG}${helper_suffix}" "${_build_context}"
+    
+    exit_code=$?
     set +x
 
+    if [[ ${exit_code} -ne 0 ]] ; then set +x; die "Failed to build image '${DOCKER_REPO}:${DOCKER_TAG}${helper_suffix}'" ${exit_code} ; fi
+
     ### get the actual verbose version sticker value from the helper image and store it as the current one
     ### note that some apps require display to report their versions correctly (e.g. Ristretto or Screenshooter)
     # version_sticker="$( docker run --rm ${DOCKER_REPO}:${DOCKER_TAG}${helper_suffix} --skip-vnc --version-sticker-verbose )"

docker/hooks/push

@@ -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"
@@ -10,6 +11,8 @@ source "${_mydir}"/util.rc
 deployment_push() {
     local target
     local repo="${_deploy_repo##*/}"
+    local keeper_repo_tag="${_deploy_builder_tags[0]}"
+    local -i exit_code=0
 
     if [[ -n "${repo}" && "${repo}" != "${_prohibited_repo_name}" ]] ; then
 
@@ -18,24 +21,33 @@ deployment_push() {
 
             ### note that the builder and deployment repositories could be identical
             ### in that case skip the tag which has been already published above
-            if [[ "${DOCKER_REPO}" != "${_deploy_repo}" || "${DOCKER_TAG}" != "${t}" ]] ; then
+            if [[ "${DOCKER_REPO}" != "${_deploy_repo}" || "${keeper_repo_tag}" != "${t}" ]] ; then
 
                 target="${_deploy_repo}:${t}"
 
                 echo ; echo "Deploying image '${target}'"
-                docker tag "${DOCKER_REPO}:${DOCKER_TAG}" "${target}"
+                docker tag "${DOCKER_REPO}:${keeper_repo_tag}" "${target}"
                 docker push "${target}"
+                exit_code=$?
+                docker rmi "${target}"
+
+                if [[ ${exit_code} -ne 0 ]] ; then
+                    docker logout
+                    die "Unable to push image '${target}'" ${exit_code}
+                fi
             fi
         done
 
     else
-        echo "Skipping push because of null or prohibited deployment repository '${repo}'."
+        echo "Skipping deployment repo push because of null or prohibited deployment repository '${repo}'."
     fi
 }
 
 main() {
     local target
     local repo="${DOCKER_REPO##*/}"
+    local keeper_repo_tag="${_deploy_builder_tags[0]}"
+    local -i exit_code=0
 
     if [[ -f "${_build_context}/${_scrap_demand_stop_building}" ]] ; then
         echo "Skipping push on demand."
@@ -61,15 +73,42 @@ main() {
     fi
 
     ### push images into the builder repository
-    if [[ "${FORCE_PUBLISHING_BUILDER_REPO}" == "1" ]] ; then
+    if [[ "${FORCE_PUBLISHING_BUILDER_REPO:-0}" == "1" ]] ; then
 
         if [[ -n "${repo}" && "${repo}" != "${_prohibited_repo_name}" ]] ; then
 
-            echo ; echo "Pushing builder image ${DOCKER_REPO}:${DOCKER_TAG}"
-            docker push ${DOCKER_REPO}:${DOCKER_TAG}
+            ### push all target tags into the builder repository
+            for t in "${_deploy_builder_tags[@]}" ; do
+
+                echo ; echo "Pushing builder image ${DOCKER_REPO}:${t}"
+
+                if [[ "${t}" == "${keeper_repo_tag}" ]] ; then
+
+                    # first element is the master repo (a keeper)
+                    docker push "${DOCKER_REPO}:${t}"
+                    exit_code=$?
+
+                    if [[ ${exit_code} -ne 0 ]] ; then
+                        docker logout
+                        die "Unable to push image '${DOCKER_REPO}:${t}'" ${exit_code}
+                    fi
+                else
+                    target="${DOCKER_REPO}:${t}"
+
+                    docker tag "${DOCKER_REPO}:${keeper_repo_tag}" "${target}"
+                    docker push "${target}"
+                    exit_code=$?
+                    docker rmi "${target}"
+
+                    if [[ ${exit_code} -ne 0 ]] ; then
+                        docker logout
+                        die "Unable to push image '${target}'" ${exit_code}
+                    fi
+                fi
+            done
 
         else
-            echo "Skipping forced push because of null or prohibited builder repository '${repo}'."
+            echo "Skipping forced builder repo push because of null or prohibited builder repository '${repo}'."
         fi
     fi
 

docker/hooks/release_of

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

docker/hooks/secrets.rc

@@ -0,0 +1,116 @@
+### This files configures the environment (including secrets!) for building images locally.
+### Source this file before building.
+### Rename it to "secrets.rc" (or similar) and **make sure** that the '.gitignore' and '.dockerignore' files 
+### contain the 'secret*' exclusion pattern!
+### Example: source ./secrets.rc
+### This file is automatically sourced by the script 'hooks/env.rc' if it's found in the same directory.
+
+#region General building pipeline control
+
+export DOCKER_BUILDKIT=1
+# export COMPOSE_DOCKER_CLI_BUILD=0
+
+### will force re-building regardless of the verbose version sticker changes
+export FORCE_BUILDING=1
+
+### will prohibit re-building regardless of verbose version sticker changes
+# export PROHIBIT_BUILDING=0
+
+#endregion
+
+
+#region Optional version sticker prefix and/or suffix
+
+# export VERSION_STICKER_PREFIX="LOCAL-BETA-"
+# export VERSION_STICKER_SUFFIX="-BETA"
+
+#endregion
+
+
+#region Development environment
+
+### -----------------------
+### development environment
+### -----------------------
+
+# ### owner of Gitea repos
+# export REPO_OWNER_NAME=""
+# ### development builder gist
+# export GIST_ID=""
+# ### development deployment gist
+# export DEPLOY_GIST_ID=""
+# ### note that the reserved repository name 'void' will prohibit the publishing
+# ### primary deployment repos may not exist (may be also left unset)
+# export DEPLOYMENT_REPO=""
+# export DEPLOYMENT_REPO_CHROMIUM=""
+# export DEPLOYMENT_REPO_FIREFOX=""
+# ### builder repo can be a secondary deployment repo (if FORCE_PUBLISHING_BUILDER_REPO=1)
+# export BUILDER_REPO=""
+# ### shared g3-cache is outside the Docker building context
+# export SHARED_G3_CACHE_PATH=""
+# ### used to control building/publishing (unset means '0')
+# export FORCE_PUBLISHING_BUILDER_REPO=1
+# export FORCE_BUILDING=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_OVERRIDING_ENVV=0
+
+#endregion
+
+
+#region Production environment
+
+### ----------------------
+### production environment
+### ----------------------
+
+# ### owner of Docker Hub repos
+export REPO_OWNER_NAME="repo.aknlw.com"
+# ### production builder gist
+# export GIST_ID=""
+# ### produktion deployment gist
+# export DEPLOY_GIST_ID=""
+# ### note that the reserved repository name 'void' will prohibit the publishing
+# ### primary deployment repos
+export DEPLOYMENT_REPO="repo.aknlw.com"
+export DEPLOYMENT_REPO_CHROMIUM="akanealw/debian-vnc-xfce-chromium"
+export DEPLOYMENT_REPO_FIREFOX="akanealw/debian-vnc-xfce-firefox"
+# ### builder repo can be a secondary deployment repo (if FORCE_PUBLISHING_BUILDER_REPO=1)
+export BUILDER_REPO="akanealw/debian-vnc-xfce"
+# ### shared g3-cache is outside the Docker building context
+# export SHARED_G3_CACHE_PATH=""
+# ### used to control building/publishing (unset means '0')
+# export FORCE_PUBLISHING_BUILDER_REPO=1
+# export FORCE_BUILDING=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_OVERRIDING_ENVV=0
+
+#endregion
+
+
+#region Real secrets
+
+### ------------
+### REAL SECRETS
+### ------------
+
+### !!! REAL SECRET !!!
+### Gitea: Settings/Developer settings/Personal access tokens
+### this PAT must have the 'gist' scope
+### warning! this gist token is valid for all gits of the same owner!
+# export GIST_TOKEN=""
+
+### !!! REAL SECRETS !!!
+### Docker Hub credentials
+### warning! this credentials are valid for all Docker Hub repositories of the same owner!
+# export DOCKERHUB_USERNAME=""
+# export DOCKERHUB_PASSWORD=""
+
+#endregion

docker/src/home/.bashrc

@@ -0,0 +1,18 @@
+### some examples of custom aliases
+
+alias ll="ls -l"
+
+### clear terminal window
+alias cls='printf "\033c"'
+
+### change terminal prompt text
+fn_ps1() {
+    if [ $# -gt 0 ] ; then
+        ### given value in bold green
+        PS1="\[\033[01;32m\]$1\[\033[00m\]> "
+    else
+        ### basename of the current working directory in bold blue
+        PS1='\[\033[01;34m\]\W\[\033[00m\]> '
+    fi
+}
+alias ps1='fn_ps1'

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

@@ -5,45 +5,76 @@ generate_container_user() {
 
     local user_id
     local group_id
-    local application_user_name
-    local group_name
+    local headless_user_name
+    local headless_group_name
 
-    ### note that this block will be exuceted only once (see the end of the if-block)
+    ### note that this block will be executed only once (see the end of the if-block)
     if [[ -w /etc/passwd ]] ; then
 
         user_id="$(id -u)"
         group_id="$(id -g)"
-        application_user_name="${HEADLESS_USER_NAME}"
-        group_name="${HEADLESS_USER_GROUP_NAME}"
+        headless_user_name="${HEADLESS_USER_NAME}"
+        headless_group_name="${HEADLESS_USER_GROUP_NAME}"
 
-        ### user 'root (0)' is always created by default
-        ### user 'application_user_name' is created by Dockerfile
-        if [[ "${user_id}" != "0" && "${user_id}" != "${HEADLESS_USER_ID}" ]] ; then
+        ### add the new group if the same GID does not exist yet
+        if [[ "${group_id}" != "0" && "${group_id}" != "${HEADLESS_USER_GROUP_ID}" ]] ; then
 
-            ### rename the existing 'application_user_name' to 'builder'
-            if [[ $( grep -c "${application_user_name}:x:${HEADLESS_USER_ID}:" /etc/passwd ) -ne 0 ]]; then
+            ### rename the existing 'headless_group_name' into 'g3builder'
+            if [[ $( grep -c "${headless_group_name}:x:${HEADLESS_USER_GROUP_ID}:" /etc/group ) -ne 0 ]]; then
 
-                cat /etc/passwd | sed -e "s/^${application_user_name}:x:${HEADLESS_USER_ID}:${HEADLESS_USER_GROUP_ID}:Default:/builder:x:${HEADLESS_USER_ID}:${HEADLESS_USER_GROUP_ID}:Builder:/" > /tmp/passwd
+                cat /etc/group | sed -e "s/^${headless_group_name}:x:${HEADLESS_USER_GROUP_ID}:/g3builder:x:${HEADLESS_USER_GROUP_ID}:/" > /tmp/group
 
-                cp /tmp/passwd /etc/
-                rm /tmp/passwd
+                cp /tmp/group /etc/
+                rm /tmp/group
 
                 if [[ -n "${_verbose}" ]] ; then
-                    echo "User '${application_user_name} (${HEADLESS_USER_ID}:${HEADLESS_USER_GROUP_ID})' renamed to 'builder (${HEADLESS_USER_ID}:${HEADLESS_USER_GROUP_ID})' in '/etc/passwd'"
+                    echo "Default user group '${headless_group_name}(${HEADLESS_USER_GROUP_ID})' renamed into 'g3builder(${HEADLESS_USER_GROUP_ID})' in '/etc/group'"
                 fi
             fi
 
-            ### add the current application user ID as a new 'application_user_name' if it does not exist yet
-            if [[ $( grep -c "${application_user_name}:x:${user_id}:" /etc/passwd ) -eq 0 ]] ; then
+            ### add the current default user group ID as a new 'headless_group_name' if it does not exist yet
+            if [[ $( grep -c -E ":x:${group_id}:$" /etc/group ) -eq 0 ]] ; then
 
-                cat /etc/passwd > /tmp/passwd
-                echo "${application_user_name}:x:${user_id}:${group_id}:Default:${HOME}:/bin/bash" >> /tmp/passwd
+                cat /etc/group > /tmp/group
+                echo "${headless_group_name}:x:${group_id}:" >> /tmp/group
+
+                cp /tmp/group /etc/
+                rm /tmp/group
+
+                if [[ -n "${_verbose}" ]] ; then
+                    echo "Default user group '${headless_group_name}(${group_id})' added into '/etc/group'"
+                fi
+            fi
+        fi
+
+        ### user 'root (0)' is always created by default
+        ### user 'headless_user_name' is created by Dockerfile
+        if [[ "${user_id}" != "0" && "${user_id}" != "${HEADLESS_USER_ID}" ]] ; then
+
+            ### rename the existing 'headless_user_name' into 'g3builder'
+            if [[ $( grep -c "${headless_user_name}:x:${HEADLESS_USER_ID}:" /etc/passwd ) -ne 0 ]]; then
+
+                cat /etc/passwd | sed -e "s/^${headless_user_name}:x:${HEADLESS_USER_ID}:${HEADLESS_USER_GROUP_ID}:Default:/g3builder:x:${HEADLESS_USER_ID}:${HEADLESS_USER_GROUP_ID}:G3Builder:/" > /tmp/passwd
 
                 cp /tmp/passwd /etc/
                 rm /tmp/passwd
 
                 if [[ -n "${_verbose}" ]] ; then
-                    echo "User '${application_user_name} (${user_id}:${group_id})' added into '/etc/passwd'"
+                    echo "Default user '${headless_user_name}(${HEADLESS_USER_ID}:${HEADLESS_USER_GROUP_ID})' renamed into 'g3builder(${HEADLESS_USER_ID}:${HEADLESS_USER_GROUP_ID})' in '/etc/passwd'"
+                fi
+            fi
+
+            ### add the current default user ID as a new 'headless_user_name' if it does not exist yet
+            if [[ $( grep -c "${headless_user_name}:x:${user_id}:" /etc/passwd ) -eq 0 ]] ; then
+
+                cat /etc/passwd > /tmp/passwd
+                echo "${headless_user_name}:x:${user_id}:${group_id}:Default:${HOME}:/bin/bash" >> /tmp/passwd
+
+                cp /tmp/passwd /etc/
+                rm /tmp/passwd
+
+                if [[ -n "${_verbose}" ]] ; then
+                    echo "Default user '${headless_user_name}(${user_id}:${group_id})' added into '/etc/passwd'"
                 fi
 
                 ### update the environment variables
@@ -52,33 +83,19 @@ generate_container_user() {
             fi
         fi
 
-        ### add the new group if the same GID does not exist yet
-        if [[ "${group_id}" != "0" ]] ; then
+        if [[ -s "${STARTUPDIR}"/.initial_sudo_password ]] ; then
 
-            if [[ $( grep -c -E ":x:${group_id}:$" /etc/group ) -eq 0 ]] ; then
+            ### 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
 
-                cat /etc/group > /tmp/group
-                echo "${group_name}:x:${group_id}:" >> /tmp/group
+            ### 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
 
-                cp /tmp/group /etc/
-                rm /tmp/group
-
-                if [[ -n "${_verbose}" ]] ; then
-                    echo "Group '${group_name} (${group_id})' added into '/etc/group'"
-                fi
-            fi
+            ### 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
-
-        ### 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
-
-        ### 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
-
-        ### 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
     fi
 }

docker/src/xfce-startup/version_of.sh

@@ -8,7 +8,7 @@ case "$1" in
         echo $(ng --version 2>/dev/null | grep -Po -m1 '(?<=Angular CLI:\s)[0-9.]+')
         ;;
     chromium | chromium-browser)
-        ### source example: Chromium 109.0.5414.119 built on Debian 11.6, running on Debian 11.6
+        ### source example: Chromium 115.0.5790.170 built on Debian 12.1, running on Debian 12.1
         echo $(chromium --version 2>/dev/null | grep -Po -m1 '(?<=Chromium\s)[0-9.]+')
         ;;
     code | vsc | vscode | visual-studio-code | visualstudiocode )

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-dockerhub.md

@@ -2,237 +2,135 @@
 
 ## accetto/debian-vnc-xfce-chromium-g3
 
-[Docker Hub][this-docker] - [Git Hub][this-github] - [Dockerfile][this-dockerfile] - [Full Readme][this-readme-full] - [Changelog][this-changelog] - [Project Readme][this-readme-project]
+[User Guide][this-user-guide] - [GitHub][this-github] - [Dockerfile][this-dockerfile] - [Readme][this-readme-full] - [Changelog][this-changelog]
 
 ![badge-docker-pulls][badge-docker-pulls]
 ![badge-docker-stars][badge-docker-stars]
 ![badge-github-release][badge-github-release]
-![badge-github-release-date][badge-github-release-date]
 
 ***
 
-- [Headless Debian/Xfce container with VNC/noVNC and Chromium Browser](#headless-debianxfce-container-with-vncnovnc-and-chromium-browser)
-  - [accetto/debian-vnc-xfce-chromium-g3](#accettodebian-vnc-xfce-chromium-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)
-    - [Description](#description)
-    - [Image tags](#image-tags)
-    - [More information](#more-information)
+This Docker Hub repository contains Docker images for headless working.
 
-***
+The images are based on the current [Debian 12][docker-debian] and the previous [Debian 11][docker-debian] and include [Xfce][xfce] desktop, [TigerVNC][tigervnc] server and [noVNC][novnc] client.
+The popular web browser [Chromium][chromium] is also included.
 
-### Introduction
+This [User guide][this-user-guide] describes the images and how to use them.
 
-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.
+The related [GitHub project][this-github] contains image generators that image users generally don’t need, unless they want to build the images themselves.
 
-There is also a similar sibling image [accetto/ubuntu-vnc-xfce-chromium-g3][accetto-dockerhub-ubuntu-vnc-xfce-chromium-g3] based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu].
+### Tags
 
-This is the **short README** version for the **Docker Hub**. There is also the [full-length README][this-readme-full] on the **GitHub**.
+The following image tags are regularly built and published on Docker Hub:
 
-### TL;DR
+<!-- markdownlint-disable MD052 -->
 
-#### Installing packages
+- `latest` (also as `12`) based on `Debian 12`
 
-I try to keep the images slim. Consequently you can 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.
+    ![badge_latest_created][badge_latest_created]
+    [![badge_latest_version-sticker][badge_latest_version-sticker]][link_latest_version-sticker-verbose]
 
-You can also try to fix it by executing the following (the default `sudo` password is **headless**):
+- `11` based on `Debian 11`
 
-```shell
-### apt cache needs to be updated only once
-sudo apt-get update
+    ![badge_11_created][badge_11_created]
+    [![badge_11_version-sticker][badge_11_version-sticker]][link_11_version-sticker-verbose]
 
-sudo apt --fix-broken install
-```
+<!-- markdownlint-enable MD052 -->
 
-#### Shared memory size
+**Hint:** Clicking the version sticker badge reveals more information about the particular build.
 
-Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior.
-
-You can check the current shared memory size by executing the following command inside the container:
-
-```shell
-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
-
-The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images.
-
-Your concrete `Dockerfile` may need more statements, but the concept should be clear.
-
-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
-
-The fastest way to build the images:
-
-```shell
-### PWD = project root
-### prepare and source the 'secrets.rc' file first (see 'example-secrets.rc')
-
-### examples of building and publishing the individual images 
-./builder.sh latest-chromium all
-
-### just building an image, skipping the publishing and the version sticker update
-./builder.sh latest-chromium build
-
-### examples of building and publishing the images as a group
-./ci-builder.sh all group latest-chromium
-
-### or also
-./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 [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 the [local-building-example][this-readme-local-building-example] for more information.
-
-#### Sharing devices
-
-Sharing the audio device for video with sound works only with `Chromium` and only on Linux:
-
-```shell
-docker run -it -P --rm \
-  --device /dev/snd:/dev/snd:rw \
-  --group-add audio \
-accetto/debian-vnc-xfce-chromium-g3:latest
-```
-
-Sharing the display with the host works only on Linux:
-
-```shell
-xhost +local:$(whoami)
-
-docker run -it -P --rm \
-    -e DISPLAY=${DISPLAY} \
-    --device /dev/dri/card0 \
-    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
-    accetto/debian-vnc-xfce-chromium-g3:latest --skip-vnc
-
-xhost -local:$(whoami)
-```
-
-Sharing the X11 socket with the host works only on Linux:
-
-```shell
-xhost +local:$(whoami)
-
-docker run -it -P --rm \
-    --device /dev/dri/card0 \
-    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
-    accetto/debian-vnc-xfce-chromium-g3:latest
-
-xhost -local:$(whoami)
-```
-
-### Description
-
-**Attention:** The [Chromium Browser][chromium] in these images runs in the `--no-sandbox` mode. You should be aware of the implications. The image is intended for testing and development.
-
-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].
+### Features
 
 The main features and components of the images in the default configuration are:
 
-- utilities **ping**, **wget**, **sudo** (Debian distribution)
+- lightweight [Xfce][xfce] desktop environment (Debian distribution)
+- [sudo][sudo] support
 - current version of JSON processor [jq][jq]
-- light-weight [Xfce][xfce] desktop environment (Debian distribution)
 - current version of high-performance [TigerVNC][tigervnc] server and client
 - current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**)
 - popular text editor [nano][nano] (Debian distribution)
 - lite but advanced graphical editor [mousepad][mousepad] (Debian distribution)
 - 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**)
+- support for overriding environment variables, VNC parameters, user and group (see [User guide][this-user-guide-using-containers])
+- support of **version sticker** (see [User guide][this-user-guide-version-sticker])
 - current version of [Chromium Browser][chromium] open-source web browser (Debian distribution)
 
-The history of notable changes is documented in the [CHANGELOG][this-changelog].
+The following **TCP** ports are exposed by default:
+
+- **5901** for access over **VNC** (using VNC viewer)
+- **6901** for access over [noVNC][novnc] (using web browser)
 
 ![container-screenshot][this-screenshot-container]
 
-### Image tags
+### Remarks
 
-The following image tags are regularly built and published on the **Docker Hub**:
+There is also a similar sibling image [accetto/ubuntu-vnc-xfce-chromium-g3][accetto-dockerhub-ubuntu-vnc-xfce-chromium-g3] based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu].
 
-- `latest` based on `Debian 11`
+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].
 
-    ![badge_latest_created][badge_latest_created]
-    [![badge_latest_version-sticker][badge_latest_version-sticker]][link_latest_version-sticker-verbose]
+The [Chromium Browser][chromium] in these images runs in the `--no-sandbox` mode.
+You should be aware of the implications.
+The images are intended for testing and development.
 
-Clicking on the version sticker badge reveals more information about the actual configuration of the image.
+### Getting help
 
-### More information
+If you've found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and [sibling Wiki][sibling-wiki] first.
+Please do not overlook the closed issues.
 
-More information about these images can be found in the [full-length README][this-readme-full] file on the GitHub.
+If you do not find a solution, you can file a new issue.
+The better you describe the problem, the bigger the chance it'll be solved soon.
+
+If you have a question or an idea and you don't want to open an issue, you can also use the [sibling Discussions][sibling-discussions].
 
 ***
 
-<!-- GitHub project common -->
+[this-user-guide]: https://accetto.github.io/user-guide-g3/
+
+[this-user-guide-version-sticker]: https://accetto.github.io/user-guide-g3/version-sticker/
+
+[this-user-guide-using-containers]: https://accetto.github.io/user-guide-g3/using-containers/
 
 [this-changelog]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/CHANGELOG.md
+
 [this-github]: https://github.com/accetto/debian-vnc-xfce-g3/
-<!-- [this-issues]: https://github.com/accetto/debian-vnc-xfce-g3/issues -->
+
 [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
+[this-issues]: https://github.com/accetto/debian-vnc-xfce-g3/issues
 
-<!-- Docker image specific -->
-
-[this-docker]: https://hub.docker.com/r/accetto/debian-vnc-xfce-chromium-g3/
 [this-dockerfile]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/docker/Dockerfile.xfce
 
-[this-screenshot-container]: https://raw.githubusercontent.com/accetto/debian-vnc-xfce-g3/master/docker/doc/images/debian-vnc-xfce-chromium.jpg
-
-<!-- Sibling projects -->
+[this-screenshot-container]: https://raw.githubusercontent.com/accetto/debian-vnc-xfce-g3/master/docker/doc/images/animation-debian-vnc-xfce-chromium-g3.gif
 
 [accetto-dockerhub-ubuntu-vnc-xfce-chromium-g3]: https://hub.docker.com/r/accetto/ubuntu-vnc-xfce-chromium-g3
 
 [sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki
 
-<!-- Previous generations -->
+[sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions
 
 [accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/
-[accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce
-[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess
 
-<!-- External links -->
+[accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce
 
 [docker-debian]: https://hub.docker.com/_/debian/
 [docker-ubuntu]: https://hub.docker.com/_/ubuntu/
 
-<!-- [docker-doc]: https://docs.docker.com/ -->
-<!-- [docker-doc-managing-data]: https://docs.docker.com/storage/ -->
-
-[debian-packages-search]: https://packages.debian.org/index
-
+[chromium]: https://www.chromium.org/Home
 [jq]: https://stedolan.github.io/jq/
 [mousepad]: https://github.com/codebrainz/mousepad
 [nano]: https://www.nano-editor.org/
 [novnc]: https://github.com/kanaka/noVNC
+[sudo]: https://www.sudo.ws/
 [tigervnc]: http://tigervnc.org
 [tini]: https://github.com/krallin/tini
 [xfce]: http://www.xfce.org
 
-[chromium]: https://www.chromium.org/Home
-
-<!-- github badges common -->
-
 [badge-github-release]: https://badgen.net/github/release/accetto/debian-vnc-xfce-g3?icon=github&label=release
 
-[badge-github-release-date]: https://img.shields.io/github/release-date/accetto/debian-vnc-xfce-g3?logo=github
-
-<!-- docker badges specific -->
-
 [badge-docker-pulls]: https://badgen.net/docker/pulls/accetto/debian-vnc-xfce-chromium-g3?icon=docker&label=pulls
 
 [badge-docker-stars]: https://badgen.net/docker/stars/accetto/debian-vnc-xfce-chromium-g3?icon=docker&label=stars
 
-<!-- Appendix -->
+<!-- Appendix will be added by util-readme.sh -->

docker/xfce-chromium/README.md

@@ -2,91 +2,15 @@
 
 ## accetto/debian-vnc-xfce-chromium-g3
 
-[Docker Hub][this-docker] - [Git Hub][this-github] - [Dockerfile][this-dockerfile] - [Docker Readme][this-readme-dockerhub] - [Changelog][this-changelog] - [Project Readme][this-readme-project]
-
-![badge-docker-pulls][badge-docker-pulls]
-![badge-docker-stars][badge-docker-stars]
-![badge-github-release][badge-github-release]
-![badge-github-release-date][badge-github-release-date]
+[User Guide][this-user-guide] - [Docker Hub][this-docker] - [Dockerfile][this-dockerfile] - [Readme][this-readme] - [Changelog][this-changelog]
 
 ***
 
-- [Headless Debian/Xfce container with VNC/noVNC and Chromium Browser](#headless-debianxfce-container-with-vncnovnc-and-chromium-browser)
-  - [accetto/debian-vnc-xfce-chromium-g3](#accettodebian-vnc-xfce-chromium-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)
-    - [Description](#description)
-    - [Image tags](#image-tags)
-    - [Ports](#ports)
-    - [Volumes](#volumes)
-    - [Version sticker](#version-sticker)
-  - [Using headless containers](#using-headless-containers)
-    - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters)
-  - [Container user account](#container-user-account)
-    - [Overriding container user parameters](#overriding-container-user-parameters)
-      - [Overriding user parameters in build-time](#overriding-user-parameters-in-build-time)
-      - [Overriding user parameters in run-time](#overriding-user-parameters-in-run-time)
-      - [User permissions and ownership](#user-permissions-and-ownership)
-      - [Other considerations](#other-considerations)
-  - [Running containers in background (detached)](#running-containers-in-background-detached)
-  - [Running containers in foreground (interactively)](#running-containers-in-foreground-interactively)
-  - [Startup options and help](#startup-options-and-help)
-  - [Issues, Wiki and Discussions](#issues-wiki-and-discussions)
-  - [Credits](#credits)
-  - [Diagrams](#diagrams)
-    - [Dockerfile.xfce](#dockerfilexfce)
+This GitHub project folder contains resources used by building Debian images available on Docker Hub in the repository [accetto/debian-vnc-xfce-chromium-g3][this-docker].
 
-***
+This [User guide][this-user-guide] describes the images and how to use them.
 
-### 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 and the current [Chromium][chromium] web browser.
-
-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
-
-#### Installing packages
-
-I try to keep the images slim. Consequently you can 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.
-
-You can also try to fix it by executing the following (the default `sudo` password is **headless**):
-
-```shell
-### apt cache needs to be updated only once
-sudo apt-get update
-
-sudo apt --fix-broken install
-```
-
-#### Shared memory size
-
-Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior.
-
-You can check the current shared memory size by executing the following command inside the container:
-
-```shell
-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
-
-The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images.
-
-Your concrete `Dockerfile` may need more statements, but the concept should be clear.
-
-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
-
-The fastest way to build the images:
+### Building images
 
 ```shell
 ### PWD = project root
@@ -102,573 +26,66 @@ 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 [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information.
+Refer to the main [README][this-readme] file for more information about the building subject.
 
-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.
+### Remarks
 
-#### Sharing devices
+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].
 
-Sharing the audio device for video with sound works only with `Chromium` and only on Linux:
+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].
 
-```shell
-docker run -it -P --rm \
-  --device /dev/snd:/dev/snd:rw \
-  --group-add audio \
-accetto/debian-vnc-xfce-chromium-g3:latest
-```
+The [Chromium Browser][chromium] in these images runs in the `--no-sandbox` mode.
+You should be aware of the implications.
+The images are intended for testing and development.
 
-Sharing the display with the host works only on Linux:
+### Getting help
 
-```shell
-xhost +local:$(whoami)
+If you've found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and [sibling Wiki][sibling-wiki] first.
+Please do not overlook the closed issues.
 
-docker run -it -P --rm \
-    -e DISPLAY=${DISPLAY} \
-    --device /dev/dri/card0 \
-    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
-    accetto/debian-vnc-xfce-chromium-g3:latest --skip-vnc
+If you do not find a solution, you can file a new issue.
+The better you describe the problem, the bigger the chance it'll be solved soon.
 
-xhost -local:$(whoami)
-```
+If you have a question or an idea and you don't want to open an issue, you can also use the [sibling Discussions][sibling-discussions].
 
-Sharing the X11 socket with the host works only on Linux:
+### Diagrams
 
-```shell
-xhost +local:$(whoami)
+Diagram of the multi-staged Dockerfile used for building multiple images.
 
-docker run -it -P --rm \
-    --device /dev/dri/card0 \
-    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
-    accetto/debian-vnc-xfce-chromium-g3:latest
+The actual content of a particular image build is controlled by the *feature variables*.
 
-xhost -local:$(whoami)
-```
-
-### Description
-
-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].
-
-**Attention:** The [Chromium Browser][chromium] in these images runs in the `--no-sandbox` mode. You should be aware of the implications. The image is intended for testing and development.
-
-The main features and components of the images in the default configuration are:
-
-- utilities **ping**, **wget**, **sudo** (Debian distribution)
-- current version of JSON processor [jq][jq]
-- light-weight [Xfce][xfce] desktop environment (Debian distribution)
-- current version of high-performance [TigerVNC][tigervnc] server and client
-- current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**)
-- popular text editor [nano][nano] (Debian distribution)
-- lite but advanced graphical editor [mousepad][mousepad] (Debian distribution)
-- 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 [Chromium Browser][chromium] open-source web browser (Debian distribution)
-
-The history of notable changes is documented in the [CHANGELOG][this-changelog].
-
-![container-screenshot][this-screenshot-container]
-
-### Image tags
-
-The following image tags are regularly built and published on the **Docker Hub**:
-
-- `latest` based on `Debian 11`
-
-Clicking on the version sticker badge in the [README on Docker Hub][this-readme-dockerhub] reveals more information about the actual configuration of the image.
-
-### Ports
-
-Following **TCP** ports are exposed by default:
-
-- **5901** is used for access over **VNC**
-- **6901** is used for access over [noVNC][novnc]
-
-These default ports and also some other parameters can be overridden several ways (see bellow).
-
-### Volumes
-
-The containers do not create or use any external volumes by default.
-
-Both **named volumes** and **bind mounts** can be used. More about volumes can be found in [Docker documentation][docker-doc] (e.g. [Manage data in Docker][docker-doc-managing-data]).
-
-### Version sticker
-
-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.
-
-The **verbose version sticker value** is used by the CI builder to decide if the image needs to be refreshed. It describes the actual configuration of the essential components of the image. It can be revealed by clicking on the version sticker badge in the README file.
-
-The version sticker values are generated by the script `version_sticker.sh`, which is deployed into the startup directory `/dockerstartup`. The script will show a short help if executed with the argument `-h`. There is also a convenient `Version Sticker` launcher on the container desktop.
-
-## Using headless containers
-
-There are two ways, how to use the containers created from this image.
-
-All containers are accessible by a VNC viewer (e.g. [TigerVNC][tigervnc] or [TightVNC][tightvnc]).
-
-The default `VNC_PORT` value is `5901`. The default `DISPLAY` value is `:1`. The default VNC password (`VNC_PW`) is `headless`.
-
-The containers that are created from the images built with the **noVNC feature** can be also accessed over [noVNC][noVNC] by any web browser supporting HTML5.
-
-The default `NOVNC_PORT` value is `6901`. The noVNC password is always identical to the VNC password.
-
-There are several ways of connecting to headless containers and the possibilities also differ between the Linux and Windows environments, but usually it is done by mapping the VNC/noVNC ports exposed by the container to some free TCP ports on its host system.
-
-For example, the following command would map the VNC/noVNC ports `5901/6901` of the container to the TCP ports `25901/26901` on the host:
-
-```shell
-docker run -p 25901:5901 -p 26901:6901 ...
-```
-
-If the container would run on the local computer, then it would be accessible over **VNC** as `localhost:25901` and over **noVNC** as `http://localhost:26901`.
-
-If it would run on the remote server  `mynas`, then it would be accessible over **VNC** as `mynas:25901` and over **noVNC** as `http://mynas:26901`.
-
-The image offers two [noVNC][novnc] clients - **lite client** and **full client**. Because the connection URL differs slightly in both cases, the container provides a **simple startup page**.
-
-The startup page offers two hyperlinks for both noVNC clients:
-
-- **noVNC Lite Client** (`http://mynas:26901/vnc_lite.html`)
-- **noVNC Full Client** (`http://mynas:26901/vnc.html`)
-
-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 VNC/noVNC parameters
-
-The VNC/noVNC parameters are controlled by related environment variables embedded into the image.
-
-They have the following default values:
-
-```shell
-DISPLAY=:1
-NOVNC_PORT=6901
-VNC_COL_DEPTH=24
-VNC_PORT=5901
-VNC_PW=headless
-VNC_RESOLUTION=1360x768
-VNC_VIEW_ONLY=false
-```
-
-These environment variables can be overridden several ways.
-
-**At image build-time** you can embed different default values by using the following build arguments:
-
-- `ARG_VNC_PW` sets the variable `VNC_PW` (VNV/noVNC password)
-- `ARG_VNC_DISPLAY` sets the variable `DISPLAY`
-- `ARG_VNC_PORT` sets the variable `VNC_PORT`
-- `ARG_VNC_RESOLUTION` sets the variable `VNC_RESOLUTION`
-- `ARG_VNC_COL_DEPTH` sets the variable `VNC_COL_DEPTH`
-- `ARG_VNC_VIEW_ONLY` set the variable `VNC_VIEW_ONLY`
-- `ARG_NOVNC_PORT` sets the variable `NOVNC_PORT`
-
-For example:
-
-```shell
-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`).
-
-For example:
-
-```shell
-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).
-
-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
-```
-
-The content of the file should be similar to the provided example file `example-vnc-override.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
-export VNC_RESOLUTION=1024x768
-export DISPLAY=:2
-export VNC_PORT=5902
-export NOVNC_PORT=6902
-;export NOVNC_HEARTBEAT=25
-```
-
-Please note that only the lines beginning with `export` at the first position will be imported.
-
-By providing the variable values the following rules apply:
-
-- The value of `ARG_VNC_DISPLAY/VNC_DISPLAY` should include also the leading colon (e.g. `:1`).
-- The value of `ARG_VNC_PW/VNC_PW` can be empty. It effectively disables the VNC/noVNC password.
-
-If you want to check, what parameter values have been actually applied, then you can start the container with the parameter `--debug`.
-
-For example:
-
-```shell
-docker run -it -P --rm accetto/debian-vnc-xfce-g3:latest --debug
-
-### output (excerpt)
-VNC server started on display ':1' and TCP port '5901'
-Connect via VNC viewer with 172.17.0.3:5901
-noVNC started on TCP port '6901'
-```
-
-You should be aware, that overriding the VNC/noVNC parameters incorrectly could prevent the container from starting.
-
-This feature assumes some preliminary knowledge and it is provided for advanced users that already know what they want to achieve.
-
-For example, by default there is a relation between the `DISPLAY` and `VNC_PORT` values. Generally the convention `VNC_PORT = 5900 + DISPLAY` is followed (similarly `NOVNC_PORT = 6900 + DISPLAY`).
-
-You may decide not to follow the conventions. This image allows you to set the parameters differently, but again, you should know, what you are doing.
-
-Be also aware, that there are differences between the Linux and Windows environments.
-
-If your session disconnects, it might be related to a network equipment (load-balancer, reverse proxy, ...) dropping the websocket session for inactivity (more info [here](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) and [here](https://nginx.org/en/docs/http/websocket.html) for nginx). In such case, try defining the **NOVNC_HEARTBEAT=XX** environment variable at startup-time, where **XX** is the number of seconds between [websocket ping/pong](https://github.com/websockets/ws/issues/977) packets.
-
-## Container user account
-
-Containers created from this image run under the **application user** (by default `headless:headless`, `1000:1000`), which is a **non-root** user account. However, the application user gets permissions for `sudo`.
-
-The **application user name** also defines the **home directory name**, which is by default `/home/headless`.
-
-The default application user's password is `headless`, which is also the default `sudo` password.
-
-The user's (and `sudo`) password can be changed inside the container by using the `passwd` command. For example, changing the password to `docker`:
-
-```shell
-echo 'headless:docker' | sudo chpasswd
-
-### or also
-sudo chpasswd <<<"headless:docker"
-```
-
-The `sudo` command allows user elevation, so the **application user** can install additional software inside the container.
-
-The following example shows how to install **vim**:
-
-```shell
-sudo apt-get update
-sudo apt-get install -y vim
-```
-
-### Overriding container user parameters
-
-The user ID, user name, user group ID, user group name and the initial `sudo` password can be overridden during the build time (`docker build`).
-
-The user ID and the group ID can be overridden also in run time (`docker run`).
-
-#### Overriding user parameters in build-time
-
-The build parameters `ARG_HEADLESS_USER_ID`, `ARG_HEADLESS_USER_NAME`, `ARG_HEADLESS_USER_GROUP_ID` and `ARG_HEADLESS_USER_GROUP_NAME` are used during the build time (`docker build`) and they allow to override the related container parameters.
-
-Their values are persisted in the corresponding environment variables `HEADLESS_USER_ID`, `HEADLESS_USER_NAME`, `HEADLESS_USER_GROUP_ID` and `HEADLESS_USER_GROUP_NAME`.
-
-The build argument `ARG_SUDO_INITIAL_PW` allows overriding the initial application user's and `sudo` password (which is `headless`). This initial password is not stored into any environment variable, but into a temporary file, which is removed on the first container start. The password can be changed inside the container.
-
-For example, building an image with the application user name `hairless`, with the primary user group `hairygroup`, the IDs `2002:3003` and the initial password `docker`:
-
-```shell
-docker build --build-arg ARG_HEADLESS_USER_NAME=hairless --build-arg ARG_HEADLESS_USER_GROUP_NAME=hairygroup --build-arg ARG_HEADLESS_USER_ID=2002 --build-arg ARG_HEADLESS_USER_GROUP_ID=3003 --build-arg ARG_SUDO_INITIAL_PW=docker ... -t my/image:overriden
-```
-
-#### Overriding user parameters in run-time
-
-Both the user ID and group ID can be overridden also in the run time (`docker run`). It does not apply to the application user name, the group name and the initial password.
-
-For example, this would override the `user:group` by `2000:3000`:
-
-```shell
-docker run --user 2000:3000 ... my/image:overriden
-```
-
-#### User permissions and ownership
-
-The actual application user account and the user group are created by the startup script on the first container start.
-
-During this one-time task the startup script needs to modify the container files `/etc/passwd` and `/etc/group`. That is why there is the line `chmod 666 /etc/passwd /etc/group` in the Dockerfile (see the `stage_final`). However, the permissions of these two files will be set to the standard value `644` just after creating the user.
-
-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.
-
-There is the script `~/tests/test-01.sh` that allows quick check of the current permissions.
-
-#### Other considerations
-
-Please note that the described configuration will not be done if the startup script `startup.sh` will not be executed.
-
-Also do not confuse the application user's password with the **VNC password**, because they both have the same default value (`headless`).
-
-## Running containers in background (detached)
-
-The following container will keep running in the background and it will listen on an automatically selected TCP port on the host computer:
-
-```shell
-docker run -d -P accetto/debian-vnc-xfce-chromium-g3:latest
-```
-
-The following container will listen on the host's TCP port **25901**:
-
-```shell
-docker run -d -p 25901:5901 accetto/debian-vnc-xfce-chromium-g3:latest
-```
-
-The following container will create (or re-use) the local named volume **my\_Downloads** mounted as `/home/headless/Downloads`:
-
-```shell
-docker run -d -P -v my_Downloads:/home/headless/Downloads accetto/debian-vnc-xfce-chromium-g3:latest
-```
-
-or using the newer syntax with **--mount** flag:
-
-```shell
-docker run -d -P --mount source=my_Downloads,target=/home/headless/Downloads accetto/debian-vnc-xfce-chromium-g3:latest
-```
-
-## Running containers in foreground (interactively)
-
-The following container can be used interactively:
-
-```shell
-docker run -it --rm accetto/debian-vnc-xfce-chromium-g3:latest bash
-```
-
-The opened `bash` session can be used as usual and then closed by entering `^C` (CTRL-C):
-
-```shell
-To run a command as administrator (user "root"), use "sudo <command>".
-See "man sudo_root" for details.
-
-headless@cf4a4e01d94b:~$ whoami
-headless
-headless@cf4a4e01d94b:~$ pwd
-/home/headless
-headless@cf4a4e01d94b:~$
-```
-
-The container will remove itself.
-
-## Startup options and help
-
-The image supports multiple **start-up options** and **start-up modifiers**. There also also two help modes.
-
-The following container will print out the short help and then it will remove itself:
-
-```shell
-docker run --rm accetto/debian-vnc-xfce-chromium-g3:latest --help
-```
-
-Example of the short help text:
-
-```text
-Container startup script
-Usage: /dockerstartup/startup.sh [-v|--version] [-h|--help] [-H|--help-usage] [--(no-)wait] [--(no-)skip-startup] [--(no-)tail-null] [--(no-)tail-vnc] [--(no-)version-sticker] [--(no-)version-sticker-verbose] [--(no-)skip-vnc] [--(no-)skip-novnc] [--(no-)debug] [--(no-)verbose] [--] [<command-1>] ... [<command-n>] ...
-        <command>: Optional command with optional arguments. It is executed during startup.
-        -v, --version: Prints version
-        -h, --help: Prints help
-        -H, --help-usage: Extended container usage help.
-        --wait, --no-wait: Default background execution mode (on by default)
-        --skip-startup, --no-skip-startup: Default foreground execution mode (off by default)
-        --tail-null, --no-tail-null: Alternative background execution mode (off by default)
-        --tail-vnc, --no-tail-vnc: Alternative background execution mode (off by default)
-        --version-sticker, --no-version-sticker: Alternative foreground execution mode (off by default)
-        --version-sticker-verbose, --no-version-sticker-verbose: Alternative foreground execution mode (off by default)
-        --skip-vnc, --no-skip-vnc: Startup process modifier (off by default)
-        --skip-novnc, --no-skip-novnc: Startup process modifier (off by default)
-        --debug, --no-debug: Startup process modifier (off by default)
-        --verbose, --no-verbose: Startup process modifier (off by default)
-
-Use '-H' or '--help-usage' for extended container usage help.
-For more information visit https://github.com/accetto/debian-vnc-xfce-g3
-```
-
-The following container will print out the long help and then it will remove itself:
-
-```shell
-docker run --rm accetto/debian-vnc-xfce-chromium-g3:latest --help-usage
-```
-
-Example of the long help text:
-
-```text
-CONTAINER USAGE:
-docker run [<docker-run-options>] accetto/<image>:<tag> [<startup-options>] [<command>]
-
-POSITIONAL ARGUMENTS:
-command
-    Optional command with optional arguments.
-    It will be executed during startup before going waiting, tailing or asleep.
-    It is necessary to use the quotes correctly or the 'bash -c "<command>"' pattern.
-
-STARTUP OPTIONS:
-
---wait, or no options, or unknown option, or empty input
-    Default background execution mode.
-    Starts the VNC and noVNC servers, if available, then executes the command
-    and waits until the VNC server process exits or goes asleep infinitely.
-    Container keeps running in the background.
-
---skip-startup
-    Default foreground execution mode.
-    Skips the startup procedure, executes the command and exits.
-    Be aware that the container user generator will be also skipped.
-    Container does not keep running in the background.
-
---tail-null
-    Alternative background execution mode.
-    Similar to '--wait', but tails the null device instead of going asleep.
-    Container keeps running in the background.
-
---tail-vnc
-    Alternative background execution mode.
-    Similar to '--wait', but tails the VNC log instead of waiting until the VNC process exits.
-    Falls back to '--tail-null' if the VNC server has not been started.
-    Container keeps running in the background.
-
---version-sticker
-    Alternative foreground execution mode.
-    Prints out the version sticker info.
-    The VNC server is also started by default, if available, because some applications
-    need a display to report their versions correctly. It can be suppressed by providing
-    also '--skip-vnc'. The '--skip-novnc' option is always enforced automatically.
-    Container does not keep running in the background.
-
---version-sticker-verbose
-    Alternative foreground execution mode.
-    Similar to '--version-sticker', but prints out the verbose version sticker info and features list.
-    Container does not keep running in the background.
-
---skip-vnc
-    Startup process modifier.
-    If VNC and noVNC startup should be skipped.
-    It also enforces '--skip-novnc'.
-
---skip-novnc
-    Startup process modifier.
-    If noVNC startup should be skipped.
-    It is also enforced by '--skip-vnc'.
-
---debug
-    Startup process modifier.
-    If additional debugging info should be displayed during startup.
-    It also enforces option '--verbose'.
-
---verbose
-    Startup process modifier.
-    If startup progress messages should be displayed.
-    It is also enforced by '--debug'.
-
---help-usage, -H
-    Prints out this extended container usage help and exits.
-    The rest of the input is ignored.
-
---help, -h
-    Prints out the short startup script help and exits.
-    The rest of the input is ignored.
-
---version, -v
-    Prints out the version of the startup script and exits.
-    The rest of the input is ignored.
-
-Use '-h' or '--help' for short startup script help.
-Fore more information visit https://github.com/accetto/debian-vnc-xfce-g3
-```
-
-## Issues, Wiki and Discussions
-
-If you have found a problem or you just have a question, please check the [Issues][this-issues] and the [sibling Wiki][sibling-wiki] first. Please do not overlook the closed issues.
-
-If you do not find a solution, you can file a new issue. The better you describe the problem, the bigger the chance it'll be solved soon.
-
-If you have a question or an idea and you don't want to open an issue, you can use the [sibling Discussions][sibling-discussions].
-
-## Credits
-
-Credit goes to all the countless people and companies, who contribute to open source community and make so many dreamy things real.
-
-## Diagrams
-
-The stage diagram doesn't differ from the [sibling project][accetto-github-ubuntu-vnc-xfce-g3].
-
-### Dockerfile.xfce
+The stage diagram doesn't differ from the sibling project [accetto/github-ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3].
 
 ![Dockerfile.xfce stages][sibling-diagram-dockerfile-stages]
 
 ***
 
-<!-- GitHub project common -->
+[this-user-guide]: https://accetto.github.io/user-guide-g3/
+
+[this-readme]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/README.md
 
 [this-changelog]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/CHANGELOG.md
-[this-github]: https://github.com/accetto/debian-vnc-xfce-g3/
+
 [this-issues]: https://github.com/accetto/debian-vnc-xfce-g3/issues
-[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 -->
 
 [this-docker]: https://hub.docker.com/r/accetto/debian-vnc-xfce-chromium-g3/
+
 [this-dockerfile]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/docker/Dockerfile.xfce
 
-[this-screenshot-container]: https://raw.githubusercontent.com/accetto/debian-vnc-xfce-g3/master/docker/doc/images/debian-vnc-xfce-chromium.jpg
-
-<!-- Sibling projects -->
-
 [accetto-github-ubuntu-vnc-xfce-g3]: https://github.com/accetto/ubuntu-vnc-xfce-g3
 
 [sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki
+
 [sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions
 
 [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/
+
 [accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce
 
-[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess
-
-<!-- External links -->
-
-[docker-debian]: https://hub.docker.com/_/debian/
 [docker-ubuntu]: https://hub.docker.com/_/ubuntu/
 
-[docker-doc]: https://docs.docker.com/
-[docker-doc-managing-data]: https://docs.docker.com/storage/
-
-[debian-packages-search]: https://packages.debian.org/index
-
-[jq]: https://stedolan.github.io/jq/
-[mousepad]: https://github.com/codebrainz/mousepad
-[nano]: https://www.nano-editor.org/
-[novnc]: https://github.com/kanaka/noVNC
-[tigervnc]: http://tigervnc.org
-[tightvnc]: http://www.tightvnc.com
-[tini]: https://github.com/krallin/tini
-[xfce]: http://www.xfce.org
-
 [chromium]: https://www.chromium.org/Home
-
-<!-- github badges common -->
-
-[badge-github-release]: https://badgen.net/github/release/accetto/debian-vnc-xfce-g3?icon=github&label=release
-
-[badge-github-release-date]: https://img.shields.io/github/release-date/accetto/debian-vnc-xfce-g3?logo=github
-
-<!-- docker badges specific -->
-
-[badge-docker-pulls]: https://badgen.net/docker/pulls/accetto/debian-vnc-xfce-chromium-g3?icon=docker&label=pulls
-
-[badge-docker-stars]: https://badgen.net/docker/stars/accetto/debian-vnc-xfce-chromium-g3?icon=docker&label=stars

docker/xfce-chromium/readme-append.template

@@ -8,3 +8,11 @@
 [badge_latest_version-sticker]: https://badgen.net/https/gist.githubusercontent.com/${OWNER}/${GIST}/raw/${REPO}@latest@version-sticker.json
 
 [link_latest_version-sticker-verbose]: https://gist.githubusercontent.com/${OWNER}/${GIST}/raw/${REPO}@latest@version-sticker-verbose.txt
+
+<!-- 11 -->
+
+[badge_11_created]: https://badgen.net/https/gist.githubusercontent.com/${OWNER}/${GIST}/raw/${REPO}@11@created.json
+
+[badge_11_version-sticker]: https://badgen.net/https/gist.githubusercontent.com/${OWNER}/${GIST}/raw/${REPO}@11@version-sticker.json
+
+[link_11_version-sticker-verbose]: https://gist.githubusercontent.com/${OWNER}/${GIST}/raw/${REPO}@11@version-sticker-verbose.txt

docker/xfce-firefox/README-dockerhub.md

@@ -2,231 +2,133 @@
 
 ## accetto/debian-vnc-xfce-firefox-g3
 
-[Docker Hub][this-docker] - [Git Hub][this-github] - [Dockerfile][this-dockerfile] - [Full Readme][this-readme-full] - [Changelog][this-changelog] - [Project Readme][this-readme-project]
+[User Guide][this-user-guide] - [GitHub][this-github] - [Dockerfile][this-dockerfile] - [Readme][this-readme-full] - [Changelog][this-changelog]
 
 ![badge-docker-pulls][badge-docker-pulls]
 ![badge-docker-stars][badge-docker-stars]
 ![badge-github-release][badge-github-release]
-![badge-github-release-date][badge-github-release-date]
 
 ***
 
-- [Headless Debian/Xfce container with VNC/noVNC and Firefox browser](#headless-debianxfce-container-with-vncnovnc-and-firefox-browser)
-  - [accetto/debian-vnc-xfce-firefox-g3](#accettodebian-vnc-xfce-firefox-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)
-    - [Description](#description)
-    - [Image tags](#image-tags)
-    - [More information](#more-information)
+This Docker Hub repository contains Docker images for headless working.
 
-***
+The images are based on the current [Debian 12][docker-debian] and the previous [Debian 11][docker-debian] and include [Xfce][xfce] desktop, [TigerVNC][tigervnc] server and [noVNC][novnc] client.
+The popular web browser [Firefox][firefox] is also included.
 
-**Warning** about the images with Firefox
+This [User guide][this-user-guide] describes the images and how to use them.
 
-There is no single-process Firefox image in this repository any more and the **multi-process mode** is always enabled. Be aware, that the multi-process mode requires larger shared memory (`/dev/shm`). At least 256MB is recommended. Please check the **Firefox multi-process** page in this older sibling [Wiki][that-wiki-firefox-multiprocess] for more information and the instructions, how to set the shared memory size in different scenarios.
+The related [GitHub project][this-github] contains image generators that image users generally don’t need, unless they want to build the images themselves.
 
-***
+### Tags
 
-### Introduction
+The following image tags are regularly built and published on Docker Hub:
 
-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.
+<!-- markdownlint-disable MD052 -->
 
-There is also a similar sibling image [accetto/ubuntu-vnc-xfce-firefox-g3][accetto-dockerhub-ubuntu-vnc-xfce-firefox-g3] based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu].
+- `latest` (also as `12`) based on `Debian 12`
 
-This is the **short README** version for the **Docker Hub**. There is also the [full-length README][this-readme-full] on the **GitHub**.
+    ![badge_latest_created][badge_latest_created]
+    [![badge_latest_version-sticker][badge_latest_version-sticker]][link_latest_version-sticker-verbose]
 
-### TL;DR
+- `11` based on `Debian 11`
 
-#### Installing packages
+    ![badge_11_created][badge_11_created]
+    [![badge_11_version-sticker][badge_11_version-sticker]][link_11_version-sticker-verbose]
 
-I try to keep the images slim. Consequently you can 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.
+<!-- markdownlint-enable MD052 -->
 
-You can also try to fix it by executing the following (the default `sudo` password is **headless**):
+**Hint:** Clicking the version sticker badge reveals more information about the particular build.
 
-```shell
-### apt cache needs to be updated only once
-sudo apt-get update
-
-sudo apt --fix-broken install
-```
-
-#### Shared memory size
-
-Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior.
-
-You can check the current shared memory size by executing the following command inside the container:
-
-```shell
-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
-
-The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images.
-
-Your concrete `Dockerfile` may need more statements, but the concept should be clear.
-
-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
-
-The fastest way to build the images:
-
-```shell
-### PWD = project root
-### prepare and source the 'secrets.rc' file first (see 'example-secrets.rc')
-
-### examples of building and publishing the individual images 
-./builder.sh latest-firefox all
-
-### just building an image, skipping the publishing and the version sticker update
-./builder.sh latest-firefox build
-
-### examples of building and publishing the images as a group
-./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 [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 the [local-building-example][this-readme-local-building-example] for more information.
-
-#### Sharing devices
-
-Sharing the display with the host works only on Linux:
-
-```shell
-xhost +local:$(whoami)
-
-docker run -it -P --rm \
-    -e DISPLAY=${DISPLAY} \
-    --device /dev/dri/card0 \
-    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
-    accetto/debian-vnc-xfce-firefox-g3:latest --skip-vnc
-
-xhost -local:$(whoami)
-```
-
-Sharing the X11 socket with the host works only on Linux:
-
-```shell
-xhost +local:$(whoami)
-
-docker run -it -P --rm \
-    --device /dev/dri/card0 \
-    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
-    accetto/debian-vnc-xfce-firefox-g3:latest
-
-xhost -local:$(whoami)
-```
-
-### Description
-
-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].
+### Features
 
 The main features and components of the images in the default configuration are:
 
-- utilities **ping**, **wget**, **sudo** (Debian distribution)
+- lightweight [Xfce][xfce] desktop environment (Debian distribution)
+- [sudo][sudo] support
 - current version of JSON processor [jq][jq]
-- light-weight [Xfce][xfce] desktop environment (Debian distribution)
 - current version of high-performance [TigerVNC][tigervnc] server and client
 - current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**)
 - popular text editor [nano][nano] (Debian distribution)
 - lite but advanced graphical editor [mousepad][mousepad] (Debian distribution)
 - 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 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
+- support for overriding environment variables, VNC parameters, user and group (see [User guide][this-user-guide-using-containers])
+- support of **version sticker** (see [User guide][this-user-guide-version-sticker])
+- current version of [Firefox ESR (Extended Support Release)][firefox] web browser and also the additional **Firefox plus** feature (see [User guide][this-user-guide-firefox-plus])
 
-The history of notable changes is documented in the [CHANGELOG][this-changelog].
+The following **TCP** ports are exposed by default:
+
+- **5901** for access over **VNC** (using VNC viewer)
+- **6901** for access over [noVNC][novnc] (using web browser)
 
 ![container-screenshot][this-screenshot-container]
 
-### Image tags
+### Remarks
 
-The following image tags are regularly built and published on the **Docker Hub**:
+There is also a similar sibling image [accetto/ubuntu-vnc-xfce-firefox-g3][accetto-dockerhub-ubuntu-vnc-xfce-firefox-g3] based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu].
 
-- `latest` based on `Debian 11`
+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].
 
-    ![badge_latest_created][badge_latest_created]
-    [![badge_latest_version-sticker][badge_latest_version-sticker]][link_latest_version-sticker-verbose]
+### Getting help
 
-Clicking on the version sticker badge reveals more information about the actual configuration of the image.
+If you've found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and [sibling Wiki][sibling-wiki] first.
+Please do not overlook the closed issues.
 
-### More information
+If you do not find a solution, you can file a new issue.
+The better you describe the problem, the bigger the chance it'll be solved soon.
 
-More information about these images can be found in the [full-length README][this-readme-full] file on the GitHub.
+If you have a question or an idea and you don't want to open an issue, you can also use the [sibling Discussions][sibling-discussions].
 
 ***
 
-<!-- GitHub project common -->
+[this-user-guide]: https://accetto.github.io/user-guide-g3/
+
+[this-user-guide-version-sticker]: https://accetto.github.io/user-guide-g3/version-sticker/
+
+[this-user-guide-using-containers]: https://accetto.github.io/user-guide-g3/using-containers/
+
+[this-user-guide-firefox-plus]: https://accetto.github.io/user-guide-g3/firefox-plus/
 
 [this-changelog]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/CHANGELOG.md
+
 [this-github]: https://github.com/accetto/debian-vnc-xfce-g3/
-<!-- [this-issues]: https://github.com/accetto/debian-vnc-xfce-g3/issues -->
+
 [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
+[this-issues]: https://github.com/accetto/debian-vnc-xfce-g3/issues
 
-<!-- Docker image specific -->
-
-[this-docker]: https://hub.docker.com/r/accetto/debian-vnc-xfce-firefox-g3/
 [this-dockerfile]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/docker/Dockerfile.xfce
 
-[this-screenshot-container]: https://raw.githubusercontent.com/accetto/debian-vnc-xfce-g3/master/docker/doc/images/debian-vnc-xfce-firefox-plus.jpg
-
-<!-- Sibling projects -->
+[this-screenshot-container]: https://raw.githubusercontent.com/accetto/debian-vnc-xfce-g3/master/docker/doc/images/animation-debian-vnc-xfce-firefox-g3.gif
 
 [accetto-dockerhub-ubuntu-vnc-xfce-firefox-g3]: https://hub.docker.com/r/accetto/ubuntu-vnc-xfce-firefox-g3
 
 [sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki
 
-<!-- Previous generations -->
+[sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions
 
 [accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/
+
 [accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce
 
-[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess
-
-<!-- External links -->
-
 [docker-debian]: https://hub.docker.com/_/debian/
 [docker-ubuntu]: https://hub.docker.com/_/ubuntu/
 
-<!-- [docker-doc]: https://docs.docker.com/ -->
-<!-- [docker-doc-managing-data]: https://docs.docker.com/storage/ -->
-
-[debian-packages-search]: https://packages.debian.org/index
-
+[firefox]: https://www.mozilla.org
 [jq]: https://stedolan.github.io/jq/
 [mousepad]: https://github.com/codebrainz/mousepad
 [nano]: https://www.nano-editor.org/
 [novnc]: https://github.com/kanaka/noVNC
+[sudo]: https://www.sudo.ws/
 [tigervnc]: http://tigervnc.org
 [tini]: https://github.com/krallin/tini
 [xfce]: http://www.xfce.org
 
-[firefox]: https://www.mozilla.org
-<!-- [firefox-doc-preferences]: https://developer.mozilla.org/en-US/docs/Mozilla/Preferences/A_brief_guide_to_Mozilla_preferences -->
-
-<!-- github badges common -->
-
 [badge-github-release]: https://badgen.net/github/release/accetto/debian-vnc-xfce-g3?icon=github&label=release
 
-[badge-github-release-date]: https://img.shields.io/github/release-date/accetto/debian-vnc-xfce-g3?logo=github
-
-<!-- docker badges specific -->
-
 [badge-docker-pulls]: https://badgen.net/docker/pulls/accetto/debian-vnc-xfce-firefox-g3?icon=docker&label=pulls
 
 [badge-docker-stars]: https://badgen.net/docker/stars/accetto/debian-vnc-xfce-firefox-g3?icon=docker&label=stars
 
-<!-- Appendix -->
+<!-- Appendix will be added by util-readme.sh -->

docker/xfce-firefox/README.md

@@ -2,100 +2,15 @@
 
 ## accetto/debian-vnc-xfce-firefox-g3
 
-[Docker Hub][this-docker] - [Git Hub][this-github] - [Dockerfile][this-dockerfile] - [Docker Readme][this-readme-dockerhub] - [Changelog][this-changelog] - [Project Readme][this-readme-project]
-
-![badge-docker-pulls][badge-docker-pulls]
-![badge-docker-stars][badge-docker-stars]
-![badge-github-release][badge-github-release]
-![badge-github-release-date][badge-github-release-date]
+[User Guide][this-user-guide] - [Docker Hub][this-docker] - [Dockerfile][this-dockerfile] - [Readme][this-readme] - [Changelog][this-changelog]
 
 ***
 
-- [Headless Debian/Xfce container with VNC/noVNC and Firefox browser](#headless-debianxfce-container-with-vncnovnc-and-firefox-browser)
-  - [accetto/debian-vnc-xfce-firefox-g3](#accettodebian-vnc-xfce-firefox-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)
-    - [Description](#description)
-    - [Image tags](#image-tags)
-    - [Ports](#ports)
-    - [Volumes](#volumes)
-    - [Version sticker](#version-sticker)
-  - [Using headless containers](#using-headless-containers)
-    - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters)
-  - [Container user account](#container-user-account)
-    - [Overriding container user parameters](#overriding-container-user-parameters)
-      - [Overriding user parameters in build-time](#overriding-user-parameters-in-build-time)
-      - [Overriding user parameters in run-time](#overriding-user-parameters-in-run-time)
-      - [User permissions and ownership](#user-permissions-and-ownership)
-      - [Other considerations](#other-considerations)
-  - [Running containers in background (detached)](#running-containers-in-background-detached)
-  - [Running containers in foreground (interactively)](#running-containers-in-foreground-interactively)
-  - [Firefox multi-process](#firefox-multi-process)
-    - [Setting shared memory size](#setting-shared-memory-size)
-  - [Firefox preferences and the plus features](#firefox-preferences-and-the-plus-features)
-  - [Startup options and help](#startup-options-and-help)
-  - [Issues, Wiki and Discussions](#issues-wiki-and-discussions)
-  - [Credits](#credits)
-  - [Diagrams](#diagrams)
-    - [Dockerfile.xfce](#dockerfilexfce)
+This GitHub project folder contains resources used by building Debian images available on Docker Hub in the repository [accetto/debian-vnc-xfce-firefox-g3][this-docker].
 
-***
+This [User guide][this-user-guide] describes the images and how to use them.
 
-**Warning** about the images with Firefox
-
-There is no single-process Firefox image in this repository any more and the **multi-process mode** is always enabled. Be aware, that the multi-process mode requires larger shared memory (`/dev/shm`). At least 256MB is recommended. Please check the **Firefox multi-process** page in this older sibling [Wiki][that-wiki-firefox-multiprocess] for more information and the instructions, how to set the shared memory size in different scenarios.
-
-***
-
-### 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 and the current [Firefox][firefox] web browser.
-
-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
-
-#### Installing packages
-
-I try to keep the images slim. Consequently you can 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.
-
-You can also try to fix it by executing the following (the default `sudo` password is **headless**):
-
-```shell
-### apt cache needs to be updated only once
-sudo apt-get update
-
-sudo apt --fix-broken install
-```
-
-#### Shared memory size
-
-Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior.
-
-You can check the current shared memory size by executing the following command inside the container:
-
-```shell
-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
-
-The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images.
-
-Your concrete `Dockerfile` may need more statements, but the concept should be clear.
-
-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
-
-The fastest way to build the images:
+### Building images
 
 ```shell
 ### PWD = project root
@@ -111,621 +26,60 @@ 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 [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information.
+Refer to the main [README][this-readme] file for more information about the building subject.
 
-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.
+### Remarks
 
-#### Sharing devices
+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].
 
-Sharing the display with the host works only on Linux:
+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].
 
-```shell
-xhost +local:$(whoami)
+### Getting help
 
-docker run -it -P --rm \
-    -e DISPLAY=${DISPLAY} \
-    --device /dev/dri/card0 \
-    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
-    accetto/debian-vnc-xfce-firefox-g3:latest --skip-vnc
+If you've found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and [sibling Wiki][sibling-wiki] first.
+Please do not overlook the closed issues.
 
-xhost -local:$(whoami)
-```
+If you do not find a solution, you can file a new issue.
+The better you describe the problem, the bigger the chance it'll be solved soon.
 
-Sharing the X11 socket with the host works only on Linux:
+If you have a question or an idea and you don't want to open an issue, you can also use the [sibling Discussions][sibling-discussions].
 
-```shell
-xhost +local:$(whoami)
+### Diagrams
 
-docker run -it -P --rm \
-    --device /dev/dri/card0 \
-    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
-    accetto/debian-vnc-xfce-firefox-g3:latest
+Diagram of the multi-staged Dockerfile used for building multiple images.
 
-xhost -local:$(whoami)
-```
+The actual content of a particular image build is controlled by the *feature variables*.
 
-### Description
-
-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].
-
-The main features and components of the images in the default configuration are:
-
-- utilities **ping**, **wget**, **sudo** (Debian distribution)
-- current version of JSON processor [jq][jq]
-- light-weight [Xfce][xfce] desktop environment (Debian distribution)
-- current version of high-performance [TigerVNC][tigervnc] server and client
-- current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**)
-- popular text editor [nano][nano] (Debian distribution)
-- lite but advanced graphical editor [mousepad][mousepad] (Debian distribution)
-- 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 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].
-
-![container-screenshot][this-screenshot-container]
-
-### Image tags
-
-The following image tags are regularly built and published on the **Docker Hub**:
-
-- `latest` based on `Debian 11`
-
-Clicking on the version sticker badge in the [README on Docker Hub][this-readme-dockerhub] reveals more information about the actual configuration of the image.
-
-### Ports
-
-Following **TCP** ports are exposed by default:
-
-- **5901** is used for access over **VNC**
-- **6901** is used for access over [noVNC][novnc]
-
-These default ports and also some other parameters can be overridden several ways (see bellow).
-
-### Volumes
-
-The containers do not create or use any external volumes by default.
-
-Both **named volumes** and **bind mounts** can be used. More about volumes can be found in [Docker documentation][docker-doc] (e.g. [Manage data in Docker][docker-doc-managing-data]).
-
-### Version sticker
-
-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.
-
-The **verbose version sticker value** is used by the CI builder to decide if the image needs to be refreshed. It describes the actual configuration of the essential components of the image. It can be revealed by clicking on the version sticker badge in the README file.
-
-The version sticker values are generated by the script `version_sticker.sh`, which is deployed into the startup directory `/dockerstartup`. The script will show a short help if executed with the argument `-h`. There is also a convenient `Version Sticker` launcher on the container desktop.
-
-## Using headless containers
-
-There are two ways, how to use the containers created from this image.
-
-All containers are accessible by a VNC viewer (e.g. [TigerVNC][tigervnc] or [TightVNC][tightvnc]).
-
-The default `VNC_PORT` value is `5901`. The default `DISPLAY` value is `:1`. The default VNC password (`VNC_PW`) is `headless`.
-
-The containers that are created from the images built with the **noVNC feature** can be also accessed over [noVNC][noVNC] by any web browser supporting HTML5.
-
-The default `NOVNC_PORT` value is `6901`. The noVNC password is always identical to the VNC password.
-
-There are several ways of connecting to headless containers and the possibilities also differ between the Linux and Windows environments, but usually it is done by mapping the VNC/noVNC ports exposed by the container to some free TCP ports on its host system.
-
-For example, the following command would map the VNC/noVNC ports `5901/6901` of the container to the TCP ports `25901/26901` on the host:
-
-```shell
-docker run -p 25901:5901 -p 26901:6901 ...
-```
-
-If the container would run on the local computer, then it would be accessible over **VNC** as `localhost:25901` and over **noVNC** as `http://localhost:26901`.
-
-If it would run on the remote server  `mynas`, then it would be accessible over **VNC** as `mynas:25901` and over **noVNC** as `http://mynas:26901`.
-
-The image offers two [noVNC][novnc] clients - **lite client** and **full client**. Because the connection URL differs slightly in both cases, the container provides a **simple startup page**.
-
-The startup page offers two hyperlinks for both noVNC clients:
-
-- **noVNC Lite Client** (`http://mynas:26901/vnc_lite.html`)
-- **noVNC Full Client** (`http://mynas:26901/vnc.html`)
-
-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 VNC/noVNC parameters
-
-The VNC/noVNC parameters are controlled by related environment variables embedded into the image.
-
-They have the following default values:
-
-```shell
-DISPLAY=:1
-NOVNC_PORT=6901
-VNC_COL_DEPTH=24
-VNC_PORT=5901
-VNC_PW=headless
-VNC_RESOLUTION=1360x768
-VNC_VIEW_ONLY=false
-```
-
-These environment variables can be overridden several ways.
-
-**At image build-time** you can embed different default values by using the following build arguments:
-
-- `ARG_VNC_PW` sets the variable `VNC_PW` (VNV/noVNC password)
-- `ARG_VNC_DISPLAY` sets the variable `DISPLAY`
-- `ARG_VNC_PORT` sets the variable `VNC_PORT`
-- `ARG_VNC_RESOLUTION` sets the variable `VNC_RESOLUTION`
-- `ARG_VNC_COL_DEPTH` sets the variable `VNC_COL_DEPTH`
-- `ARG_VNC_VIEW_ONLY` set the variable `VNC_VIEW_ONLY`
-- `ARG_NOVNC_PORT` sets the variable `NOVNC_PORT`
-
-For example:
-
-```shell
-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`).
-
-For example:
-
-```shell
-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).
-
-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
-```
-
-The content of the file should be similar to the provided example file `example-vnc-override.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
-export VNC_RESOLUTION=1024x768
-export DISPLAY=:2
-export VNC_PORT=5902
-export NOVNC_PORT=6902
-;export NOVNC_HEARTBEAT=25
-```
-
-Please note that only the lines beginning with `export` at the first position will be imported.
-
-By providing the variable values the following rules apply:
-
-- The value of `ARG_VNC_DISPLAY/VNC_DISPLAY` should include also the leading colon (e.g. `:1`).
-- The value of `ARG_VNC_PW/VNC_PW` can be empty. It effectively disables the VNC/noVNC password.
-
-If you want to check, what parameter values have been actually applied, then you can start the container with the parameter `--debug`.
-
-For example:
-
-```shell
-docker run -it -P --rm accetto/debian-vnc-xfce-g3:latest --debug
-
-### output (excerpt)
-VNC server started on display ':1' and TCP port '5901'
-Connect via VNC viewer with 172.17.0.3:5901
-noVNC started on TCP port '6901'
-```
-
-You should be aware, that overriding the VNC/noVNC parameters incorrectly could prevent the container from starting.
-
-This feature assumes some preliminary knowledge and it is provided for advanced users that already know what they want to achieve.
-
-For example, by default there is a relation between the `DISPLAY` and `VNC_PORT` values. Generally the convention `VNC_PORT = 5900 + DISPLAY` is followed (similarly `NOVNC_PORT = 6900 + DISPLAY`).
-
-You may decide not to follow the conventions. This image allows you to set the parameters differently, but again, you should know, what you are doing.
-
-Be also aware, that there are differences between the Linux and Windows environments.
-
-If your session disconnects, it might be related to a network equipment (load-balancer, reverse proxy, ...) dropping the websocket session for inactivity (more info [here](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) and [here](https://nginx.org/en/docs/http/websocket.html) for nginx). In such case, try defining the **NOVNC_HEARTBEAT=XX** environment variable at startup-time, where **XX** is the number of seconds between [websocket ping/pong](https://github.com/websockets/ws/issues/977) packets.
-
-## Container user account
-
-Containers created from this image run under the **application user** (by default `headless:headless`, `1000:1000`), which is a **non-root** user account. However, the application user gets permissions for `sudo`.
-
-The **application user name** also defines the **home directory name**, which is by default `/home/headless`.
-
-The default application user's password is `headless`, which is also the default `sudo` password.
-
-The user's (and `sudo`) password can be changed inside the container by using the `passwd` command. For example, changing the password to `docker`:
-
-```shell
-echo 'headless:docker' | sudo chpasswd
-
-### or also
-sudo chpasswd <<<"headless:docker"
-```
-
-The `sudo` command allows user elevation, so the **application user** can install additional software inside the container.
-
-The following example shows how to install **vim**:
-
-```shell
-sudo apt-get update
-sudo apt-get install -y vim
-```
-
-### Overriding container user parameters
-
-The user ID, user name, user group ID, user group name and the initial `sudo` password can be overridden during the build time (`docker build`).
-
-The user ID and the group ID can be overridden also in run time (`docker run`).
-
-#### Overriding user parameters in build-time
-
-The build parameters `ARG_HEADLESS_USER_ID`, `ARG_HEADLESS_USER_NAME`, `ARG_HEADLESS_USER_GROUP_ID` and `ARG_HEADLESS_USER_GROUP_NAME` are used during the build time (`docker build`) and they allow to override the related container parameters.
-
-Their values are persisted in the corresponding environment variables `HEADLESS_USER_ID`, `HEADLESS_USER_NAME`, `HEADLESS_USER_GROUP_ID` and `HEADLESS_USER_GROUP_NAME`.
-
-The build argument `ARG_SUDO_INITIAL_PW` allows overriding the initial application user's and `sudo` password (which is `headless`). This initial password is not stored into any environment variable, but into a temporary file, which is removed on the first container start. The password can be changed inside the container.
-
-For example, building an image with the application user name `hairless`, with the primary user group `hairygroup`, the IDs `2002:3003` and the initial password `docker`:
-
-```shell
-docker build --build-arg ARG_HEADLESS_USER_NAME=hairless --build-arg ARG_HEADLESS_USER_GROUP_NAME=hairygroup --build-arg ARG_HEADLESS_USER_ID=2002 --build-arg ARG_HEADLESS_USER_GROUP_ID=3003 --build-arg ARG_SUDO_INITIAL_PW=docker ... -t my/image:overriden
-```
-
-#### Overriding user parameters in run-time
-
-Both the user ID and group ID can be overridden also in the run time (`docker run`). It does not apply to the application user name, the group name and the initial password.
-
-For example, this would override the `user:group` by `2000:3000`:
-
-```shell
-docker run --user 2000:3000 ... my/image:overriden
-```
-
-#### User permissions and ownership
-
-The actual application user account and the user group are created by the startup script on the first container start.
-
-During this one-time task the startup script needs to modify the container files `/etc/passwd` and `/etc/group`. That is why there is the line `chmod 666 /etc/passwd /etc/group` in the Dockerfile (see the `stage_final`). However, the permissions of these two files will be set to the standard value `644` just after creating the user.
-
-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.
-
-There is the script `~/tests/test-01.sh` that allows quick check of the current permissions.
-
-#### Other considerations
-
-Please note that the described configuration will not be done if the startup script `startup.sh` will not be executed.
-
-Also do not confuse the application user's password with the **VNC password**, because they both have the same default value (`headless`).
-
-## Running containers in background (detached)
-
-The following container will keep running in the background and it will listen on an automatically selected TCP port on the host computer:
-
-```shell
-docker run -d -P accetto/debian-vnc-xfce-firefox-g3:latest
-```
-
-The following container will listen on the host's TCP port **25901**:
-
-```shell
-docker run -d -p 25901:5901 accetto/debian-vnc-xfce-firefox-g3:latest
-```
-
-The following container will create (or re-use) the local named volume **my\_Downloads** mounted as `/home/headless/Downloads`:
-
-```shell
-docker run -d -P -v my_Downloads:/home/headless/Downloads accetto/debian-vnc-xfce-firefox-g3:latest
-```
-
-or using the newer syntax with **--mount** flag:
-
-```shell
-docker run -d -P --mount source=my_Downloads,target=/home/headless/Downloads accetto/debian-vnc-xfce-firefox-g3:latest
-```
-
-## Running containers in foreground (interactively)
-
-The following container can be used interactively:
-
-```shell
-docker run -it --rm accetto/debian-vnc-xfce-firefox-g3:latest bash
-```
-
-The opened `bash` session can be used as usual and then closed by entering `^C` (CTRL-C):
-
-```shell
-To run a command as administrator (user "root"), use "sudo <command>".
-See "man sudo_root" for details.
-
-headless@cf4a4e01d94b:~$ whoami
-headless
-headless@cf4a4e01d94b:~$ pwd
-/home/headless
-headless@cf4a4e01d94b:~$
-```
-
-The container will remove itself.
-
-## Firefox multi-process
-
-Firefox multi-process (also known as **Electrolysis** or just **E10S**) can cause heavy crashing in Docker containers if there is not enough shared memory (**Gah. Your tab just crashed.**).
-
-In Firefox versions till **76.0.1** it has been possible to disable multi-process by setting the environment variable **MOZ_FORCE_DISABLE_E10S**. However, in Firefox **77.0.1** it has caused ugly scrambling of almost all web pages, because they were not decompressed.
-
-Mozilla has fixed the problem in the next release, but they warned about not supporting the switch in the future. That is why I've decided, that all images with Firefox will use multi-process by default, even if it requires larger shared memory. On the positive side, performance should be higher and Internet browsing should be sand-boxed.
-
-Please check the older sibling Wiki page [Firefox multi-process][that-wiki-firefox-multiprocess] for more information and the instructions, how the shared memory size can be set in different scenarios.
-
-### Setting shared memory size
-
-Instability of multi-process Firefox is caused by setting the shared memory size too low. Docker assigns only **64MB** by default. Testing on my computers has shown, that using at least **256MB** completely eliminates the problem. However, it could be different on your system.
-
-The older sibling Wiki page [Firefox multi-process][that-wiki-firefox-multiprocess] describes several ways, how to increase the shared memory size. It's really simple, if you need it for a single container started from the command line.
-
-For example, the following container will have its shared memory size set to 256MB:
-
-```shell
-docker run -d -P --shm-size=256m accetto/debian-vnc-xfce-firefox-g3:latest
-```
-
-You can check the current shared memory size by executing the following command inside the container:
-
-```shell
-df -h /dev/shm
-```
-
-## Firefox preferences and the plus features
-
-Firefox browser supports pre-configuration of user preferences.
-
-Users can enforce their personal browser preferences if they put them into the `user.js` file and then copy it into the Firefox profile folder. The provided **plus** features make it really easy.
-
-There is the `/home/headless/firefox.plus` folder containing the `user.js` file and the helper utility `copy_firefox_user_preferences.sh`. It will copy the `user.js` file into one or more existing Firefox profiles. The utility is easy to use, because it is interactive and it will also display the help, if started with the `-h` or `--help` argument.
-
-To make it even more convenient, there are also desktop launchers for the utility and for the **Firefox Profile Manager**.
-
-Recommended procedure for taking advantage of the **plus** features is:
-
-- Start the **Firefox Profile Manager** using the desktop launcher **FF Profile Manager**. Create a new Firefox profile if there is none or you want to add one more. Wait until the profile is created and then start Firefox with it. Starting Firefox is required to create the actual profile content.
-  
-  **Hint**: You can also check the **Work offline** check-box before creating the profile.
-
-  The Firefox profiles are created inside the `/home/headless/.mozilla/firefox` folder by default. Note that the `.mozilla` folder is hidden.
-
-  Close the **Profile Manager** by pushing the **Exit** button.
-
-- Put your personal Firefox preferences into the `user.js` file which is in the `/home/headless/firefox.plus`folder. Check the Firefox documentation (e.g. [Firefox preferences][firefox-doc-preferences]) for more information about the syntax.  
-  
-  **Hint**: There is also another way. You can first start Firefox, configure it and then copy the content of the `prefs.js` file from the Firefox profile folder into the `user.js` file. Then you can check the content and to keep only the preferences you really want to enforce. It's not a quick task, but you have to do it only once or until you need an update.
-
-- Start the helper utility using the desktop launcher **Copy FF Preferences**. The utility will allow you to copy the `user.js` file to any of the existing Firefox profiles.  
-  
-  **Hint**: You preferences will be enforced until you delete the `user.js` file from the Firefox profile folder.
-
-It is also very easy to build customized images with pre-filled `user.js` files.
-
-## Startup options and help
-
-The image supports multiple **start-up options** and **start-up modifiers**. There also also two help modes.
-
-The following container will print out the short help and then it will remove itself:
-
-```shell
-docker run --rm accetto/debian-vnc-xfce-firefox-g3:latest --help
-```
-
-Example of the short help text:
-
-```text
-Container startup script
-Usage: /dockerstartup/startup.sh [-v|--version] [-h|--help] [-H|--help-usage] [--(no-)wait] [--(no-)skip-startup] [--(no-)tail-null] [--(no-)tail-vnc] [--(no-)version-sticker] [--(no-)version-sticker-verbose] [--(no-)skip-vnc] [--(no-)skip-novnc] [--(no-)debug] [--(no-)verbose] [--] [<command-1>] ... [<command-n>] ...
-        <command>: Optional command with optional arguments. It is executed during startup.
-        -v, --version: Prints version
-        -h, --help: Prints help
-        -H, --help-usage: Extended container usage help.
-        --wait, --no-wait: Default background execution mode (on by default)
-        --skip-startup, --no-skip-startup: Default foreground execution mode (off by default)
-        --tail-null, --no-tail-null: Alternative background execution mode (off by default)
-        --tail-vnc, --no-tail-vnc: Alternative background execution mode (off by default)
-        --version-sticker, --no-version-sticker: Alternative foreground execution mode (off by default)
-        --version-sticker-verbose, --no-version-sticker-verbose: Alternative foreground execution mode (off by default)
-        --skip-vnc, --no-skip-vnc: Startup process modifier (off by default)
-        --skip-novnc, --no-skip-novnc: Startup process modifier (off by default)
-        --debug, --no-debug: Startup process modifier (off by default)
-        --verbose, --no-verbose: Startup process modifier (off by default)
-
-Use '-H' or '--help-usage' for extended container usage help.
-For more information visit https://github.com/accetto/debian-vnc-xfce-g3
-```
-
-The following container will print out the long help and then it will remove itself:
-
-```shell
-docker run --rm accetto/debian-vnc-xfce-firefox-g3:latest --help-usage
-```
-
-Example of the long help text:
-
-```text
-CONTAINER USAGE:
-docker run [<docker-run-options>] accetto/<image>:<tag> [<startup-options>] [<command>]
-
-POSITIONAL ARGUMENTS:
-command
-    Optional command with optional arguments.
-    It will be executed during startup before going waiting, tailing or asleep.
-    It is necessary to use the quotes correctly or the 'bash -c "<command>"' pattern.
-
-STARTUP OPTIONS:
-
---wait, or no options, or unknown option, or empty input
-    Default background execution mode.
-    Starts the VNC and noVNC servers, if available, then executes the command
-    and waits until the VNC server process exits or goes asleep infinitely.
-    Container keeps running in the background.
-
---skip-startup
-    Default foreground execution mode.
-    Skips the startup procedure, executes the command and exits.
-    Be aware that the container user generator will be also skipped.
-    Container does not keep running in the background.
-
---tail-null
-    Alternative background execution mode.
-    Similar to '--wait', but tails the null device instead of going asleep.
-    Container keeps running in the background.
-
---tail-vnc
-    Alternative background execution mode.
-    Similar to '--wait', but tails the VNC log instead of waiting until the VNC process exits.
-    Falls back to '--tail-null' if the VNC server has not been started.
-    Container keeps running in the background.
-
---version-sticker
-    Alternative foreground execution mode.
-    Prints out the version sticker info.
-    The VNC server is also started by default, if available, because some applications
-    need a display to report their versions correctly. It can be suppressed by providing
-    also '--skip-vnc'. The '--skip-novnc' option is always enforced automatically.
-    Container does not keep running in the background.
-
---version-sticker-verbose
-    Alternative foreground execution mode.
-    Similar to '--version-sticker', but prints out the verbose version sticker info and features list.
-    Container does not keep running in the background.
-
---skip-vnc
-    Startup process modifier.
-    If VNC and noVNC startup should be skipped.
-    It also enforces '--skip-novnc'.
-
---skip-novnc
-    Startup process modifier.
-    If noVNC startup should be skipped.
-    It is also enforced by '--skip-vnc'.
-
---debug
-    Startup process modifier.
-    If additional debugging info should be displayed during startup.
-    It also enforces option '--verbose'.
-
---verbose
-    Startup process modifier.
-    If startup progress messages should be displayed.
-    It is also enforced by '--debug'.
-
---help-usage, -H
-    Prints out this extended container usage help and exits.
-    The rest of the input is ignored.
-
---help, -h
-    Prints out the short startup script help and exits.
-    The rest of the input is ignored.
-
---version, -v
-    Prints out the version of the startup script and exits.
-    The rest of the input is ignored.
-
-Use '-h' or '--help' for short startup script help.
-Fore more information visit https://github.com/accetto/debian-vnc-xfce-g3
-```
-
-## Issues, Wiki and Discussions
-
-If you have found a problem or you just have a question, please check the [Issues][this-issues] and the [sibling Wiki][sibling-wiki] first. Please do not overlook the closed issues.
-
-If you do not find a solution, you can file a new issue. The better you describe the problem, the bigger the chance it'll be solved soon.
-
-If you have a question or an idea and you don't want to open an issue, you can use the [sibling Discussions][sibling-discussions].
-
-## Credits
-
-Credit goes to all the countless people and companies, who contribute to open source community and make so many dreamy things real.
-
-## Diagrams
-
-The stage diagram doesn't differ from the [sibling project][accetto-github-ubuntu-vnc-xfce-g3].
-
-### Dockerfile.xfce
+The stage diagram doesn't differ from the sibling project [accetto/github-ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3].
 
 ![Dockerfile.xfce stages][sibling-diagram-dockerfile-stages]
 
 ***
 
-<!-- GitHub project common -->
+[this-user-guide]: https://accetto.github.io/user-guide-g3/
+
+[this-readme]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/README.md
 
 [this-changelog]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/CHANGELOG.md
-[this-github]: https://github.com/accetto/debian-vnc-xfce-g3/
+
 [this-issues]: https://github.com/accetto/debian-vnc-xfce-g3/issues
-[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 -->
 
 [this-docker]: https://hub.docker.com/r/accetto/debian-vnc-xfce-firefox-g3/
+
 [this-dockerfile]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/docker/Dockerfile.xfce
 
-[this-screenshot-container]: https://raw.githubusercontent.com/accetto/debian-vnc-xfce-g3/master/docker/doc/images/debian-vnc-xfce-firefox-plus.jpg
-
-<!-- Sibling projects -->
-
 [accetto-github-ubuntu-vnc-xfce-g3]: https://github.com/accetto/ubuntu-vnc-xfce-g3
 
 [sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki
+
 [sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions
 
 [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/
+
 [accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce
 
-[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess
-
-<!-- External links -->
-
-[docker-debian]: https://hub.docker.com/_/debian/
 [docker-ubuntu]: https://hub.docker.com/_/ubuntu/
-
-[docker-doc]: https://docs.docker.com/
-[docker-doc-managing-data]: https://docs.docker.com/storage/
-
-[debian-packages-search]: https://packages.debian.org/index
-
-[jq]: https://stedolan.github.io/jq/
-[mousepad]: https://github.com/codebrainz/mousepad
-[nano]: https://www.nano-editor.org/
-[novnc]: https://github.com/kanaka/noVNC
-[tigervnc]: http://tigervnc.org
-[tightvnc]: http://www.tightvnc.com
-[tini]: https://github.com/krallin/tini
-[xfce]: http://www.xfce.org
-
-[firefox]: https://www.mozilla.org
-[firefox-doc-preferences]: https://developer.mozilla.org/en-US/docs/Mozilla/Preferences/A_brief_guide_to_Mozilla_preferences
-
-<!-- github badges common -->
-
-[badge-github-release]: https://badgen.net/github/release/accetto/debian-vnc-xfce-g3?icon=github&label=release
-
-[badge-github-release-date]: https://img.shields.io/github/release-date/accetto/debian-vnc-xfce-g3?logo=github
-
-<!-- docker badges specific -->
-
-[badge-docker-pulls]: https://badgen.net/docker/pulls/accetto/debian-vnc-xfce-firefox-g3?icon=docker&label=pulls
-
-[badge-docker-stars]: https://badgen.net/docker/stars/accetto/debian-vnc-xfce-firefox-g3?icon=docker&label=stars

docker/xfce-firefox/readme-append.template

@@ -8,3 +8,11 @@
 [badge_latest_version-sticker]: https://badgen.net/https/gist.githubusercontent.com/${OWNER}/${GIST}/raw/${REPO}@latest@version-sticker.json
 
 [link_latest_version-sticker-verbose]: https://gist.githubusercontent.com/${OWNER}/${GIST}/raw/${REPO}@latest@version-sticker-verbose.txt
+
+<!-- 11 -->
+
+[badge_11_created]: https://badgen.net/https/gist.githubusercontent.com/${OWNER}/${GIST}/raw/${REPO}@11@created.json
+
+[badge_11_version-sticker]: https://badgen.net/https/gist.githubusercontent.com/${OWNER}/${GIST}/raw/${REPO}@11@version-sticker.json
+
+[link_11_version-sticker-verbose]: https://gist.githubusercontent.com/${OWNER}/${GIST}/raw/${REPO}@11@version-sticker-verbose.txt

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-dockerhub.md

@@ -2,221 +2,128 @@
 
 ## accetto/debian-vnc-xfce-g3
 
-[Docker Hub][this-docker] - [Git Hub][this-github] - [Dockerfile][this-dockerfile] - [Full Readme][this-readme-full] - [Changelog][this-changelog] - [Project Readme][this-readme-project]
+[User Guide][this-user-guide] - [GitHub][this-github] - [Dockerfile][this-dockerfile] - [Readme][this-readme-full] - [Changelog][this-changelog]
 
 ![badge-docker-pulls][badge-docker-pulls]
 ![badge-docker-stars][badge-docker-stars]
 ![badge-github-release][badge-github-release]
-![badge-github-release-date][badge-github-release-date]
 
 ***
 
-- [Headless Debian/Xfce container with VNC/noVNC](#headless-debianxfce-container-with-vncnovnc)
-  - [accetto/debian-vnc-xfce-g3](#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)
-    - [Description](#description)
-    - [Image tags](#image-tags)
-    - [More information](#more-information)
+This Docker Hub repository contains Docker images for headless working.
 
-***
+The images are based on the current [Debian 12][docker-debian] and the previous [Debian 11][docker-debian] and include [Xfce][xfce] desktop, [TigerVNC][tigervnc] server and [noVNC][novnc] client.
 
-### Introduction
+This [User guide][this-user-guide] describes the images and how to use them.
 
-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.
+The related [GitHub project][this-github] contains image generators that image users generally don’t need, unless they want to build the images themselves.
 
-There is also a similar sibling image [accetto/ubuntu-vnc-xfce-g3][accetto-dockerhub-ubuntu-vnc-xfce-g3] based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu].
+### Tags
 
-This is the **short README** version for the **Docker Hub**. There is also the [full-length README][this-readme-full] on the **GitHub**.
+The following image tags are regularly built and published on Docker Hub:
 
-### TL;DR
+<!-- markdownlint-disable MD052 -->
 
-#### Installing packages
+- `latest` (also as `12`) based on `Debian 12`
 
-I try to keep the images slim. Consequently you can 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.
+    ![badge_latest_created][badge_latest_created]
+    [![badge_latest_version-sticker][badge_latest_version-sticker]][link_latest_version-sticker-verbose]
 
-You can also try to fix it by executing the following (the default `sudo` password is **headless**):
+- `11` based on `Debian 11`
 
-```shell
-### apt cache needs to be updated only once
-sudo apt-get update
+    ![badge_11_created][badge_11_created]
+    [![badge_11_version-sticker][badge_11_version-sticker]][link_11_version-sticker-verbose]
 
-sudo apt --fix-broken install
-```
+<!-- markdownlint-enable MD052 -->
 
-#### Shared memory size
+**Hint:** Clicking the version sticker badge reveals more information about the particular build.
 
-Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior.
-
-You can check the current shared memory size by executing the following command inside the container:
-
-```shell
-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
-
-The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images.
-
-Your concrete `Dockerfile` may need more statements, but the concept should be clear.
-
-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
-
-The fastest way to build the images:
-
-```shell
-### PWD = project root
-### prepare and source the 'secrets.rc' file first (see 'example-secrets.rc')
-
-### examples of building and publishing the individual images
-./builder.sh latest all
-
-### just building an image, skipping the publishing and the version sticker update
-./builder.sh latest build
-
-### examples of building and publishing the images as a group
-./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 [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 the [local-building-example][this-readme-local-building-example] for more information.
-
-#### Sharing devices
-
-Sharing the display with the host works only on Linux:
-
-```shell
-xhost +local:$(whoami)
-
-docker run -it -P --rm \
-    -e DISPLAY=${DISPLAY} \
-    --device /dev/dri/card0 \
-    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
-    accetto/debian-vnc-xfce-g3:latest --skip-vnc
-
-xhost -local:$(whoami)
-```
-
-Sharing the X11 socket with the host works only on Linux:
-
-```shell
-xhost +local:$(whoami)
-
-docker run -it -P --rm \
-    --device /dev/dri/card0 \
-    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
-    accetto/debian-vnc-xfce-g3:latest
-
-xhost -local:$(whoami)
-```
-
-### Description
-
-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].
+### Features
 
 The main features and components of the images in the default configuration are:
 
-- utilities **ping**, **wget**, **sudo** (Debian distribution)
+- lightweight [Xfce][xfce] desktop environment (Debian distribution)
+- [sudo][sudo] support
 - current version of JSON processor [jq][jq]
-- light-weight [Xfce][xfce] desktop environment (Debian distribution)
 - current version of high-performance [TigerVNC][tigervnc] server and client
 - current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**)
 - popular text editor [nano][nano] (Debian distribution)
 - lite but advanced graphical editor [mousepad][mousepad] (Debian distribution)
 - 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**)
+- support for overriding environment variables, VNC parameters, user and group (see [User guide][this-user-guide-using-containers])
+- support of **version sticker** (see [User guide][this-user-guide-version-sticker])
 
-The history of notable changes is documented in the [CHANGELOG][this-changelog].
+The following **TCP** ports are exposed by default:
+
+- **5901** for access over **VNC** (using VNC viewer)
+- **6901** for access over [noVNC][novnc] (using web browser)
 
 ![container-screenshot][this-screenshot-container]
 
-### Image tags
+### Remarks
 
-The following image tags are regularly built and published on the **Docker Hub**:
+There is also a similar sibling repository [accetto/ubuntu-vnc-xfce-g3][accetto-dockerhub-ubuntu-vnc-xfce-g3], containing images based on [Ubuntu 22.04 LTS and 20.04 LTS][docker-ubuntu].
 
-- `latest` based on `Debian 11`
+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].
 
-    ![badge_latest_created][badge_latest_created]
-    [![badge_latest_version-sticker][badge_latest_version-sticker]][link_latest_version-sticker-verbose]
+### Getting help
 
-Clicking on the version sticker badge reveals more information about the actual configuration of the image.
+If you've found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and [sibling Wiki][sibling-wiki] first.
+Please do not overlook the closed issues.
 
-### More information
+If you do not find a solution, you can file a new issue.
+The better you describe the problem, the bigger the chance it'll be solved soon.
 
-More information about these images can be found in the [full-length README][this-readme-full] file on the GitHub.
+If you have a question or an idea and you don't want to open an issue, you can also use the [sibling Discussions][sibling-discussions].
 
 ***
 
-<!-- GitHub project common -->
+[this-user-guide]: https://accetto.github.io/user-guide-g3/
+
+[this-user-guide-version-sticker]: https://accetto.github.io/user-guide-g3/version-sticker/
+
+[this-user-guide-using-containers]: https://accetto.github.io/user-guide-g3/using-containers/
 
 [this-changelog]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/CHANGELOG.md
+
 [this-github]: https://github.com/accetto/debian-vnc-xfce-g3/
-<!-- [this-issues]: https://github.com/accetto/debian-vnc-xfce-g3/issues -->
+
 [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
+[this-issues]: https://github.com/accetto/debian-vnc-xfce-g3/issues
 
-<!-- Docker image specific -->
-
-[this-docker]: https://hub.docker.com/r/accetto/debian-vnc-xfce-g3/
 [this-dockerfile]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/docker/Dockerfile.xfce
 
-[this-screenshot-container]: https://raw.githubusercontent.com/accetto/debian-vnc-xfce-g3/master/docker/doc/images/debian-vnc-xfce-g3.jpg
-
-<!-- Sibling projects -->
+[this-screenshot-container]: https://raw.githubusercontent.com/accetto/debian-vnc-xfce-g3/master/docker/doc/images/animation-debian-vnc-xfce-g3.gif
 
 [accetto-dockerhub-ubuntu-vnc-xfce-g3]: https://hub.docker.com/r/accetto/ubuntu-vnc-xfce-g3
 
 [sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki
 
-<!-- Previous generations -->
+[sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions
 
 [accetto-github-xubuntu-vnc-novnc]: https://github.com/accetto/xubuntu-vnc-novnc/
+
 [accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce
 
-[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess
-
-<!-- External links -->
-
 [docker-debian]: https://hub.docker.com/_/debian/
 [docker-ubuntu]: https://hub.docker.com/_/ubuntu/
 
-<!-- [docker-doc]: https://docs.docker.com/ -->
-<!-- [docker-doc-managing-data]: https://docs.docker.com/storage/ -->
-
-[debian-packages-search]: https://packages.debian.org/index
-
 [jq]: https://stedolan.github.io/jq/
 [mousepad]: https://github.com/codebrainz/mousepad
 [nano]: https://www.nano-editor.org/
 [novnc]: https://github.com/kanaka/noVNC
+[sudo]: https://www.sudo.ws/
 [tigervnc]: http://tigervnc.org
 [tini]: https://github.com/krallin/tini
 [xfce]: http://www.xfce.org
 
-<!-- github badges common -->
-
-[badge-github-release]: https://badgen.net/github/release/accetto/debian-vnc-xfce-g3?icon=github&label=release
-
-[badge-github-release-date]: https://img.shields.io/github/release-date/accetto/debian-vnc-xfce-g3?logo=github
-
-<!-- docker badges specific -->
+[badge-github-release]: https://badgen.net/github/release/accetto/debian-vnc-xfce-g3?icon=github&label=GitHub
 
 [badge-docker-pulls]: https://badgen.net/docker/pulls/accetto/debian-vnc-xfce-g3?icon=docker&label=pulls
 
 [badge-docker-stars]: https://badgen.net/docker/stars/accetto/debian-vnc-xfce-g3?icon=docker&label=stars
 
-<!-- Appendix -->
+<!-- Appendix will be added by util-readme.sh -->

docker/xfce/README.md

@@ -2,97 +2,21 @@
 
 ## accetto/debian-vnc-xfce-g3
 
-[Docker Hub][this-docker] - [Git Hub][this-github] - [Dockerfile][this-dockerfile] - [Docker Readme][this-readme-dockerhub] - [Changelog][this-changelog] - [Project Readme][this-readme-project]
-
-![badge-docker-pulls][badge-docker-pulls]
-![badge-docker-stars][badge-docker-stars]
-![badge-github-release][badge-github-release]
-![badge-github-release-date][badge-github-release-date]
+[User Guide][this-user-guide] - [Docker Hub][this-docker] - [Dockerfile][this-dockerfile] - [Readme][this-readme] - [Changelog][this-changelog]
 
 ***
 
-- [Headless Debian/Xfce container with VNC/noVNC](#headless-debianxfce-container-with-vncnovnc)
-  - [accetto/debian-vnc-xfce-g3](#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)
-    - [Description](#description)
-    - [Image tags](#image-tags)
-    - [Ports](#ports)
-    - [Volumes](#volumes)
-    - [Version sticker](#version-sticker)
-  - [Using headless containers](#using-headless-containers)
-    - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters)
-  - [Container user account](#container-user-account)
-    - [Overriding container user parameters](#overriding-container-user-parameters)
-      - [Overriding user parameters in build-time](#overriding-user-parameters-in-build-time)
-      - [Overriding user parameters in run-time](#overriding-user-parameters-in-run-time)
-      - [User permissions and ownership](#user-permissions-and-ownership)
-      - [Other considerations](#other-considerations)
-  - [Running containers in background (detached)](#running-containers-in-background-detached)
-  - [Running containers in foreground (interactively)](#running-containers-in-foreground-interactively)
-  - [Startup options and help](#startup-options-and-help)
-  - [Issues, Wiki and Discussions](#issues-wiki-and-discussions)
-  - [Credits](#credits)
-  - [Diagrams](#diagrams)
-    - [Dockerfile.xfce](#dockerfilexfce)
+This GitHub project folder contains resources used by building Debian images available on Docker Hub in the repository [accetto/debian-vnc-xfce-g3][this-docker].
 
-***
+This [User guide][this-user-guide] describes the images and how to use them.
 
-### 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.
-
-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
-
-#### Installing packages
-
-I try to keep the images slim. Consequently you can 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.
-
-You can also try to fix it by executing the following (the default `sudo` password is **headless**):
-
-```shell
-### apt cache needs to be updated only once
-sudo apt-get update
-
-sudo apt --fix-broken install
-```
-
-#### Shared memory size
-
-Note that some applications require larger shared memory than the default 64MB. Using 256MB usually solves crashes or strange behavior.
-
-You can check the current shared memory size by executing the following command inside the container:
-
-```shell
-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
-
-The provided example file `Dockerfile.extend` shows how to use the images as the base for your own images.
-
-Your concrete `Dockerfile` may need more statements, but the concept should be clear.
-
-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
-
-The fastest way to build the images:
+### Building images
 
 ```shell
 ### PWD = project root
 ### prepare and source the 'secrets.rc' file first (see 'example-secrets.rc')
 
-### examples of building and publishing the individual images 
+### examples of building and publishing the individual images
 ./builder.sh latest all
 
 ### just building the image, skipping the publishing and the version sticker update
@@ -102,558 +26,60 @@ 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 [builder-utility-readme][this-builder-readme], [local-building-example][this-readme-local-building-example] and [sibling Wiki][sibling-wiki] for more information.
+Refer to the main [README][this-readme] file for more information about the building subject.
 
-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.
+### Remarks
 
-#### Sharing devices
+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].
 
-Sharing the display with the host works only on Linux:
+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].
 
-```shell
-xhost +local:$(whoami)
+### Getting help
 
-docker run -it -P --rm \
-    -e DISPLAY=${DISPLAY} \
-    --device /dev/dri/card0 \
-    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
-    accetto/debian-vnc-xfce-g3:latest --skip-vnc
+If you've found a problem or you just have a question, please check the [User guide][this-user-guide], [Issues][this-issues] and [sibling Wiki][sibling-wiki] first.
+Please do not overlook the closed issues.
 
-xhost -local:$(whoami)
-```
+If you do not find a solution, you can file a new issue.
+The better you describe the problem, the bigger the chance it'll be solved soon.
 
-Sharing the X11 socket with the host works only on Linux:
+If you have a question or an idea and you don't want to open an issue, you can also use the [sibling Discussions][sibling-discussions].
 
-```shell
-xhost +local:$(whoami)
+### Diagrams
 
-docker run -it -P --rm \
-    --device /dev/dri/card0 \
-    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
-    accetto/debian-vnc-xfce-g3:latest
+Diagram of the multi-staged Dockerfile used for building multiple images.
 
-xhost -local:$(whoami)
-```
+The actual content of a particular image build is controlled by the *feature variables*.
 
-### Description
-
-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].
-
-The main features and components of the images in the default configuration are:
-
-- utilities **ping**, **wget**, **sudo** (Debian distribution)
-- current version of JSON processor [jq][jq]
-- light-weight [Xfce][xfce] desktop environment (Debian distribution)
-- current version of high-performance [TigerVNC][tigervnc] server and client
-- current version of [noVNC][novnc] HTML5 clients (full and lite) (TCP port **6901**)
-- popular text editor [nano][nano] (Debian distribution)
-- lite but advanced graphical editor [mousepad][mousepad] (Debian distribution)
-- 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)
-
-The history of notable changes is documented in the [CHANGELOG][this-changelog].
-
-![container-screenshot][this-screenshot-container]
-
-### Image tags
-
-The following image tags are regularly built and published on the **Docker Hub**:
-
-- `latest` based on `Debian 11`
-
-Clicking on the version sticker badge in the [README on Docker Hub][this-readme-dockerhub] reveals more information about the actual configuration of the image.
-
-### Ports
-
-Following **TCP** ports are exposed by default:
-
-- **5901** is used for access over **VNC**
-- **6901** is used for access over [noVNC][novnc]
-
-These default ports and also some other parameters can be overridden several ways (see bellow).
-
-### Volumes
-
-The containers do not create or use any external volumes by default.
-
-Both **named volumes** and **bind mounts** can be used. More about volumes can be found in [Docker documentation][docker-doc] (e.g. [Manage data in Docker][docker-doc-managing-data]).
-
-### Version sticker
-
-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.
-
-The **verbose version sticker value** is used by the CI builder to decide if the image needs to be refreshed. It describes the actual configuration of the essential components of the image. It can be revealed by clicking on the version sticker badge in the README file.
-
-The version sticker values are generated by the script `version_sticker.sh`, which is deployed into the startup directory `/dockerstartup`. The script will show a short help if executed with the argument `-h`. There is also a convenient `Version Sticker` launcher on the container desktop.
-
-## Using headless containers
-
-There are two ways, how to use the containers created from this image.
-
-All containers are accessible by a VNC viewer (e.g. [TigerVNC][tigervnc] or [TightVNC][tightvnc]).
-
-The default `VNC_PORT` value is `5901`. The default `DISPLAY` value is `:1`. The default VNC password (`VNC_PW`) is `headless`.
-
-The containers that are created from the images built with the **noVNC feature** can be also accessed over [noVNC][noVNC] by any web browser supporting HTML5.
-
-The default `NOVNC_PORT` value is `6901`. The noVNC password is always identical to the VNC password.
-
-There are several ways of connecting to headless containers and the possibilities also differ between the Linux and Windows environments, but usually it is done by mapping the VNC/noVNC ports exposed by the container to some free TCP ports on its host system.
-
-For example, the following command would map the VNC/noVNC ports `5901/6901` of the container to the TCP ports `25901/26901` on the host:
-
-```shell
-docker run -p 25901:5901 -p 26901:6901 ...
-```
-
-If the container would run on the local computer, then it would be accessible over **VNC** as `localhost:25901` and over **noVNC** as `http://localhost:26901`.
-
-If it would run on the remote server  `mynas`, then it would be accessible over **VNC** as `mynas:25901` and over **noVNC** as `http://mynas:26901`.
-
-The image offers two [noVNC][novnc] clients - **lite client** and **full client**. Because the connection URL differs slightly in both cases, the container provides a **simple startup page**.
-
-The startup page offers two hyperlinks for both noVNC clients:
-
-- **noVNC Lite Client** (`http://mynas:26901/vnc_lite.html`)
-- **noVNC Full Client** (`http://mynas:26901/vnc.html`)
-
-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 VNC/noVNC parameters
-
-The VNC/noVNC parameters are controlled by related environment variables embedded into the image.
-
-They have the following default values:
-
-```shell
-DISPLAY=:1
-NOVNC_PORT=6901
-VNC_COL_DEPTH=24
-VNC_PORT=5901
-VNC_PW=headless
-VNC_RESOLUTION=1360x768
-VNC_VIEW_ONLY=false
-```
-
-These environment variables can be overridden several ways.
-
-**At image build-time** you can embed different default values by using the following build arguments:
-
-- `ARG_VNC_PW` sets the variable `VNC_PW` (VNV/noVNC password)
-- `ARG_VNC_DISPLAY` sets the variable `DISPLAY`
-- `ARG_VNC_PORT` sets the variable `VNC_PORT`
-- `ARG_VNC_RESOLUTION` sets the variable `VNC_RESOLUTION`
-- `ARG_VNC_COL_DEPTH` sets the variable `VNC_COL_DEPTH`
-- `ARG_VNC_VIEW_ONLY` set the variable `VNC_VIEW_ONLY`
-- `ARG_NOVNC_PORT` sets the variable `NOVNC_PORT`
-
-For example:
-
-```shell
-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`).
-
-For example:
-
-```shell
-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).
-
-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
-```
-
-The content of the file should be similar to the provided example file `example-vnc-override.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
-export VNC_RESOLUTION=1024x768
-export DISPLAY=:2
-export VNC_PORT=5902
-export NOVNC_PORT=6902
-;export NOVNC_HEARTBEAT=25
-```
-
-Please note that only the lines beginning with `export` at the first position will be imported.
-
-By providing the variable values the following rules apply:
-
-- The value of `ARG_VNC_DISPLAY/VNC_DISPLAY` should include also the leading colon (e.g. `:1`).
-- The value of `ARG_VNC_PW/VNC_PW` can be empty. It effectively disables the VNC/noVNC password.
-
-If you want to check, what parameter values have been actually applied, then you can start the container with the parameter `--debug`.
-
-For example:
-
-```shell
-docker run -it -P --rm accetto/debian-vnc-xfce-g3:latest --debug
-
-### output (excerpt)
-VNC server started on display ':1' and TCP port '5901'
-Connect via VNC viewer with 172.17.0.3:5901
-noVNC started on TCP port '6901'
-```
-
-You should be aware, that overriding the VNC/noVNC parameters incorrectly could prevent the container from starting.
-
-This feature assumes some preliminary knowledge and it is provided for advanced users that already know what they want to achieve.
-
-For example, by default there is a relation between the `DISPLAY` and `VNC_PORT` values. Generally the convention `VNC_PORT = 5900 + DISPLAY` is followed (similarly `NOVNC_PORT = 6900 + DISPLAY`).
-
-You may decide not to follow the conventions. This image allows you to set the parameters differently, but again, you should know, what you are doing.
-
-Be also aware, that there are differences between the Linux and Windows environments.
-
-If your session disconnects, it might be related to a network equipment (load-balancer, reverse proxy, ...) dropping the websocket session for inactivity (more info [here](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) and [here](https://nginx.org/en/docs/http/websocket.html) for nginx). In such case, try defining the **NOVNC_HEARTBEAT=XX** environment variable at startup-time, where **XX** is the number of seconds between [websocket ping/pong](https://github.com/websockets/ws/issues/977) packets.
-
-## Container user account
-
-Containers created from this image run under the **application user** (by default `headless:headless`, `1000:1000`), which is a **non-root** user account. However, the application user gets permissions for `sudo`.
-
-The **application user name** also defines the **home directory name**, which is by default `/home/headless`.
-
-The default application user's password is `headless`, which is also the default `sudo` password.
-
-The user's (and `sudo`) password can be changed inside the container by using the `passwd` command. For example, changing the password to `docker`:
-
-```shell
-echo 'headless:docker' | sudo chpasswd
-
-### or also
-sudo chpasswd <<<"headless:docker"
-```
-
-The `sudo` command allows user elevation, so the **application user** can install additional software inside the container.
-
-The following example shows how to install **vim**:
-
-```shell
-sudo apt-get update
-sudo apt-get install -y vim
-```
-
-### Overriding container user parameters
-
-The user ID, user name, user group ID, user group name and the initial `sudo` password can be overridden during the build time (`docker build`).
-
-The user ID and the group ID can be overridden also in run time (`docker run`).
-
-#### Overriding user parameters in build-time
-
-The build parameters `ARG_HEADLESS_USER_ID`, `ARG_HEADLESS_USER_NAME`, `ARG_HEADLESS_USER_GROUP_ID` and `ARG_HEADLESS_USER_GROUP_NAME` are used during the build time (`docker build`) and they allow to override the related container parameters.
-
-Their values are persisted in the corresponding environment variables `HEADLESS_USER_ID`, `HEADLESS_USER_NAME`, `HEADLESS_USER_GROUP_ID` and `HEADLESS_USER_GROUP_NAME`.
-
-The build argument `ARG_SUDO_INITIAL_PW` allows overriding the initial application user's and `sudo` password (which is `headless`). This initial password is not stored into any environment variable, but into a temporary file, which is removed on the first container start. The password can be changed inside the container.
-
-For example, building an image with the application user name `hairless`, with the primary user group `hairygroup`, the IDs `2002:3003` and the initial password `docker`:
-
-```shell
-docker build --build-arg ARG_HEADLESS_USER_NAME=hairless --build-arg ARG_HEADLESS_USER_GROUP_NAME=hairygroup --build-arg ARG_HEADLESS_USER_ID=2002 --build-arg ARG_HEADLESS_USER_GROUP_ID=3003 --build-arg ARG_SUDO_INITIAL_PW=docker ... -t my/image:overriden
-```
-
-#### Overriding user parameters in run-time
-
-Both the user ID and group ID can be overridden also in the run time (`docker run`). It does not apply to the application user name, the group name and the initial password.
-
-For example, this would override the `user:group` by `2000:3000`:
-
-```shell
-docker run --user 2000:3000 ... my/image:overriden
-```
-
-#### User permissions and ownership
-
-The actual application user account and the user group are created by the startup script on the first container start.
-
-During this one-time task the startup script needs to modify the container files `/etc/passwd` and `/etc/group`. That is why there is the line `chmod 666 /etc/passwd /etc/group` in the Dockerfile (see the `stage_final`). However, the permissions of these two files will be set to the standard value `644` just after creating the user.
-
-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.
-
-There is the script `~/tests/test-01.sh` that allows quick check of the current permissions.
-
-#### Other considerations
-
-Please note that the described configuration will not be done if the startup script `startup.sh` will not be executed.
-
-Also do not confuse the application user's password with the **VNC password**, because they both have the same default value (`headless`).
-
-## Running containers in background (detached)
-
-The following container will keep running in the background and it will listen on an automatically selected TCP port on the host computer:
-
-```shell
-docker run -d -P accetto/debian-vnc-xfce-g3
-```
-
-The following container will listen on the host's TCP port **25901**:
-
-```shell
-docker run -d -p 25901:5901 accetto/debian-vnc-xfce-g3
-```
-
-The following container will create (or re-use) the local named volume **my\_Downloads** mounted as `/home/headless/Downloads`:
-
-```shell
-docker run -d -P -v my_Downloads:/home/headless/Downloads accetto/debian-vnc-xfce-g3:latest
-```
-
-or using the newer syntax with **--mount** flag:
-
-```shell
-docker run -d -P --mount source=my_Downloads,target=/home/headless/Downloads accetto/debian-vnc-xfce-g3:latest
-```
-
-## Running containers in foreground (interactively)
-
-The following container can be used interactively:
-
-```shell
-docker run -it --rm accetto/debian-vnc-xfce-g3:latest bash
-```
-
-The opened `bash` session can be used as usual and then closed by entering `^C` (CTRL-C):
-
-```shell
-To run a command as administrator (user "root"), use "sudo <command>".
-See "man sudo_root" for details.
-
-headless@cf4a4e01d94b:~$ whoami
-headless
-headless@cf4a4e01d94b:~$ pwd
-/home/headless
-headless@cf4a4e01d94b:~$
-```
-
-The container will remove itself.
-
-## Startup options and help
-
-The image supports multiple **start-up options** and **start-up modifiers**. There also also two help modes.
-
-The following container will print out the short help and then it will remove itself:
-
-```shell
-docker run --rm accetto/debian-vnc-xfce-g3:latest --help
-```
-
-Example of the short help text:
-
-```text
-Container startup script
-Usage: /dockerstartup/startup.sh [-v|--version] [-h|--help] [-H|--help-usage] [--(no-)wait] [--(no-)skip-startup] [--(no-)tail-null] [--(no-)tail-vnc] [--(no-)version-sticker] [--(no-)version-sticker-verbose] [--(no-)skip-vnc] [--(no-)skip-novnc] [--(no-)debug] [--(no-)verbose] [--] [<command-1>] ... [<command-n>] ...
-        <command>: Optional command with optional arguments. It is executed during startup.
-        -v, --version: Prints version
-        -h, --help: Prints help
-        -H, --help-usage: Extended container usage help.
-        --wait, --no-wait: Default background execution mode (on by default)
-        --skip-startup, --no-skip-startup: Default foreground execution mode (off by default)
-        --tail-null, --no-tail-null: Alternative background execution mode (off by default)
-        --tail-vnc, --no-tail-vnc: Alternative background execution mode (off by default)
-        --version-sticker, --no-version-sticker: Alternative foreground execution mode (off by default)
-        --version-sticker-verbose, --no-version-sticker-verbose: Alternative foreground execution mode (off by default)
-        --skip-vnc, --no-skip-vnc: Startup process modifier (off by default)
-        --skip-novnc, --no-skip-novnc: Startup process modifier (off by default)
-        --debug, --no-debug: Startup process modifier (off by default)
-        --verbose, --no-verbose: Startup process modifier (off by default)
-
-Use '-H' or '--help-usage' for extended container usage help.
-For more information visit https://github.com/accetto/debian-vnc-xfce-g3
-```
-
-The following container will print out the long help and then it will remove itself:
-
-```shell
-docker run --rm accetto/debian-vnc-xfce-g3:latest --help-usage
-```
-
-Example of the long help text:
-
-```text
-CONTAINER USAGE:
-docker run [<docker-run-options>] accetto/<image>:<tag> [<startup-options>] [<command>]
-
-POSITIONAL ARGUMENTS:
-command
-    Optional command with optional arguments.
-    It will be executed during startup before going waiting, tailing or asleep.
-    It is necessary to use the quotes correctly or the 'bash -c "<command>"' pattern.
-
-STARTUP OPTIONS:
-
---wait, or no options, or unknown option, or empty input
-    Default background execution mode.
-    Starts the VNC and noVNC servers, if available, then executes the command
-    and waits until the VNC server process exits or goes asleep infinitely.
-    Container keeps running in the background.
-
---skip-startup
-    Default foreground execution mode.
-    Skips the startup procedure, executes the command and exits.
-    Be aware that the container user generator will be also skipped.
-    Container does not keep running in the background.
-
---tail-null
-    Alternative background execution mode.
-    Similar to '--wait', but tails the null device instead of going asleep.
-    Container keeps running in the background.
-
---tail-vnc
-    Alternative background execution mode.
-    Similar to '--wait', but tails the VNC log instead of waiting until the VNC process exits.
-    Falls back to '--tail-null' if the VNC server has not been started.
-    Container keeps running in the background.
-
---version-sticker
-    Alternative foreground execution mode.
-    Prints out the version sticker info.
-    The VNC server is also started by default, if available, because some applications
-    need a display to report their versions correctly. It can be suppressed by providing
-    also '--skip-vnc'. The '--skip-novnc' option is always enforced automatically.
-    Container does not keep running in the background.
-
---version-sticker-verbose
-    Alternative foreground execution mode.
-    Similar to '--version-sticker', but prints out the verbose version sticker info and features list.
-    Container does not keep running in the background.
-
---skip-vnc
-    Startup process modifier.
-    If VNC and noVNC startup should be skipped.
-    It also enforces '--skip-novnc'.
-
---skip-novnc
-    Startup process modifier.
-    If noVNC startup should be skipped.
-    It is also enforced by '--skip-vnc'.
-
---debug
-    Startup process modifier.
-    If additional debugging info should be displayed during startup.
-    It also enforces option '--verbose'.
-
---verbose
-    Startup process modifier.
-    If startup progress messages should be displayed.
-    It is also enforced by '--debug'.
-
---help-usage, -H
-    Prints out this extended container usage help and exits.
-    The rest of the input is ignored.
-
---help, -h
-    Prints out the short startup script help and exits.
-    The rest of the input is ignored.
-
---version, -v
-    Prints out the version of the startup script and exits.
-    The rest of the input is ignored.
-
-Use '-h' or '--help' for short startup script help.
-Fore more information visit https://github.com/accetto/debian-vnc-xfce-g3
-```
-
-## Issues, Wiki and Discussions
-
-If you have found a problem or you just have a question, please check the [Issues][this-issues] and the [sibling Wiki][sibling-wiki] first. Please do not overlook the closed issues.
-
-If you do not find a solution, you can file a new issue. The better you describe the problem, the bigger the chance it'll be solved soon.
-
-If you have a question or an idea and you don't want to open an issue, you can use the [sibling Discussions][sibling-discussions].
-
-## Credits
-
-Credit goes to all the countless people and companies, who contribute to open source community and make so many dreamy things real.
-
-## Diagrams
-
-The stage diagram doesn't differ from the [sibling project][accetto-github-ubuntu-vnc-xfce-g3].
-
-### Dockerfile.xfce
+The stage diagram doesn't differ from the sibling project [accetto/github-ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3].
 
 ![Dockerfile.xfce stages][sibling-diagram-dockerfile-stages]
 
 ***
 
-<!-- GitHub project common -->
+[this-user-guide]: https://accetto.github.io/user-guide-g3/
+
+[this-readme]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/README.md
 
 [this-changelog]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/CHANGELOG.md
-[this-github]: https://github.com/accetto/debian-vnc-xfce-g3/
+
 [this-issues]: https://github.com/accetto/debian-vnc-xfce-g3/issues
-[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 -->
 
 [this-docker]: https://hub.docker.com/r/accetto/debian-vnc-xfce-g3/
+
 [this-dockerfile]: https://github.com/accetto/debian-vnc-xfce-g3/blob/master/docker/Dockerfile.xfce
 
-[this-screenshot-container]: https://raw.githubusercontent.com/accetto/debian-vnc-xfce-g3/master/docker/doc/images/debian-vnc-xfce-g3.jpg
-
-<!-- Sibling projects -->
-
 [accetto-github-ubuntu-vnc-xfce-g3]: https://github.com/accetto/ubuntu-vnc-xfce-g3
+
 [sibling-wiki]: https://github.com/accetto/ubuntu-vnc-xfce-g3/wiki
+
 [sibling-discussions]: https://github.com/accetto/ubuntu-vnc-xfce-g3/discussions
 
 [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/
+
 [accetto-github-ubuntu-vnc-xfce]: https://github.com/accetto/ubuntu-vnc-xfce
 
-[that-wiki-firefox-multiprocess]: https://github.com/accetto/xubuntu-vnc/wiki/Firefox-multiprocess
-
-<!-- External links -->
-
-[docker-debian]: https://hub.docker.com/_/debian/
 [docker-ubuntu]: https://hub.docker.com/_/ubuntu/
-
-[docker-doc]: https://docs.docker.com/
-[docker-doc-managing-data]: https://docs.docker.com/storage/
-
-[debian-packages-search]: https://packages.debian.org/index
-
-[jq]: https://stedolan.github.io/jq/
-[mousepad]: https://github.com/codebrainz/mousepad
-[nano]: https://www.nano-editor.org/
-[novnc]: https://github.com/kanaka/noVNC
-[tigervnc]: http://tigervnc.org
-[tightvnc]: http://www.tightvnc.com
-[tini]: https://github.com/krallin/tini
-[xfce]: http://www.xfce.org
-
-<!-- github badges common -->
-
-[badge-github-release]: https://badgen.net/github/release/accetto/debian-vnc-xfce-g3?icon=github&label=release
-
-[badge-github-release-date]: https://img.shields.io/github/release-date/accetto/debian-vnc-xfce-g3?logo=github
-
-<!-- docker badges specific -->
-
-[badge-docker-pulls]: https://badgen.net/docker/pulls/accetto/debian-vnc-xfce-g3?icon=docker&label=pulls
-
-[badge-docker-stars]: https://badgen.net/docker/stars/accetto/debian-vnc-xfce-g3?icon=docker&label=stars

docker/xfce/readme-append.template

@@ -8,3 +8,15 @@
 [badge_latest_version-sticker]: https://badgen.net/https/gist.githubusercontent.com/${OWNER}/${GIST}/raw/${REPO}@latest@version-sticker.json
 
 [link_latest_version-sticker-verbose]: https://gist.githubusercontent.com/${OWNER}/${GIST}/raw/${REPO}@latest@version-sticker-verbose.txt
+
+<!-- 11 -->
+
+[badge_11_created]: https://badgen.net/https/gist.githubusercontent.com/${OWNER}/${GIST}/raw/${REPO}@11@created.json
+
+[badge_11_version-sticker]: https://badgen.net/https/gist.githubusercontent.com/${OWNER}/${GIST}/raw/${REPO}@11@version-sticker.json
+
+[link_11_version-sticker-verbose]: https://gist.githubusercontent.com/${OWNER}/${GIST}/raw/${REPO}@11@version-sticker-verbose.txt
+
+
+
+

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

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

@@ -48,14 +48,15 @@ export DOCKER_BUILDKIT=1
 # export BUILDER_REPO=""
 # ### shared g3-cache is outside the Docker building context
 # export SHARED_G3_CACHE_PATH=""
-# ### building process control
-# # export FORCE_PUBLISHING_BUILDER_REPO=1
-# export FORCE_BUILDING=0
+# ### used to control building/publishing (unset means '0')
+# export FORCE_PUBLISHING_BUILDER_REPO=1
+# export FORCE_BUILDING=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
+# ### explicitly disable features that are enabled by default
 # # export FEATURES_NOVNC=0
 # # export FEATURES_FIREFOX_PLUS=0
+# # export FEATURES_OVERRIDING_ENVV=0
 
 #endregion
 
@@ -81,14 +82,15 @@ export DOCKER_BUILDKIT=1
 # export BUILDER_REPO=""
 # ### shared g3-cache is outside the Docker building context
 # export SHARED_G3_CACHE_PATH=""
-# ### building process control
-# export FORCE_PUBLISHING_BUILDER_REPO=0
-# export FORCE_BUILDING=0
+# ### used to control building/publishing (unset means '0')
+# export FORCE_PUBLISHING_BUILDER_REPO=1
+# export FORCE_BUILDING=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_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

readme-builder.md

@@ -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)
@@ -10,7 +13,8 @@
 
 ## Introduction
 
-This utility script can build and publish individual images. It can also execute the individual hook scripts of the building pipeline (`docker/hooks` folder).
+This utility script can build and publish individual images.
+It can also execute the individual hook scripts of the building pipeline (`docker/hooks` folder).
 
 Common usage pattern:
 
@@ -38,22 +42,88 @@ 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**:
@@ -77,7 +147,8 @@ You can skip the publishing to the **Docker Hub** by replacing the command `all`
 ./builder.sh latest all-no-push
 ```
 
-You can also provide additional parameters for the internally used Docker `build` command. For example:
+You can also provide additional parameters for the internally used Docker `build` command.
+For example:
 
 ```shell
 ./builder.sh latest all-no-push --no-cache
@@ -87,6 +158,7 @@ You can also provide additional parameters for the internally used Docker `build
 ```
 
 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
 
@@ -113,11 +185,14 @@ The building pipeline consists of the following steps, that can be executed also
 ./builder.sh latest post_push
 ```
 
-The optional `<docker-cli-options>` are passed to the each individual hook script, which can pass them to the internally used Docker CLI command. The `cache` hook script, however, doesn't use any Docker CLI commands.
+The optional `<docker-cli-options>` are passed to the each individual hook script, which can pass them to the internally used Docker CLI command.
+The `cache` hook script, however, doesn't use any Docker CLI commands.
 
 ### What about the 'cache' helper script
 
-The `cache` hook script has been introduced in the **second version** (G3v2) of the building pipeline in the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3]. It refreshes the local `g3-cache`, which must be always placed inside the Docker build context. The script is also used by the `pre_build` and `build` hook scripts.
+The `cache` hook script has been introduced in the **second version** (G3v2) of the building pipeline in the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3].
+It refreshes the local `g3-cache`, which must be always placed inside the Docker build context.
+The script is also used by the `pre_build` and `build` hook scripts.
 
 The `g3-cache` and the rules for its refreshing are described separately.
 

readme-ci-builder.md

@@ -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,14 +13,15 @@
       - [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)
 
 ## Introduction
 
-This utility script can build and publish sets of images. It can also extract selected information from the building log.
+This utility script can build and publish sets of images.
+It can also extract selected information from the building log.
 
 The common usage pattern
 
@@ -67,24 +71,91 @@ The script creates a complete execution log.
 
 The optional parameter `--no-cache` will be passed to the internally used script `builder.sh`.
 
-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. 
+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
@@ -99,7 +170,8 @@ The **group mode** usage pattern:
 
 #### Group mode examples
 
-The image tags can be listed in the command line. For example, all these images will be built independently of each other.
+The image tags can be listed in the command line.
+For example, all these images will be built independently of each other.
 
 ```shell
 ./ci-builder.sh all group latest latest-firefox latest-chromium
@@ -125,13 +197,16 @@ You can also use one of the **named groups**:
 
 The **family mode** is intended for efficient building of sets of dependent images.
 
-**Remark:** Since the version G3v3 of the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] is this mode for advanced use only. The previous images `accetto/ubuntu-vnc-xfce-g3:latest-fugo` and `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` that used it are not published any more. The image `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` has been renamed to `accetto/ubuntu-vnc-xfce-firefox-g3:latest`.
+**Remark:** Since the version G3v3 of the sibling project [accetto/ubuntu-vnc-xfce-g3][accetto-github-ubuntu-vnc-xfce-g3] is this mode for advanced use only.
+The previous images `accetto/ubuntu-vnc-xfce-g3:latest-fugo` and `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` that used it are not published any more.
+The image `accetto/ubuntu-vnc-xfce-firefox-g3:latest-plus` has been renamed to `accetto/ubuntu-vnc-xfce-firefox-g3:latest`.
 
 The dependency in this context is meant more technically than conceptually.
 
 The following example will help to understand the concept.
 
-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].
+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].
 
 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.
 
@@ -167,7 +242,8 @@ The following command could also be used, but there would be no benefit comparin
 ./ci-builder.sh all family latest-chromium
 ```
 
-You can also skip the publishing to the **Docker Hub** by replacing the `all` command by the `all-no-push` one. For example:
+You can also skip the publishing to the **Docker Hub** by replacing the `all` command by the `all-no-push` one.
+For example:
 
 ```shell
 ### image 'latest-fugo' will be skipped if the 'latest' image doesn't need a re-build
@@ -176,7 +252,8 @@ You can also skip the publishing to the **Docker Hub** by replacing the `all` co
 
 ### Log processing
 
-The **log processing** mode is intended for evaluating the outcome of the latest image building session. The result are extracted from the **ci-builder log** by `grep` utility.
+The **log processing** mode is intended for evaluating the outcome of the latest image building session.
+The result are extracted from the **ci-builder log** by `grep` utility.
 
 The **log processing mode** usage pattern:
 
@@ -205,9 +282,10 @@ 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).
+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).
 
 ```shell
 ./ci-builder.sh log get stickers

readme-g3-cache.md

@@ -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,21 @@ 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**:
@@ -38,9 +48,11 @@ The same shared `g3-cache` is usually used also by the sibling projects, for exa
 
 ## Helper script `cache`
 
-Both `g3-caches` are refreshed by the helper script `cache`, which is stored in the folder `docker/hooks/`. Therefore it's sometimes referenced as a hook script.
+Both `g3-caches` are refreshed by the helper script `cache`, which is stored in the folder `docker/hooks/`.
+Therefore it's sometimes referenced as a hook script.
 
-The script is used by the hook scripts `pre_build` and `build`. However, it can be executed also stand-alone.
+The script is used by the hook scripts `pre_build` and `build`.
+However, it can be executed also stand-alone.
 
 **Remark**: The current implementation of the cache refreshing code is not thread safe and it is not intended for parallel building of multiple images.
 

readme-local-building-example.md

@@ -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)
@@ -18,6 +21,8 @@
     - [Disabling `noVNC`](#disabling-novnc)
     - [Disabling `Firefox Plus`](#disabling-firefox-plus)
   - [README files for Docker Hub](#readme-files-for-docker-hub)
+  - [Tips and examples](#tips-and-examples)
+    - [How to deploy all images into one repository](#how-to-deploy-all-images-into-one-repository)
 
 ## Introduction
 
@@ -29,11 +34,34 @@ The **second version** (G3v2) of the building pipeline introduced in the sibling
 
 ## 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 +75,45 @@ 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,11 +125,14 @@ 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 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.
+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.
 
-There is also the helper script `util-readme.sh`, stored in the folder `utils/`. This script can be used for preparing the `README` file for the **Docker Hub**.
+There is also the helper script `util-readme.sh`, stored in the folder `utils/`.
+This script can be used for preparing the `README` file for the **Docker Hub**.
 
 ## Three ways of building images
 
@@ -76,7 +146,9 @@ Since the **second version** (G3v2) of the building pipeline introduced in the s
 
 ### Building and publishing sets of images
 
-Building and publishing of sets of images is pretty easy. Let's say that we want to refresh the images that feature the Firefox browser. We can do that by executing the following command:
+Building and publishing of sets of images is pretty easy.
+Let's say that we want to refresh the images that feature the Firefox browser.
+We can do that by executing the following command:
 
 ```shell
 ### PWD = project's root directory
@@ -97,7 +169,9 @@ You can find more information and examples in the separate `readme` file, descri
 
 ### Building and publishing individual images
 
-Building and publishing of individual images is also very easy. Let's say we wan to refresh the image `accetto/debian-vnc-xfce-g3:latest`. We could execute the following command:
+Building and publishing of individual images is also very easy.
+Let's say we wan to refresh the image `accetto/debian-vnc-xfce-g3:latest`.
+We could execute the following command:
 
 ```shell
 ### PWD = project's root directory
@@ -116,7 +190,8 @@ You can find more information and examples in the separate `readme` file, descri
 
 ### Step-by-step building and publishing
 
-The building pipeline can executed also step-by-step. The hook scripts in the folder `docker/hooks/` can be executed directly or also by using the utility script `builder.sh`.
+The building pipeline can executed also step-by-step.
+The hook scripts in the folder `docker/hooks/` can be executed directly or also by using the utility script `builder.sh`.
 
 The script `builder.sh` is using the individual hook scripts internally.
 
@@ -142,7 +217,9 @@ This step builds the temporary helper image and creates the following temporary
 - `scrap-version_sticker-verbose_previous.tmp`
 - `scrap-demand-stop-building`
 
-The file `scrap-demand-stop-building` is created only if the verbose version sticker hasn't changed since the last time it has been published on the builder repository's **GitHub Gist** and if the environment variable `FORCE_BUILDING` is not set to `1`. **Its presence will block** the next hook script `build` from building a new persistent image. If you want to force the image building, you can delete this file manually.
+The file `scrap-demand-stop-building` is created only if the verbose version sticker hasn't changed since the last time it has been published on the builder repository's **GitHub Gist** and if the environment variable `FORCE_BUILDING` is not set to `1`.
+**Its presence will block** the next hook script `build` from building a new persistent image.
+If you want to force the image building, you can delete this file manually.
 
 The other option is to set the environment variable `FORCE_BUILDING=1` **before** executing the `pre_build` script.
 
@@ -285,6 +362,40 @@ For example, the `README` file for the repository `accetto/debian-vnc-xfce-g3` c
 ./util-readme.sh --repo accetto/debian-vnc-xfce-g3 --context=../docker/xfce -- preview
 ```
 
+## Tips and examples
+
+### How to deploy all images into one repository
+
+There are three deployment repositories by default.
+
+Their names are defined by the following environment variables:
+
+- `DEPLOYMENT_REPO` for generic images
+- `DEPLOYMENT_REPO_CHROMIUM` for images with Chromium
+- `DEPLOYMENT_REPO_FIREFOX` for images with Firefox
+
+The forth variable `BUILDER_REPO` defines the name of the *builder repository*, which is not used for deployment by default.
+
+However, the images can be optionally published also into the *builder repository* by setting the environment variable `FORCE_PUBLISHING_BUILDER_REPO=1`.
+
+The images in the builder repository are distinguished by their tags.
+
+On the other hand, if the repository environment variables are unset or set to the reserved value `void`, then the deployment into the related repository will be skipped.
+
+This behaviour can be used, if you want to publish all the images into a single repository.
+
+Simply set all repositories except the builder one to `void` and force the publishing into the builder repository.
+
+For example, for publishing all the images into a single repository `headless-debian-g3` set the variables like this:
+
+```shell
+DEPLOYMENT_REPO="void"
+DEPLOYMENT_REPO_CHROMIUM="void"
+DEPLOYMENT_REPO_FIREFOX="void"
+BUILDER_REPO="headless-debian-g3"
+FORCE_PUBLISHING_BUILDER_REPO=1
+```
+
 ***
 
 [accetto-github-ubuntu-vnc-xfce-g3]: https://github.com/accetto/ubuntu-vnc-xfce-g3