docker-headless-vnc-container: Docker images with Xfce4 or IceWM desktops on Rocky and Debian

Four images: Rocky 9 and Debian 11 each paired with Xfce4 or IceWM

The project ships four images organized as a matrix of two OS bases against two desktop environments. Rocky 9 is available with both Xfce4 (consol/rocky-xfce-vnc) and IceWM (consol/rocky-icewm-vnc). Debian 11 has the same two options: consol/debian-xfce-vnc and consol/debian-icewm-vnc. Xfce4 is a full desktop environment with a panel and file manager; IceWM is a lighter window manager intended for lower-resource scenarios. Robert Bohne contributed the IceWM images, as listed in the contributors section.

Every image ships with Mozilla Firefox and Chromium, making the images practical for running browser tests or inspecting graphical applications that require a display. Each image exposes VNC on port 5901 and the noVNC HTML5 client on port 6901. noVNC lets you reach the desktop from a browser tab without installing a VNC viewer separately.

noVNC serves two pages on port 6901: /vnc.html opens a full-featured browser interface, while /?password=vncpassword is a stripped-down client that embeds the password directly in the URL. Both paths reach the same desktop session. The README lists vncpassword as the default connection password in the Connect section, while the environment variable section lists VNC_PW with a default of my-pw. The README does not clarify which value takes precedence, so setting VNC_PW explicitly before exposing any port to an untrusted network is the more cautious approach.

Starting a container and connecting via VNC viewer or noVNC browser client

To start the Rocky Xfce4 image with both ports forwarded, in detached mode:

docker run -d -p 5901:5901 -p 6901:6901 consol/rocky-xfce-vnc

Once the container is running, connect to localhost:5901 with a VNC viewer or open http://localhost:6901/vnc.html in a browser. Port 5901 is the standard VNC protocol port, which any VNC client can reach. Port 6901 serves noVNC, which requires only a browser.

For an interactive shell alongside the graphical session:

docker run -it -p 5901:5901 -p 6901:6901 consol/rocky-xfce-vnc bash

To print the image's own help text listing its startup options:

docker run consol/rocky-xfce-vnc --help

Substituting any of the other three image names, consol/debian-xfce-vnc, consol/rocky-icewm-vnc, or consol/debian-icewm-vnc, follows the same flag and port mapping pattern. Kubernetes and OpenShift deployments have separate README files in the kubernetes/ and openshift/ subdirectories. Those cover running the containers in cluster environments, but their content is not summarized in the main README. Reading those subdirectory READMEs directly is necessary before attempting a cluster deployment, because port mapping, resource limits, and storage configuration in a cluster differ substantially from a local docker run.

VNC_RESOLUTION, VNC_PW, VNC_COL_DEPTH, and VNC_VIEW_ONLY configure the session at startup

Four environment variables customize the desktop session. VNC_RESOLUTION controls the display size and defaults to 1280x1024. VNC_COL_DEPTH controls color depth and defaults to 24. VNC_PW sets the VNC password. VNC_PASSWORDLESS, which is not set by default, disables password authentication when set to true.

To set a custom resolution:

docker run -it -p 5901:5901 -p 6901:6901 -e VNC_RESOLUTION=800x600 consol/rocky-xfce-vnc

To set a specific VNC password:

docker run -it -p 5901:5901 -p 6901:6901 -e VNC_PW=my-pw consol/rocky-xfce-vnc

VNC_VIEW_ONLY, available since v1.2.0, puts the VNC connection into observation mode. Setting it to true causes the startup script to assign a random password to the control channel, while the VNC_PW value is assigned to the view-only channel. An observer connecting with VNC_PW can see the screen but cannot send keyboard or mouse input. This is useful for demos or monitored sessions. Regarding VNC_PASSWORDLESS: the README advises placing some kind of authorization layer in front of the container before enabling it, since removing the VNC password makes the desktop accessible to any host that can reach port 5901.

Non-root by default since v1.1.0, and switching to root for package installs in derived images

Version 1.1.0 changed the default for all images to a non-root user. Version 1.3.0 fixed that default user at id 1000 across all container processes. Extending the image to add software requires switching to user 0 in the Dockerfile:

FROM consol/rocky-xfce-vnc
ENV REFRESHED_AT 2022-10-12

USER 0
RUN yum install -y gedit \
    && yum clean all
USER 1000

This switches to root for the install step and back to user 1000 afterward. Omitting the final USER 1000 instruction leaves the derived image running as root, which undermines the non-root default.

For a running container, passing --user to docker run overrides the default. To run as root:

docker run -it --user 0 -p 6911:6901 consol/rocky-xfce-vnc

To map the container user to the host's own user and group id:

docker run -it -p 6911:6901 --user $(id -u):$(id -g) consol/rocky-xfce-vnc

Note that these examples use 6911 as the host port, which differs from the 6901:6901 mapping in the basic run examples. This is intentional in the README to illustrate that host ports are arbitrary; the container port is always 6901 for noVNC.

Chromium crashes above the default resolution without --shm-size=256m

One known issue is documented in the README. At resolutions like 1920x1080, graphics-heavy pages in Chromium can trigger a crash with no meaningful error output. Docker containers start with a small /dev/shm allocation, and that is the resource Chromium exhausts: it relies on shared memory for its GPU subprocess communication, and once /dev/shm is full the browser exits. Issue #53 tracks this, credited to contributor @raghavkarol.

The documented fix is to add --shm-size=256m to the docker run command:

docker run --shm-size=256m -it -p 6901:6901 -e VNC_RESOLUTION=1920x1080 consol/rocky-xfce-vnc chromium-browser http://map.norsecorp.com/

At the default resolution of 1280x1024, the issue is not documented. The README does not address whether intermediate resolutions trigger the same crash, only that --shm-size=256m resolves it for 1920x1080. Firefox is not mentioned as affected.

For automation scenarios that run Chromium and open multiple JavaScript-heavy pages, adding --shm-size=256m is worth doing as a precaution at any resolution, since the symptoms (a crash with no clear message) make it hard to diagnose after the fact.

Building images from source with the four root-level Dockerfiles

For building images locally rather than pulling from a registry, four Dockerfiles sit at the repository root: Dockerfile.debian-icewm-vnc, Dockerfile.debian-xfce-vnc, Dockerfile.rocky-icewm-vnc, and Dockerfile.rocky-xfce-vnc. To build the Rocky Xfce4 image:

docker build -t consol/rocky-xfce-vnc rocky-xfce-vnc

The src/ directory holds shared scripts and configuration that the Dockerfiles reference during the build. A nightly CI workflow defined in .github/ runs the build automatically.

Each image variant maps to a specific Makefile target as well. The Makefile at the repository root defines build-debian-xfce-vnc, build-debian-icewm-vnc, build-rocky-xfce-vnc, and build-rocky-icewm-vnc for building, and matching run-* targets for running with --rm so containers clean up after exit. A test target at the Makefile root delegates to the t/ subdirectory, though the README does not describe what tests are there. For release procedures, how-to-release.md at the repository root documents the process.

A t/ directory for tests and an update_refreshed_at.sh script are also present at the root, both suggesting ongoing maintenance tooling beyond what the README describes.

v2.0.4 in September 2024, Apache-2.0, and the gap between the release tag and the last push

Three GitHub releases have been published: v2.0.0 and v2.0.1 both on 2022-11-02, and v2.0.4 on 2024-09-10. The last push to the repository was on 2026-08-03. That 22-month gap between the most recent release tag and the most recent commit means the repository head contains changes not captured in any release. A changelog.md file at the repository root covers the change history, but its contents are not reproduced in the README. Before pinning to a specific tag in production, reading changelog.md is the only way to understand what those unpublished commits changed.

For anyone deploying to Kubernetes or OpenShift, the subdirectory READMEs at kubernetes/ and openshift/ may contain version-specific instructions that differ from the main README. Checking those before a cluster deployment avoids surprises.

License is Apache-2.0. The LICENSE file is at the repository root. Apache-2.0 permits commercial use, redistribution, and modification with attribution. Derived images that add proprietary software on top of the base keep the Apache-2.0 terms on the container scripts, but the licenses of installed packages apply independently. Chromium and Firefox each carry their own licenses inside the image, and the terms under which they can be redistributed depend on those licenses, not on the container project's Apache-2.0 grant.

Editorial conclusion

docker-headless-vnc-container suits teams that need a graphical desktop in a container, accessible over VNC or a browser on Rocky 9 or Debian 11. Use noVNC at http://localhost:6901/vnc.html to avoid installing a separate VNC viewer. Before running Chromium at resolutions above 1280x1024, add --shm-size=256m to docker run, because the container's /dev/shm is otherwise too small for Chromium at high resolutions. Skip it if you need GPU acceleration or kernel-level display features, because the README does not mention those capabilities.

Frequently asked questions

Official sources

1. ConSol/docker-headless-vnc-container on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases