diff --git a/CHANGELOG.md b/CHANGELOG.md index 8d903a6..87a2830 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,26 @@ *** +### 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. diff --git a/docker/Dockerfile.xfce b/docker/Dockerfile.xfce index 6ed57db..7544f2e 100644 --- a/docker/Dockerfile.xfce +++ b/docker/Dockerfile.xfce @@ -310,9 +310,11 @@ FROM ${ARG_MERGE_STAGE_BROWSER_BASE} as merge_stage_browser ############### FROM ${ARG_FINAL_STAGE_BASE} as stage_final +ARG ARG_FEATURES_OVERRIDING_ENVV ARG ARG_SUDO_INITIAL_PW ENV \ + FEATURES_OVERRIDING_ENVV="${ARG_FEATURES_OVERRIDING_ENVV:+1}" \ FEATURES_VERSION_STICKER=1 \ STARTUPDIR="/dockerstartup" diff --git a/docker/hooks/build b/docker/hooks/build index 1acaa3d..e1bd0c4 100644 --- a/docker/hooks/build +++ b/docker/hooks/build @@ -74,6 +74,7 @@ main() { --build-arg ARG_VCS_REF="$(git rev-parse --short HEAD)" \ \ ${FEATURES_BUILD_SLIM:+--build-arg ARG_APT_NO_RECOMMENDS=1} \ + ${FEATURES_OVERRIDING_ENVV:+--build-arg ARG_FEATURES_OVERRIDING_ENVV=1} \ ${FEATURES_SCREENSHOOTING:+--build-arg ARG_FEATURES_SCREENSHOOTING=1} \ ${FEATURES_THUMBNAILING:+--build-arg ARG_FEATURES_THUMBNAILING=1} \ \ diff --git a/docker/hooks/env.rc b/docker/hooks/env.rc index 71b9e92..c69490d 100644 --- a/docker/hooks/env.rc +++ b/docker/hooks/env.rc @@ -73,9 +73,11 @@ if [[ $# -ge 2 ]] ; then shift 2 ; fi ### FEATURES_NOVNC: if 'noVNC' and 'websockify' should be included ### FEATURES_SCREENSHOOTING: if 'xfce4-screenshooter' and 'ristretto' should be included ### FEATURES_THUMBNAILING: if 'tumbler' should be included +### FEATURES_OVERRIDING_ENVV: if overriding environment variables at container startup time should be enabled ### Remark: There are also 'FEATURES_*' variables that are always set, e.g. 'FEATURES_VERSION_STICKER=1'. ### These features influence the content of almost all stages: +### Warning! Anything except '0' means '1', even unset or emty. if [[ "${FEATURES_BUILD_SLIM}" == "0" ]] ; then FEATURES_BUILD_SLIM="" ; else FEATURES_BUILD_SLIM=1 ; fi ### These features influence the content of the related stages: @@ -86,6 +88,10 @@ if [[ "${FEATURES_THUMBNAILING}" == "1" ]] ; then FEATURES_THUMBNAILING=1 ; else if [[ "${FEATURES_CHROMIUM}" == "1" ]] ; then FEATURES_CHROMIUM=1 ; else FEATURES_CHROMIUM="" ; fi if [[ "${FEATURES_FIREFOX}" == "1" ]] ; then FEATURES_FIREFOX=1 ; else FEATURES_FIREFOX="" ; fi +### These features influence container behaviour at startup time +### Warning! Anything except '0' means '1', even unset or emty. +if [[ "${FEATURES_OVERRIDING_ENVV}" == "0" ]] ; then FEATURES_OVERRIDING_ENVV="" ; else FEATURES_OVERRIDING_ENVV=1 ; fi + ### These features are always enabled and cannot be disabled via environment variables FEATURES_VNC=1 diff --git a/docker/hooks/pre_build b/docker/hooks/pre_build index 6fc3a69..a65ac4b 100644 --- a/docker/hooks/pre_build +++ b/docker/hooks/pre_build @@ -65,6 +65,7 @@ main() { --build-arg BASETAG="${BASETAG}" \ \ ${FEATURES_BUILD_SLIM:+--build-arg ARG_APT_NO_RECOMMENDS=1} \ + ${FEATURES_OVERRIDING_ENVV:+--build-arg ARG_FEATURES_OVERRIDING_ENVV=1} \ ${FEATURES_SCREENSHOOTING:+--build-arg ARG_FEATURES_SCREENSHOOTING=1} \ ${FEATURES_THUMBNAILING:+--build-arg ARG_FEATURES_THUMBNAILING=1} \ \ diff --git a/docker/src/xfce-startup/startup.sh b/docker/src/xfce-startup/startup.sh index 50662de..36336c2 100644 --- a/docker/src/xfce-startup/startup.sh +++ b/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,6 +117,12 @@ 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 if [[ -s "${STARTUPDIR}"/.initial_sudo_password ]] ; then diff --git a/docker/src/xfce-startup/vnc_startup.rc b/docker/src/xfce-startup/vnc_startup.rc index f0dbabe..e3c942d 100644 --- a/docker/src/xfce-startup/vnc_startup.rc +++ b/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 diff --git a/docker/xfce-chromium/README.md b/docker/xfce-chromium/README.md index 35123e7..3f6ddce 100644 --- a/docker/xfce-chromium/README.md +++ b/docker/xfce-chromium/README.md @@ -26,6 +26,7 @@ - [Volumes](#volumes) - [Version sticker](#version-sticker) - [Using headless containers](#using-headless-containers) + - [Overriding environment variables](#overriding-environment-variables) - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters) - [Container user account](#container-user-account) - [Overriding container user parameters](#overriding-container-user-parameters) @@ -237,6 +238,21 @@ It is also possible to provide the password through the links: - `http://mynas:26901/vnc_lite.html?password=headless` - `http://mynas:26901/vnc.html?password=headless` +### Overriding environment variables + +If the environment variable `FEATURES_OVERRIDING_ENVV=1`, which is the case by default, then the container startup script will look for the file `$HOME/.override/.override_envv.rc` and source all the lines that begin with the string 'export ' at the first position and contain the '=' character. + +You can provide the overriding file from outside the container using *bind mounts* or *volumes*. + +This feature allows overriding or adding environment variables at the **container startup-time**. +It means, even after the container has already been created. + +You can disable this behavior by setting the variable `FEATURES_OVERRIDING_ENVV` to zero when the container is created or the image is built. + +The lines that have been actually sourced can be reported into the container's log if the startup parameter `--verbose` or `--debug` is provided. + +Look below for the example how to override the VNC/noVNC parameters at the container startup-time. + ### Overriding VNC/noVNC parameters The VNC/noVNC parameters are controlled by related environment variables embedded into the image. @@ -271,7 +287,7 @@ For example: docker build --build-arg DISPLAY=:2 --build-arg ARG_VNC_PORT=6902 ... ``` -**At container startup-time** you can override the environment variable values by using the `docker run -e` option. Please note that in this case you have to use the actual environment variable names, not the build argument names (e.g. `VNC_PORT` instead of `ARG_VNC_PORT`). +**At container creation-time** you can override the environment variable values by using the `docker run -e` option. Please note that in this case you have to use the actual environment variable names, not the build argument names (e.g. `VNC_PORT` instead of `ARG_VNC_PORT`). For example: @@ -279,29 +295,25 @@ For example: docker run -e VNC_PORT=6902 ... ``` -**At VNC/noVNC startup-time** you can override the environment variable values by binding an external file exporting the variables to the dedicated mounting point `${HOME}/.vnc_override.rc` (a single file, not a directory). +**At container startup-time** you can override the VNC/noVNC variables using the feature `FEATURES_OVERRIDING_ENVV' described above. For example, the following command would bind the file `my_own_vnc_parameters.rc` from the directory `/home/joe` to the container: ```shell -docker run -v /home/joe/my_own_vnc_parameters.rc:/home/headless/.vnc_override.rc +docker run -v /home/joe/my_own_vnc_parameters.rc:/home/headless/.override/.override_envv.rc ``` -The content of the file should be similar to the provided example file `example-vnc-override.rc`: +The content of the file should be similar to the provided example file `example-override-envv.rc`: ```shell -### only lines beginning with 'export ' (at position 1) will be imported and sourced -;export VNC_COL_DEPTH=32 -;export VNC_VIEW_ONLY=true -;export VNC_PW=secret +### only the lines beginning with 'export ' at the first position and containing '=' will be sourced export VNC_RESOLUTION=1024x768 -export DISPLAY=:2 -export VNC_PORT=5902 -export NOVNC_PORT=6902 -;export NOVNC_HEARTBEAT=25 +export VNC_PW=secret +#export DISPLAY=:2 +#export VNC_COL_DEPTH=32 ``` -Please note that only the lines beginning with `export` at the first position will be imported. +Please note that only the lines beginning with the string 'export ' at the first position and containing the '=' character will be imported. By providing the variable values the following rules apply: diff --git a/docker/xfce-firefox/README.md b/docker/xfce-firefox/README.md index cfdb109..6d94df8 100644 --- a/docker/xfce-firefox/README.md +++ b/docker/xfce-firefox/README.md @@ -26,6 +26,7 @@ - [Volumes](#volumes) - [Version sticker](#version-sticker) - [Using headless containers](#using-headless-containers) + - [Overriding environment variables](#overriding-environment-variables) - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters) - [Container user account](#container-user-account) - [Overriding container user parameters](#overriding-container-user-parameters) @@ -235,6 +236,21 @@ It is also possible to provide the password through the links: - `http://mynas:26901/vnc_lite.html?password=headless` - `http://mynas:26901/vnc.html?password=headless` +### Overriding environment variables + +If the environment variable `FEATURES_OVERRIDING_ENVV=1`, which is the case by default, then the container startup script will look for the file `$HOME/.override/.override_envv.rc` and source all the lines that begin with the string 'export ' at the first position and contain the '=' character. + +You can provide the overriding file from outside the container using *bind mounts* or *volumes*. + +This feature allows overriding or adding environment variables at the **container startup-time**. +It means, even after the container has already been created. + +You can disable this behavior by setting the variable `FEATURES_OVERRIDING_ENVV` to zero when the container is created or the image is built. + +The lines that have been actually sourced can be reported into the container's log if the startup parameter `--verbose` or `--debug` is provided. + +Look below for the example how to override the VNC/noVNC parameters at the container startup-time. + ### Overriding VNC/noVNC parameters The VNC/noVNC parameters are controlled by related environment variables embedded into the image. @@ -269,7 +285,7 @@ For example: docker build --build-arg DISPLAY=:2 --build-arg ARG_VNC_PORT=6902 ... ``` -**At container startup-time** you can override the environment variable values by using the `docker run -e` option. Please note that in this case you have to use the actual environment variable names, not the build argument names (e.g. `VNC_PORT` instead of `ARG_VNC_PORT`). +**At container creation-time** you can override the environment variable values by using the `docker run -e` option. Please note that in this case you have to use the actual environment variable names, not the build argument names (e.g. `VNC_PORT` instead of `ARG_VNC_PORT`). For example: @@ -277,29 +293,25 @@ For example: docker run -e VNC_PORT=6902 ... ``` -**At VNC/noVNC startup-time** you can override the environment variable values by binding an external file exporting the variables to the dedicated mounting point `${HOME}/.vnc_override.rc` (a single file, not a directory). +**At container startup-time** you can override the VNC/noVNC variables using the feature `FEATURES_OVERRIDING_ENVV' described above. For example, the following command would bind the file `my_own_vnc_parameters.rc` from the directory `/home/joe` to the container: ```shell -docker run -v /home/joe/my_own_vnc_parameters.rc:/home/headless/.vnc_override.rc +docker run -v /home/joe/my_own_vnc_parameters.rc:/home/headless/.override/.override_envv.rc ``` -The content of the file should be similar to the provided example file `example-vnc-override.rc`: +The content of the file should be similar to the provided example file `example-override-envv.rc`: ```shell -### only lines beginning with 'export ' (at position 1) will be imported and sourced -;export VNC_COL_DEPTH=32 -;export VNC_VIEW_ONLY=true -;export VNC_PW=secret +### only the lines beginning with 'export ' at the first position and containing '=' will be sourced export VNC_RESOLUTION=1024x768 -export DISPLAY=:2 -export VNC_PORT=5902 -export NOVNC_PORT=6902 -;export NOVNC_HEARTBEAT=25 +export VNC_PW=secret +#export DISPLAY=:2 +#export VNC_COL_DEPTH=32 ``` -Please note that only the lines beginning with `export` at the first position will be imported. +Please note that only the lines beginning with the string 'export ' at the first position and containing the '=' character will be imported. By providing the variable values the following rules apply: diff --git a/docker/xfce/README.md b/docker/xfce/README.md index af56098..bd6f36e 100644 --- a/docker/xfce/README.md +++ b/docker/xfce/README.md @@ -26,6 +26,7 @@ - [Volumes](#volumes) - [Version sticker](#version-sticker) - [Using headless containers](#using-headless-containers) + - [Overriding environment variables](#overriding-environment-variables) - [Overriding VNC/noVNC parameters](#overriding-vncnovnc-parameters) - [Container user account](#container-user-account) - [Overriding container user parameters](#overriding-container-user-parameters) @@ -225,6 +226,21 @@ It is also possible to provide the password through the links: - `http://mynas:26901/vnc_lite.html?password=headless` - `http://mynas:26901/vnc.html?password=headless` +### Overriding environment variables + +If the environment variable `FEATURES_OVERRIDING_ENVV=1`, which is the case by default, then the container startup script will look for the file `$HOME/.override/.override_envv.rc` and source all the lines that begin with the string 'export ' at the first position and contain the '=' character. + +You can provide the overriding file from outside the container using *bind mounts* or *volumes*. + +This feature allows overriding or adding environment variables at the **container startup-time**. +It means, even after the container has already been created. + +You can disable this behavior by setting the variable `FEATURES_OVERRIDING_ENVV` to zero when the container is created or the image is built. + +The lines that have been actually sourced can be reported into the container's log if the startup parameter `--verbose` or `--debug` is provided. + +Look below for the example how to override the VNC/noVNC parameters at the container startup-time. + ### Overriding VNC/noVNC parameters The VNC/noVNC parameters are controlled by related environment variables embedded into the image. @@ -259,7 +275,7 @@ For example: docker build --build-arg DISPLAY=:2 --build-arg ARG_VNC_PORT=6902 ... ``` -**At container startup-time** you can override the environment variable values by using the `docker run -e` option. Please note that in this case you have to use the actual environment variable names, not the build argument names (e.g. `VNC_PORT` instead of `ARG_VNC_PORT`). +**At container creation-time** you can override the environment variable values by using the `docker run -e` option. Please note that in this case you have to use the actual environment variable names, not the build argument names (e.g. `VNC_PORT` instead of `ARG_VNC_PORT`). For example: @@ -267,29 +283,25 @@ For example: docker run -e VNC_PORT=6902 ... ``` -**At VNC/noVNC startup-time** you can override the environment variable values by binding an external file exporting the variables to the dedicated mounting point `${HOME}/.vnc_override.rc` (a single file, not a directory). +**At container startup-time** you can override the VNC/noVNC variables using the feature `FEATURES_OVERRIDING_ENVV' described above. For example, the following command would bind the file `my_own_vnc_parameters.rc` from the directory `/home/joe` to the container: ```shell -docker run -v /home/joe/my_own_vnc_parameters.rc:/home/headless/.vnc_override.rc +docker run -v /home/joe/my_own_vnc_parameters.rc:/home/headless/.override/.override_envv.rc ``` -The content of the file should be similar to the provided example file `example-vnc-override.rc`: +The content of the file should be similar to the provided example file `example-override-envv.rc`: ```shell -### only lines beginning with 'export ' (at position 1) will be imported and sourced -;export VNC_COL_DEPTH=32 -;export VNC_VIEW_ONLY=true -;export VNC_PW=secret +### only the lines beginning with 'export ' at the first position and containing '=' will be sourced export VNC_RESOLUTION=1024x768 -export DISPLAY=:2 -export VNC_PORT=5902 -export NOVNC_PORT=6902 -;export NOVNC_HEARTBEAT=25 +export VNC_PW=secret +#export DISPLAY=:2 +#export VNC_COL_DEPTH=32 ``` -Please note that only the lines beginning with `export` at the first position will be imported. +Please note that only the lines beginning with the string 'export ' at the first position and containing the '=' character will be imported. By providing the variable values the following rules apply: diff --git a/examples/Dockerfile.extend b/examples/Dockerfile.extend index fe8d2c9..5c65786 100644 --- a/examples/Dockerfile.extend +++ b/examples/Dockerfile.extend @@ -38,9 +38,13 @@ RUN \ # COPY ./bashrc "${HOME}"/.bashrc # COPY ./firefox.plus/user.js "${HOME}"/firefox.plus/ +### avoid the pitfall of failing startup under some circumstances +### permissions will be set to the system defaults on the first container start +RUN chmod 666 /etc/passwd /etc/group + ### usually you want to swich back to a non-root user ### alternatively you can do it in a compose file (see 'example.yml') -USER 1000 +USER "${HEADLESS_USER_ID}" ### note that some applications refuse to be installed under the root user ### those you have to install after switching the user diff --git a/examples/example-override-envv.rc b/examples/example-override-envv.rc new file mode 100644 index 0000000..25dea2c --- /dev/null +++ b/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 diff --git a/examples/example-secrets.rc b/examples/example-secrets.rc index 10ce64a..aa175fc 100644 --- a/examples/example-secrets.rc +++ b/examples/example-secrets.rc @@ -56,6 +56,7 @@ export DOCKER_BUILDKIT=1 ### explicitly disable features that are enabled by default # # export FEATURES_NOVNC=0 # # export FEATURES_FIREFOX_PLUS=0 +# # export FEATURES_OVERRIDING_ENVV=0 #endregion @@ -89,6 +90,7 @@ export DOCKER_BUILDKIT=1 # ### explicitly disable features that are enabled by default # # export FEATURES_NOVNC=0 # # export FEATURES_FIREFOX_PLUS=0 +# # export FEATURES_OVERRIDING_ENVV=0 #endregion diff --git a/examples/example-vnc-override.rc b/examples/example-vnc-override.rc deleted file mode 100644 index 2b33c93..0000000 --- a/examples/example-vnc-override.rc +++ /dev/null @@ -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