Version: G3v9
User Guide - Docker Hub - Changelog - sibling Wiki - sibling Discussions
This GitHub repository contains resources and tools for building Docker images for headless working.
The images are based on the current Debian 13 and include Xfce desktop, TigerVNC server and noVNC client. The popular web browsers Brave, Chromium and Firefox are also included.
This User guide describes the images and how to use them.
The content of this GitHub project is intended for developers and image builders.
Ordinary users can simply use the images available in the following repositories on Docker Hub:
- accetto/debian-vnc-xfce-nodejs-g3
- accetto/debian-vnc-xfce-nvm-g3
- accetto/debian-vnc-xfce-postman-g3
- accetto/debian-vnc-xfce-python-g3
- accetto/debian-vnc-xfce-vscode-g3
This is a sibling project to the project accetto/debian-vnc-xfce-g3.
You can execute the individual hook scripts in the folder /docker/hooks/. However, the provided utilities are more convenient.
The script builder.sh builds individual images. The script ci-builder.sh can build various groups of images or all of them at once.
Before building the images you have to prepare and source the file secrets.rc (see example-secrets.rc).
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).
The resources for building the individual images and their variations (tags) are in the subfolders of the /docker/ folder.
The individual README files contain quick examples of building the images:
- accetto/debian-vnc-xfce-nodejs-g3
- accetto/debian-vnc-xfce-nvm-g3
- accetto/debian-vnc-xfce-postman-g3
- accetto/debian-vnc-xfce-python-g3
- accetto/debian-vnc-xfce-vscode-g3
Each image also has a separate README file intended for Docker Hub. The final files should be generated by the utility util-readme.sh and then copied to Docker Hub manually.
The following resources describe the image building subject in details:
- readme-local-building-example.md
- readme-builder.md
- readme-ci-builder.md
- readme-g3-cache.md
- readme-util-readme-examples.md
- sibling Wiki
This is the third generation (G3) of my headless images. The second generation (G2) contains the GitHub repository accetto/xubuntu-vnc-novnc. The first generation (G1) contains the GitHub repository accetto/ubuntu-vnc-xfce.
This file describes the ninth version (G3v9) of the project, which brings the following changes.
It goes around the problem with the current containerd and the improved building pipeline, which has been introduced in the release 25.05 (G3v8). See also the feedback-issue-603.
Since the Docker Desktop option Use containerd for pulling and storing images has been introduced some time ago, the command docker build --cache-from=<local-helper-image-used-as-cache> ignores the local helper image if the option is enabled.
It always tries to pull the cache image from the registry instead of using the local image.
The new version uses the local file system for caching the helper images. This option seems to perform better and it is easier to maintain than the other possible option with a local registry.
The path to the local helper cache is configurable via the environment variable HELPER_IMAGE_CACHE_PATH.
The variable is expected to be set in the file hooks/secrets.rc.
The default value is ./.buildx-cache.
The local cache is automatically cleaned during the building.
The usage of the stage_cache layers has been also improved in all Dockerfiles, avoiding possible stale cache data.
Also the optional building parameter --pull has been introduced for both builder scripts builder.sh and ci-builder.sh.
It prevents builds from relying only on a possibly stale local base image.
The new version also introduces a possibility to override the result of the hook script release_of by setting the environment variables like RELEASE_OF_OVERRIDE_nvm and similar.
Note that the postman is still pinned in any case directly in the script release_of to the version 10.13.6, which is the last version still containing Scratch Pad.
Please note that the project keeps evolving, so always check the CHANGELOG for the latest changes.
The previous versions are still available in this GitHub repository as the branches named as archived-generation-g3v{d}.
The version G3v8 has brought some changes in the building pipeline and building utilities and it also fixes the problem with the badge service.
The service Badgen.net, which has been unusable for some time already, was replaced by the service Shields.io.
Consequently it was necessary to update all README files of all accetto repositories on Docker Hub. Therefore there were several new functions that supported that kind of scenarios.
For example, it was possible to update the deployment gists on the GitHub without re-build the images first. The updated hook script post_push could extract the badge values ad-hoc from the final deployment images available locally and it didn't depend on the helper files created during the pre_build phase. It could use the images pulled from the Docker Hub as well.
The change made it possible to refresh the gists using the "historical" data extracted from previously published images.
Gist updates were made also more reliable because there were be up to 3 retries if an update failed.
The new functionality was available through the updated utility ci-builder.sh, which has got the following new commands:
listpullupdate-gistshelper-help
The files readme-ci-builder.md and readme-builder.md described the changes.
The version G3v7 could build final images significantly faster, because the temporary helper images were used as external caches.
Internally, the helper image was built by the pre_build hook script and then used by the build hook script as an external cache.
The helper image was then removed by the build hook script and not the pre_build hook script as before, unless the build script will be skipped.
The main purpose of the version G3v6 was to keep the project and the images uniform with the ones from the sibling Ubuntu projects.
The version G3v5 has brought only one significant change comparing to the previous version G3v3 and it also introduces the portable Visual Studio Code installation.
- The updated script
set_user_permissions.sh, which is part of Dockerfiles, skips the hidden files and directories now. It generally should not have any unwanted side effects, but it may make a difference in some scenarios, hence the version increase.
Remark: The version number G3v4 has been skipped, to align the numbering with the sibling project accetto/ubuntu-vnc-xfce-g3.
The version G3v3 has brought the following major changes comparing to the previous version G3v2:
- The updated startup scripts that support overriding the user ID (
id) and group ID (gid) without needing the former build argumentARG_FEATURES_USER_GROUP_OVERRIDE, which has been removed. - The user ID and the group ID can be overridden during the build time (
docker build) and the run time (docker run). - The
user name, thegroup nameand theinitial sudo passwordcan be overridden during the build time. - The permissions of the files
/etc/passwdand/etc/groupsare set to the standard644after creating the user. - The content of the home folder and the startup folder belongs to the created user.
- The created user gets permissions to use
sudo. The initialsudopassword is configurable during the build time using the build argumentARG_SUDO_INITIAL_PW. The password can be changed inside the container. - The default
id:gidhas been changed from1001:0to1000:1000. - Features
NOVNCandFIREFOX_PLUS, that are enabled by default, can be disabled via environment variables. - If
FEATURES_NOVNC="0", then- image will not include
noVNC - image tag will get the
-vncsuffix (e.g.latest-vnc,20.04-firefox-vncetc.)
- image will not include
- If
FEATURES_FIREFOX_PLUS="0"andFEATURES_FIREFOX="1", then- image with Firefox will not include the Firefox Plus features
- image tag will get the
-defaultsuffix (e.g.latest-firefox-defaultor alsolatest-firefox-default-vncetc.)
- The images are based on
Debian 11(formerly onUbuntu 20.04 LTS).
The version G3v2 has brought the following major changes comparing to the previous version G3v1:
- Significantly improved building performance by introducing a local cache (
g3-cache). - Auto-building on the Docker Hub and using of the GitHub Actions have been abandoned.
- The enhanced building pipeline moves towards building the images outside the Docker Hub and aims to support also stages with CI/CD capabilities (e.g. the GitLab).
- The local stage is the default building stage now. However, the new building pipeline has already been tested also with a local GitLab installation in a Docker container on a Linux machine.
- Automatic publishing of README files to the Docker Hub has been removed, because it was not working properly any more.
However, the README files for the Docker Hub can still be prepared with the provided utility
util-readme.shand then copy-and-pasted to the Docker Hub manually.
The changes affect only the building pipeline, not the Docker images themselves.
The Dockerfile, apart from using the new local g3-cache, stays conceptually unchanged.
Please refer to the sibling project to learn more about the older project versions.
Please refer to the sibling project to learn more about the project goals.
Please refer to the sibling project to learn more about the project features.
If you want to fork this project, then please check the page How to fork this repository in the sibling Wiki.
If you have found a problem or you just have a question, please check the User guide, Issues and the 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.
Credit goes to all the countless people and companies, who contribute to open source community and make so many dreamy things real.