Skip to content
NatLeePublic

Repository files navigation

The Dev Dock family: dev-dock builds the gui-vnc desktop image; dev-dock-manager (Django) and dev-dock-manager-rust (Rust) include it as the gui/ submodule and start one gui-vnc container per environment through the Docker socket

CI Docker pulls License: MIT

Dev Dock (GUI)

Dev Dock is a Docker image with a whole Linux desktop inside: Xfce on Debian, VS Code, Firefox, Miniconda and the usual command-line tools. You open the desktop in a browser (noVNC), in any VNC client, or skip the desktop and SSH in. Build it once, start as many containers as you like, and everyone gets the same dev box.

Supports x86_64 and arm64 (aarch64). Build the image on the same architecture as the host so Firefox and VS Code run natively.

The Xfce desktop in a browser, with Firefox, VS Code, a file manager and htop open

The Dev Dock family

This repo is the image. Two sibling repos turn it into a small self-hosted service where each person logs in and gets their own desktop container on one machine:

Repo What it is
dev-dock (this repo) Builds the gui-vnc image: desktop, VNC, noVNC and SSH in one container.
dev-dock-manager-rust Recommended. Web dashboard with a Rust API: per-user desktops, user management.
dev-dock-manager The older version of the same dashboard, with a Django (Python) API.

If you're setting this up today, use the Rust manager. Its README has the measured differences (image size, memory, startup time, response times). Both managers include this repo as their gui/ git submodule and build gui-vnc from it. When someone clicks "create", the manager starts a gui-vnc container through the Docker socket, publishes only its SSH port, and puts its noVNC page behind Traefik (a reverse proxy) at /novnc/<name>/. Everything else about the container is what this README describes.

How it works

Build: debian:bookworm-slim plus six install scripts gives the gui-vnc image. Run: supervisord starts docker-entrypoint.sh (VNC server on 5901 as DEFAULT_USER, noVNC on 6901) and sshd on 22; compose maps them to host ports 12345, 13579 and 24680

Building runs six scripts on top of debian:bookworm-slim, in order: user setup, OS packages and fonts, the desktop and VNC, VS Code / Firefox / AnyDesk, Miniconda, and permissions. TigerVNC comes from the bundled vnc-tools/tigervnc-1.16.0.x86_64.tar.gz on x86_64 and from Debian's packages on arm64.

Starting a container runs supervisord, which keeps two programs alive:

  • docker-entrypoint.sh sets the passwords from the environment, starts the VNC server on display :1 (port 5901) as DEFAULT_USER, runs Xfce in it, and starts noVNC on port 6901, which turns the VNC session into a web page.
  • sshd on port 22, with password login. root can log in too.

The desktop runs as DEFAULT_USER, not as root, so its home is /home/<DEFAULT_USER>. Passwords are applied on every start, so a container picks up new values after you recreate it with different environment variables.

What's inside

  • Xfce desktop (lightweight)
  • TigerVNC (port 5901) + noVNC (port 6901, browser access)
  • OpenSSH (port 22)
  • VS Code (launched with --no-sandbox for container compatibility)
  • Firefox
  • AnyDesk
  • Miniconda in /opt/conda
  • fcitx5 Chinese input (e.g. Pinyin); use fcitx5-configtool to add or switch input methods
  • Git, vim, tmux, htop and other common dev tools

Build and run

Build on the same architecture as the host (e.g. on Apple Silicon, build there) to avoid "Dynamic loader not found" for Firefox/VS Code.

docker compose build
docker compose up -d

Be patient with the first build: it downloads a few hundred packages plus VS Code, Firefox and Miniconda. On GitHub's runners a clean build takes about 3 to 4 minutes (x86_64 and arm64) and the image is about 5.2 GB. On a desktop machine behind a slower connection it took 10 to 26 minutes, almost all of it downloads.

With the default docker-compose.yml (container name test, every password test):

To open Use
Desktop in a browser http://localhost:13579/?password=test
Desktop in a VNC client localhost:12345, password test
A shell ssh test@localhost -p 24680, password test

./dev-bash.sh opens a root shell in that container and ./dev-restart.sh restarts it.

Pull from Docker Hub

Pre-built images are on natlee/gui-vnc.

Every published GitHub release builds and pushes a new image with .github/workflows/publish.yml: it builds natively on an x86_64 and an arm64 runner, runs the same smoke test as CI on each, and only then pushes both under one tag, so Docker picks the right architecture for you:

Tag What it is
latest the newest release
2.1.0 and so on a specific release (the GitHub tag v2.1.0 without the v)
docker pull natlee/gui-vnc:latest

docker run -d \
  -p 12345:5901 -p 13579:6901 -p 24680:22 \
  -v /etc/localtime:/etc/localtime:ro \
  -e VNC_PW=mypassword \
  -e DEFAULT_USER=dev -e DEFAULT_USER_PASSWORD=dev \
  -e ROOT_PASSWORD=root \
  --name gui natlee/gui-vnc:latest

Then open http://localhost:13579/?password=mypassword.

The two tags from before the workflow existed stay up: 20260208-arm64 (arm64 only) and 20241202-x86 (x86_64 only, built from a 2024 version of this repo). Until the first release goes through the workflow, latest doesn't exist yet; build the image yourself as shown above.

Maintainers can also start the workflow by hand (Actions → Publish to Docker Hub → Run workflow) with a version tag. Untick "push" to only build and smoke-test both architectures. It logs in with the repository secrets DOCKER_USERNAME and DOCKER_TOKEN (a Docker Hub access token).

NVIDIA GPU

Install NVIDIA Container Toolkit on the host, then use the GPU compose file:

docker compose -f docker-compose.nvidia.yml build
docker compose -f docker-compose.nvidia.yml up -d

Connection

Service Port in the container How to connect
VNC 5901 VNC client → <HOST_IP>:<PORT>
noVNC 6901 Browser → http://<HOST_IP>:<PORT>/?password=<VNC_PW>
SSH 22 ssh <user>@<HOST_IP> -p <PORT> (user: root or DEFAULT_USER)

docker-compose.yml maps them to host ports 12345 (VNC), 13579 (noVNC) and 24680 (SSH).

Parameters (environment / run options)

Variable Default Description
VNC_PW vncpassword VNC (and noVNC) password
VNC_RESOLUTION 1600x900 Desktop resolution
VNC_VIEW_ONLY false If true, VNC_PW only gets a view-only session (you can watch, not click or type)
DEFAULT_USER user Non-root user the desktop runs as (e.g. AnyDesk needs one)
DEFAULT_USER_PASSWORD user Password for DEFAULT_USER
ROOT_PASSWORD root Root password
LANG en_US.UTF-8 Locale (e.g. zh_TW.UTF-8 for Chinese)

Example: docker run

docker run -d \
  -p 12345:5901 -p 13579:6901 -p 24680:22 \
  -v /etc/localtime:/etc/localtime:ro \
  -v /path/on/host:/root/Desktop \
  -e VNC_PW=mypassword \
  -e VNC_RESOLUTION=1920x1080 \
  -e DEFAULT_USER=dev -e DEFAULT_USER_PASSWORD=dev \
  -e ROOT_PASSWORD=root \
  -e LANG=zh_TW.UTF-8 \
  --name gui gui-vnc

Build the image first (from this directory): docker compose build → image name is gui-vnc.

A folder mounted under /root (like /root/Desktop above, or ./desktop in docker-compose.yml) is root's. You reach it over SSH as root or from a root shell. It does not show up on the VNC desktop, because that desktop belongs to DEFAULT_USER.

Useful run options

  • Map ports: -p 12345:5901 -p 13579:6901 -p 24680:22
  • Timezone: -v /etc/localtime:/etc/localtime:ro
  • Mount folder: -v <HOST_PATH>:<CONTAINER_PATH>

License

MIT

Releases

Packages

Contributors

Languages