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.
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.
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.shsets the passwords from the environment, starts the VNC server on display:1(port 5901) asDEFAULT_USER, runs Xfce in it, and starts noVNC on port 6901, which turns the VNC session into a web page.sshdon port 22, with password login.rootcan 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.
- Xfce desktop (lightweight)
- TigerVNC (port 5901) + noVNC (port 6901, browser access)
- OpenSSH (port 22)
- VS Code (launched with
--no-sandboxfor container compatibility) - Firefox
- AnyDesk
- Miniconda in
/opt/conda - fcitx5 Chinese input (e.g. Pinyin); use
fcitx5-configtoolto add or switch input methods - Git, vim, tmux, htop and other common dev tools
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 -dBe 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.
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:latestThen 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).
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| 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).
| 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) |
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-vncBuild 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.
- 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>
