Docker/Singularity image for Ubuntu with X11 and VNC
This repository offers a Docker/Singularity image for Ubuntu with X11 and VNC. It can be useful in delivering a unified environment for teaching programming classes, demonstrating graphical user interface, developing and debugging software programs (such as using Visual Studio Code
), and visualizing simultion results on high-performance computing (HPC) platforms (such as using ParaView
). It shares some similarity to fcwu/docker-ubuntu-vnc-desktop, but with several enhancements on security and features, especially for software developers and HPC users:
-t zh_CN
to the command-line option for x11vnc_desktop.py
)Before you start, you need to first install Python 3.x and Docker on your computer by following the steps below.
If you use Linux or Mac, Python 3.x is most likely already installed on your computer, so you can skip this step.
If you use Windows, you need to install Python if you have not yet done so. The easiest way is to install Miniconda
, which you can download at https://repo.continuum.io/miniconda/Miniconda3-latest-Windows-x86_64.exe. During installation, make sure you check the option to make Miniconda the system's default Python.
Download Docker Desktop for free at https://docs.docker.com/get-docker/ and then run the installer. Note that you need administrator's privilege to install Docker. After installation, make sure you launch Docker before proceeding to the next step.
Notes for Windows Users
Notes for Mac Users
Preferences
and then select the Advanced
tab to adjust the settings.Notes for Linux Users
docker
package. You can use the package installer for your system to install docker
. Note that on some system (e.g., OpenSUSE), you may need to run the following commands to start up docker
after installing docker
:sudo systemctl enable docker
sudo systemctl start docker
docker
group. On Ubuntu, this is done by running the command:sudo adduser $USER docker
On other systems, try the following command.
sudo usermod -G docker -a $USER
After adding yourself to the docker
group, you need to log out and log back in before you can use Docker.
To run the Docker image, first download the script x11vnc_desktop.py
and save it to the working directory where you will store your codes and data. You can download the script using the command line: On Windows, start Windows PowerShell
, use the cd
command to change to the working directory where you will store your codes and data, and then run the following command:
curl https://raw.githubusercontent.com/x11vnc/x11vnc-desktop/main/x11vnc_desktop.py -outfile x11vnc_desktop.py
On Linux or Mac, start a terminal, use the cd
command to change to the working directory, and then run the following command:
curl -s -O https://raw.githubusercontent.com/x11vnc/x11vnc-desktop/main/x11vnc_desktop.py
After downloading the script, you can start the Docker image using the command
python3 x11vnc_desktop.py -p
This will download and run the Docker image and then launch your default web browser to show the desktop environment. The -p
option is optional, and it instructs the Python script to pull and update the image to the latest version. The work directory by default will be mapped to the current working directory on your host.
To use the Chinese localization, use the command
python3 x11vnc_desktop.py -t zh_CN
For additional command-line options, use the command
python3 x11vnc_desktop.py -h
To build your own image, run the following commands:
git clone https://github.com/x11vnc/x11vnc-desktop.git
docker build --rm -t x11vnc/docker-desktop x11vnc-desktop
and then use the x11vnc_desktop.py
command.
This Docker image is constructed to be compatible with Singularity. This has been tested with Singularity v3.5. If your system does not yet have Singularity, you may need to install it by following these instructions. You must have root access to install Singularity, but you can use Singularity as a regular user after it has been installed. If you do not have root access, such as on an HPC platform, ask your system administrator to install Singularity for you. It is recommended you use Singularity v2.6 or later.
To use the Docker image with Singularity, please issue the command
singularity run -c -B $HOME -B /tmp docker://x11vnc/docker-desktop:latest
It will automatically mount some minimal /dev directories and $HOME in Singularity
but does not mount most others (such as /run). If you do not want to
mount your home directory, then remove the -B $HOME
option.
Alternatively, if you use Singularity v3.x, you may use the commands
singularity pull x11vnc-desktop:latest.sif docker://x11vnc/docker-desktop:latest
singularity run -c -B $HOME -B /tmp ./x11vnc-desktop:latest.sif
Notes regarding Singularity:
zsh
user, you may need to edit your .zshrc
and .zprofile
to work both on the host and in the Singularity image.You are welcome to fork the project and customize it for your own purpose. This repository uses Github Actions to build the Docker images automatically and then push the images onto Docker Hub. For Github Actions to work in your fork correctly, please do the following three steps:
DOCKER_HUB_USERNAME
to your Docker username.DOCKER_HUB_USERNAME
and DOCKER_HUB_ACCESS_TOKEN
to your Docker Hub username and password. You can find
some detailed instructions about getting Docker Hub access token at
https://docs.docker.com/ci-cd/github-actions/.docker-desktop
in your Docker Hub
account so that the built images can be pushed into your Docker Hub account.Pull requests are also welcome. Please make sure your changes have passed the GitHub Actions CI for the pull request.
The x11vnc-desktop
project was developed by Xiangmin Jiao as a tool for teaching and research at Stony Brook University. Note that this project is independent of the LibVNC/x11vnc project.
See the LICENSE file for details.