Release 23.03.1

2023-03-12 18:39:11 +01:00
parent b0d7a185c6
commit 7d1417aed5
15 changed files with 257 additions and 58 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,10 @@

 ***

+### 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
--- a/README.md
+++ b/README.md
@@ -25,21 +25,21 @@ Version: G3v1

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

-### Introduction
+## Introduction

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

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

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

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

 There are currently resources for the following Docker images:

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

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

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

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

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

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

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

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

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

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

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

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

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

 The fastest way to build the images:

@@ -127,7 +127,7 @@ The fastest way to build the images:

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

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

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

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

-### Image generations
+## Image generations

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

-### Project versions
+## Project versions

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

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

-### Project goals
+## Project goals

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

-### Project features
+## Project features

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

--- a/docker/hooks/build
+++ b/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"

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

@@ -156,7 +157,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}"

--- a/docker/hooks/env.rc
+++ b/docker/hooks/env.rc
@@ -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"
--- a/docker/hooks/post_push
+++ b/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. 
--- a/docker/hooks/pre_build
+++ b/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"

@@ -61,7 +61,6 @@ main() {
    ### no quotes around 'params'
    docker build ${params} \
        -f "${DOCKERFILE_PATH}" \
-            --build-arg BUILDKIT_INLINE_CACHE=1 \
            --build-arg BASEIMAGE="${BASEIMAGE}" \
            --build-arg BASETAG="${BASETAG}" \
            \
--- a/docker/hooks/push
+++ b/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"
--- a/docker/hooks/release_of
+++ b/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
 }
--- a/docker/xfce/src/home/config/dconf/user
+++ b/docker/xfce/src/home/config/dconf/user
--- a/examples/Dockerfile.extend
+++ b/examples/Dockerfile.extend
@@ -14,12 +14,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,10 +27,6 @@ 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}"
-
 ### 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
--- a/readme-builder.md
+++ b/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)
@@ -38,22 +41,85 @@ The script creates a complete execution log.

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

-## Prerequisites
+## Preparation

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

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

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

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

 ### or also

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

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

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

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

 ## Executing individual pipeline steps

--- a/readme-ci-builder.md
+++ b/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,7 +13,7 @@
      - [Family mode examples](#family-mode-examples)
    - [Log processing](#log-processing)
      - [Digest command](#digest-command)
-      - [Stickers commands](#stickers-commands)
+      - [Stickers command](#stickers-command)
      - [Timing command](#timing-command)
      - [Errors command](#errors-command)
  - [Additional building parameters](#additional-building-parameters)
@@ -69,22 +72,85 @@ The optional parameter `--no-cache` will be passed to the internally used script

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

-## Prerequisites
+## Preparation

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

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

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

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

 ### or also

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

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

 ### Group mode
@@ -205,7 +271,7 @@ Built new 'headless-debian-g3:latest-chromium'.
 Built new 'headless-debian-g3:latest-firefox'.
 ```

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

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

--- a/readme-g3-cache.md
+++ b/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,18 @@ The custom `g3-cache` has been introduced in the **second version** (G3v2) of th

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

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

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

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

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

 The local `g3-cache` of this project has the following **cache sections**:
--- a/readme-local-building-example.md
+++ b/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)
@@ -29,11 +32,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 +73,42 @@ source ./secrets.rc

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

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

 The actual building pipeline consists of the following hook scripts stored in the folder `docker/hooks`: