aviel770/qnap repository overview

⁠Ubuntu Dev Desktop with VNC

A lightweight Ubuntu 22.04 desktop environment running inside a Docker container, accessible remotely through any standard VNC client.

This image provides an isolated Linux graphical environment for development, testing, training, automation, and experimenting with Linux applications without modifying the host operating system.

⁠Main Features

• Ubuntu 22.04 base image • Lightweight XFCE desktop environment • TigerVNC server preconfigured • Automatic VNC and XFCE startup • Non root dev user • Passwordless sudo access for the development user • Configurable screen resolution • Persistent workspace volume support • Optional Visual Studio Code GUI • Compatible with Linux, macOS, and Windows hosts • No host X11 server required

⁠Quick Start

Pull the image:

docker pull aviel770/qnap:v1

Run the container:

docker run -d \
  --name dev-desktop-vnc \
  -p 5901:5901 \
  -e VNC_PASSWORD=changeme \
  -e RESOLUTION=1920x1080 \
  -v "$(pwd)/workspace:/workspace" \
  aviel770/qnap:v1

Check that the container is running:

docker ps

⁠Connect with VNC

Use a VNC client such as RealVNC, Remmina, TightVNC, or UltraVNC.

Connection details:

Host: 127.0.0.1
Port: 5901
Password: changeme

Change the default password before using the container on a shared or remotely accessible network.

⁠Docker Compose Example

services:
  devdesktop:
    image: <dockerhub-username>/dev-desktop-vnc:latest
    container_name: dev-desktop-vnc
    ports:
      - "5901:5901"
    environment:
      VNC_PASSWORD: "replace-with-a-strong-password"
      RESOLUTION: "1920x1080"
      DISPLAY_NUM: "1"
    volumes:
      - ./workspace:/workspace
    restart: unless-stopped

Start the environment:

docker compose up -d

View its status:

docker compose ps

View logs:

docker compose logs -f

Stop and remove the container:

docker compose down

⁠Configuration

⁠VNC Password

Set the VNC password using the VNC_PASSWORD environment variable:

-e VNC_PASSWORD="your-strong-password"

The default password is:

changeme

For security, always replace the default password.

⁠Screen Resolution

Set the desktop resolution using the RESOLUTION environment variable:

-e RESOLUTION="2560x1440"

The default resolution is:

1920x1080

⁠Display Number

Set the VNC display number:

-e DISPLAY_NUM="1"

Display 1 is exposed through TCP port 5901.

⁠Persistent Workspace

Mount a local directory into /workspace:

-v "$(pwd)/workspace:/workspace"

Files stored in this directory remain available after the container is recreated.

⁠Common Use Cases

• Remote Linux GUI development environment • Isolated desktop for Linux experimentation • Development and automation training • GUI application testing • Temporary Linux desktop for Windows and macOS users • Running graphical development tools without installing them locally • Reproducible classroom or laboratory environments • Testing scripts and software in a disposable environment

⁠Useful Commands

Open a shell inside the container:

docker exec -it dev-desktop-vnc bash

Restart the container:

docker restart dev-desktop-vnc

View container logs:

docker logs -f dev-desktop-vnc

Check the exposed port:

docker port dev-desktop-vnc

List active VNC sessions from inside the container:

vncserver -list

Stop a VNC session:

vncserver -kill :1

⁠Troubleshooting

⁠VNC Connection Refused

Confirm that the container is running:

docker ps

Check the published port:

docker port dev-desktop-vnc

Test the local VNC port:

nc -vz 127.0.0.1 5901

⁠Desktop Does Not Start

Review the container logs:

docker logs dev-desktop-vnc

Enter the container and inspect the VNC logs:

docker exec -it dev-desktop-vnc bash
cat ~/.vnc/*.log

⁠Permission Problems in the Workspace

Check the ownership and permissions of the mounted host directory:

ls -ld workspace

The desktop runs as the non root dev user, so mounted files must be accessible to that user.

⁠Security Notes

• Replace the default VNC password immediately • Do not expose port 5901 directly to the public internet • Prefer SSH tunneling, a VPN, or a private network for remote access • Mount only directories that the container needs • Avoid storing secrets directly inside the image • Regularly rebuild the image to receive operating system security updates

⁠Source Code

The Dockerfile, startup scripts, Docker Compose configuration, installation scripts, and full documentation are available in the GitHub project:

https://github.com/Aviel-Amitay/docker-dev-desktop-vnc