Docker Hub - Git Hub - Changelog - Wiki
Attention: Resources for building images with Firefox and configurable Firefox, previously contained in this repository, have been moved to their own GitHub repositories ubuntu-vnc-xfce-firefox and ubuntu-vnc-xfce-firefox-plus.
This repository contains resources for building Docker images based on Ubuntu, with Xfce desktops and headless VNC/noVNC environments.
This image can be successfully built and used on Linux, NAS devices and Windows.
It has been tested with Docker CE on Ubuntu flavours, with Container Station on a NAS from QNAP and with Docker for Windows on Windows 10.
The image is also used as the base image for other Docker images with additional features (e.g. accetto/ubuntu-vnc-xfce-firefox-default or accetto/ubuntu-vnc-xfce-firefox-plus).
Running containers in background is the primary scenario this image has been developed for. However, running in foreground can be useful in many cases. See the description below for examples of using the containers both ways.
Containers created from this image are perfect for learning, testing or development, because they can be used headless over VNC using a VNC Viewer (e.g. TigerVNC] or TightVNC) or directly from a web browser over noVNC. Any web browser supporting HTML5 can be used. Both lite and full noVNC clients are provided.
It should be noticed, that containers created from this image do not include any web browser and that they run under the privileged root user (container's root) by default. However, the graphical editor mousepad and the text editor vim are already included and other applications can be added by the user easily.
It should be also noticed, that the container's root is not the same as the host's root and that he does not automatically get the same privileges on the hosting computer. Please check the Docker documentation for more information (e.g. Runtime privilege and Linux capabilities).
The image contains the following components:
- light-weight Xfce desktop environment
- high-performance VNC server TigerVNC (TCP port 5901)
- noVNC HTML5 clients (full and lite) (TCP port 6901)
- popular text editor vim
- lite but advanced graphical editor mousepad
The image is regularly maintained and rebuilt. The history of notable changes is documented in CHANGELOG.
-
Images based on the official ubuntu images.
Following TCP ports are exposed:
- 5901 used for access over VNC
- 6901 used for access over noVNC
The default VNC user password is headless.
The images do not create or use any external volumes by default. However, the following folders make good mounting points:
- /home/headless/Documents/
- /home/headless/Downloads/
- /home/headless/Music/
- /home/headless/Pictures/
- /home/headless/Public/
- /home/headless/Templates/
- /home/headless/Videos/
Both named volumes and bind mounts can be used. More about volumes can be found in the Docker documentation (e.g. Manage data in Docker).
Created containers run under the privileged root user by default. However, it's the container's root, which is not the same as the root of the hosting computer (see above).
The following container will listen on automatically selected TCP ports of the host computer:
docker run -d -P accetto/ubuntu-vnc-xfce
The following container will listen on the host's explicit TCP ports 25901 (VNC) and 26901 (noVNC):
docker run -d -p 25901:5901 -p 26901:6901 accetto/ubuntu-vnc-xfce
The following container will create or re-use the local named volume my_Downloads mounted as /headless/Downloads
:
docker run -d -P -v my_Downloads:/home/headless/Downloads accetto/ubuntu-vnc-xfce
or using the newer syntax with --mount flag:
docker run -d -P --mount source=my_Downloads,target=/home/headless/Downloads accetto/ubuntu-vnc-xfce
More usage examples can be found in Wiki (section HOWTO).
The image supports the following container start-up options: --wait
(default), --skip
, --debug
(also --tail-log
) and --help
.
The following container will print out the help and then it'll remove itself:
docker run --rm accetto/ubuntu-vnc-xfce --help
Excerpt from the output, which describes the other options:
OPTIONS:
-w, --wait (default) Keeps the UI and the vnc server up until SIGINT or SIGTERM are received.
An optional command can be executed after the vnc starts up.
example: docker run -d -P accetto/ubuntu-vnc-xfce
example: docker run -it -P accetto/ubuntu-vnc-xfce /bin/bash
-s, --skip Skips the vnc startup and just executes the provided command.
example: docker run -it -P accetto/ubuntu-vnc-xfce --skip /bin/bash
-d, --debug Executes the vnc startup and tails the vnc/noVNC logs.
Any parameters after '--debug' are ignored. CTRL-C stops the container.
example: docker run -it -P accetto/ubuntu-vnc-xfce --debug
-t, --tail-log same as '--debug'
-h, --help Prints out this help.
example: docker run --rm accetto/ubuntu-vnc-xfce
It should be noticed, that the --debug
start-up option does not show the command prompt even if the -it
run arguments are provided. This is because the container is watching the incoming vnc/noVNC connections and prints out their logs in real time. However, it is easy to attach to the running container like in the following example.
In the first terminal window on the host computer, create a new container named foo:
docker run --name foo accetto/ubuntu-vnc-xfce --debug
In the second terminal window on the host computer, execute the shell inside the foo container:
docker exec -it foo /bin/bash
There are two ways, how to use the created headless containers. Note that the default VNC user password is headless.
To be able to use the containers over VNC, a VNC Viewer is needed (e.g. TigerVNC or TightVNC).
The VNC Viewer should connect to the host running the container, pointing to the host's TCP port mapped to the container's TCP port 5901.
For example, if the container has been created on the host called mynas
using the parameters described above, the VNC Viewer should connect to mynas:25901
.
To be able to use the containers over noVNC, an HTML5 capable web browser is needed. It actually means, that any current web browser can be used.
The browser should navigate to the host running the container, pointing to the host's TCP port mapped to the container's TCP port 6901.
However, since the version 1.2.0 the containers offer two noVNC clients. Additionally to the previously available lite client there is also the full client with more features. The connection URL differs slightly in both cases. To make it easier, a simple startup page is implemented.
If the container have been created on the host called mynas
using the parameters described above, then the web browser should navigate to http://mynas:26901
.
The startup page will show two hyperlinks pointing to the both noVNC clients:
http://mynas:26901/vnc_lite.html
http://mynas:26901/vnc.html
It's also possible to provide the password through the links:
http://mynas:26901/vnc_lite.html?password=headless
http://mynas:26901/vnc.html?password=headless
If you have found a problem or just have a question, please check the Issues and the Troubleshooting, FAQ and HOWTO pages in 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.
This project has been originally inspired by the docker image consol/ubuntu-xfce-vnc and derived from its GitHub repository ConSol/docker-headless-vnc-container.
Credit also goes to all the countless people and companies who contribute to open source community and make so many dreamy things real.