Headless Ubuntu/Xfce containers with VNC/noVNC

Project accetto/ubuntu-vnc-xfce-g3

Docker Hub - Changelog - Wiki - Discussions

This repository contains resources for building Docker images based on Ubuntu 20.04 LTS with Xfce desktop environment and VNC/noVNC servers for headless use.

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.

There are also sibling projects containing images for headless programming in Node.js and Python (accetto/headless-coding-g3) or headless diagramming, vector drawing and bitmap image editing (accetto/headless-drawing-g3).

TL;DR

There are currently resources for the following Docker images:

• accetto/ubuntu-vnc-xfce-g3
  • full Readme
  • Dockerfile (common for all images)
  • Dockerfile stages diagram (common for all images)
• accetto/ubuntu-vnc-xfce-chromium-g3
  • full Readme
• accetto/ubuntu-vnc-xfce-firefox-g3
  • full Readme

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 Ubuntu Packages Search page and install them subsequently.

You can also try to fix it by executing the following (the default sudo password is headless):

### apt cache needs to be updated only once
sudo apt-get update

sudo apt --fix-broken install

The fastest way to build the images locally:

### PWD = project root
./docker/hooks/build dev latest
./docker/hooks/build dev latest-chromium
./docker/hooks/build dev latest-firefox
./docker/hooks/build dev latest-firefox-plus
./docker/hooks/build dev vnc
./docker/hooks/build dev vnc-chromium
./docker/hooks/build dev vnc-firefox
./docker/hooks/build dev vnc-firefox-plus
### and so on

You can also use the provided helper script builder.sh, which can also publish the images on Docker Hub, if you correctly set the required environment variables (see the file example-secrets.rc). Check the files local-builder-readme.md and local-building-example.md.

Find more in the hook script env.rc and in Wiki.

Sharing the audio device for video with sound (only Linux and Chromium):

docker run -it -P --rm \
  --device /dev/snd:/dev/snd:rw \
  --group-add audio \
accetto/ubuntu-vnc-xfce-chromium-g3:latest

Table of contents

• Headless Ubuntu/Xfce containers with VNC/noVNC
  • Project accetto/ubuntu-vnc-xfce-g3
    • TL;DR
    • Table of contents
    • Image generations
    • Project goals
    • Changes and new features
      • Naming scheme
      • Slimmer images
      • Fewer and more flexible Dockerfiles
      • Concept of features
      • Overriding of container user parameters
      • Overriding of VNC/noVNC parameters
      • Different use of version sticker
      • Image metadata
      • Simple self-containing CI
      • Separated builder and deployment repositories
      • Separate README files for Docker Hub
      • Based on Ubuntu 20.04 LTS
      • Using TigerVNC 1.11
      • New startup script
  • Issues, Wiki and Discussions
  • Credits

Image generations

This is the third generation (G3) of my headless images. The second generation (G2) contains the GitHub repositories accetto/xubuntu-vnc and accetto/xubuntu-vnc-novnc. The first generation (G1) contains the GitHub repositories accetto/ubuntu-vnc-xfce, accetto/ubuntu-vnc-xfce-firefox, accetto/ubuntu-vnc-xfce-firefox-plus and accetto/ubuntu-vnc-xfce-chromium.

Project goals

Unlike the first two generations, this one aims to support CI. One of the main project goals has been to implement a simple and cheap self-containing CI with minimal dependencies outside the project itself. There are only three service providers used, all available for free:

• GitHub hosts everything required for building the Docker images. Both public and private repositories can be used. GitHub Gists are used for persisting data, e.g. badge endpoints. GitHub Actions are also used.

• Docker Hub hosts the Docker images and is also used for building them. Public or private repositories can be used.

• Badgen.net is used for generating and hosting most of the badges.

None of the above service providers is really required. Images can be built locally under Linux or Windows and published elsewhere.

Building process is implemented to minimize image pollution. New images are pushed to the repositories only if something essential has changed. This could be overridden if needed.

Changes and new features

Hint: More detailed information about new features can be found in Wiki.

Naming scheme

Unlike the first two generations, this one will aim to use less Docker Hub image repositories with more image tags. For example, previously there have been two Docker Hub repositories xubuntu-vnc and ubuntu-vnc-novnc. Now there will be only one Docker Hub repository accetto/ubuntu-vnc-xfce-g3 containing tags vnc and vnc-novnc.

Slimmer images

New images are significantly slimmer than the previous ones. It's because that the most of the packages are installed with the apt-get switch --no-install-recommends by default. This could have consequences, so it is configurable.

Fewer and more flexible Dockerfiles

Image variations are build from fewer Dockerfiles. This is allowed by using multi-stage builds and Buildkit. On the other hand, flexible and configurable Dockerfiles are slightly more complex.

Concept of features

Flexibility in Dockerfiles is supported by introducing the concept of features. These are variables that control the building process. For example, the variable FEATURES_BUILD_SLIM controls the --no-install-recommends switch, the variable FEATURES_NOVNC controls the inclusion of noVNC and so on. Some other available features include, for example, the FEATURES_SCREENSHOOTING, FEATURES_THUMBNAILING and FEATURES_USER_GROUP_OVERRIDE variables. Also the web browsers Chromium and Firefox are defined as features controlled by the variables FEATURES_CHROMIUM, FEATURES_FIREFOX and FEATURES_FIREFOX_PLUS.

Overriding of container user parameters

Several ways of overriding the container user parameters are supported. The application user name, home directory and password can be overridden at the image build-time. The user ID can be overridden at the container startup-time.

Support for overriding the user group by docker run has been introduced in the second generation. This feature is now controlled by the variable FEATURES_USER_GROUP_OVERRIDE.

Overriding of VNC/noVNC parameters

Several ways of overriding the VNC/noVNC parameters are supported. The password, display, resolution, color depth, view mode and the ports can be overridden at the image build-time, the container startup-time and the VNC startup-time. Using of empty VNC/noVNC password is also supported because it is independent from the container user password.

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 and here 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 packets.

Different use of version sticker

The concept of version sticker has been introduced in the second generation and later implemented also in the first generation. Check this Wiki page for more information. However, the usage of the version sticker has been changed in the third generation. Previously it has been used for testing, if there are some newer packages available by following the try-and-fail pattern. That was sufficient for human controlled building process, but it became a problem for CI. Therefore it is used differently now. The verbose version sticker is used for minimizing image pollution. The short form of the version sticker is available as an image label and a badge in the README file. The version sticker badge is also linked with the verbose version sticker gist, so it is possible to check the actual image configuration even without downloading it.

Image metadata

The image metadata are now stored exclusively as image labels. The previous environment variables like REFRESHED_AT or VERSION_STICKER have been removed. Most of the labels are namespaced according the OCI IMAGE SPEC recommendations. However, the version-sticker label is in the namespace any.accetto for obvious reasons.

Simple self-containing CI

The third generation implements a relatively simple self-containing CI by utilizing the Docker Hub builder hooks. The same build pipeline can be executed also manually if building locally. For example, an image can be refreshed by executing the /hooks/pre_build and /hooks/build scripts. The script /hooks/push will push the image to the deployment repository. The script /hooks/post_push will update the gist data and trigger the GitHub Actions workflow, which will publish the image's README file to Docker Hub.

Separated builder and deployment repositories

While there is only one GitHub repository, containing the resources for building all images, there are two kinds of repositories on Docker Hub. A single builder repository is used for building all images. The final images are then published into one or more deployment repositories. This separation allows to keep permutations by naming reasonable. Not all repositories must have the same visibility, they can be private or public as required. The same repository could be also used for building and deployment.

Separate README files for Docker Hub

Each deployment repository has its own README file for Docker Hub, which is published by CI workflows after the image has been pushed. The file is split into parts. The part containing the badge links is separated into a template file. The final README file is then generated by the script just before publishing. Re-publishing can be forced even if the image has not been actually refreshed. These README files are shorter, because their length is limited by Docker Hub. Therefore there are also full-length README files published only on GitHub.

Based on Ubuntu 20.04 LTS

The current images are based on the official Ubuntu 20.04 LTS image.

Using TigerVNC 1.11

The images use the latest TigerVNC 1.11.0 server, which has introduced some significant changes in its startup process. Actually the images implement the newer TigerVNC nightly builds, that fix or mitigate some of the issues.

New startup script

The startup script has been completely redesigned with the help of argbash tool and the image accetto/argbash-docker. Several new startup switches has been added. For example, there are startup switches --wait, --skip-startup, --tail-null, --tail-vnc, --version-sticker and --version-sticker-verbose. There are also startup modifiers --skip-vnc, --skip-novnc, --debug and --verbose. Also the utility switches --help-usage, --help and --version are available.

Issues, Wiki and Discussions

If you have found a problem or you just have a question, please check the Issues and the 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 Discussions.

Credits

Credit goes to all the countless people and companies, who contribute to open source community and make so many dreamy things real.