Running the Drivechain Qt wallet in Docker, from a browser

The wallet is a Qt desktop app, so the container runs a headless X server and publishes it over VNC:

drivechain-qt ──> Xvfb :1 ──> x11vnc :5900 ──> websockify/noVNC :6080 ──> your browser
                    │
                 fluxbox (window manager) + xterm

Everything inside the container is started and supervised by supervisord.

File	Role
Dockerfile	Base image: compiles drivechaind / drivechain-qt
Dockerfile-x11	Adds Xvfb, fluxbox, x11vnc, noVNC, supervisor on top
supervisord.conf	Process table for everything above
start-gui.sh	Waits for X, then launches drivechain-qt
docker-compose.yml	Ports, volume and env for the container

Prerequisites

• Docker Desktop (or any Docker with Compose v2) running.
• ~8 GB free disk: the base image alone is ~6.5 GB.

Apple Silicon builds natively as arm64 — no --platform flag needed.

---

Step 1 — Build the base image

This compiles the whole node from source. It is slow (tens of minutes) and only has to be done once.

cd /Users/rob/projects/mainchain-deprecated
docker build -t mainchain:latest -f Dockerfile .

Check it produced the binaries:

docker run --rm --entrypoint ls mainchain:latest -la /usr/local/bin

You should see drivechain-qt, drivechaind, drivechain-cli, drivechain-tx.

Already have the base image under another name? Skip this step and pass --build-arg BASE_IMAGE=<your-image>:<tag> in step 2, or set it under build.args in docker-compose.yml.

Step 2 — Build the desktop image

Fast (~1 min), it is just an apt layer on top of the base:

docker build -t mainchain-x11:latest -f Dockerfile-x11 .

Step 3 — Start the container

docker compose up -d

Compose publishes 6080 (noVNC over HTTP) and 5900 (raw VNC), and mounts the drivechain-data volume at /data so the chain survives rebuilds.

Wait ~15 s for the node to come up, then confirm all six processes are running:

docker exec mainchain-gui supervisorctl -c /etc/supervisor/conf.d/supervisord.conf status

Expected:

drivechain-qt                    RUNNING   pid 13, uptime 0:00:19
fluxbox                          RUNNING   pid 10, uptime 0:00:19
websockify                       RUNNING   pid 12, uptime 0:00:19
x11vnc                           RUNNING   pid 11, uptime 0:00:19
xterm                            RUNNING   pid 14, uptime 0:00:19
xvfb                             RUNNING   pid  9, uptime 0:00:19

Step 4 — Open it in your browser

http://localhost:6080/

noVNC connects automatically — no password. The Drivechain wallet is on the desktop, with an xterm next to it.

If you get a connection form instead of the desktop, use http://localhost:6080/vnc.html, leave host/port as pre-filled, and click Connect.

Prefer a native client? macOS has one built in (leave the password empty):

open vnc://localhost:5900

---

Steps 2–4 in one command

Once the base image from step 1 exists, this rebuilds the desktop layer and (re)starts the container:

docker compose up -d --build

Use it every time you edit supervisord.conf, start-gui.sh or Dockerfile-x11 — those are baked into the image, so a plain restart will not pick up your changes.

Configuration

Set these in docker-compose.yml under environment:, or inline on the command line.

Env var	Default	Meaning
SCREEN	1440x900x24	Xvfb geometry, WIDTHxHEIGHTxDEPTH
DRIVECHAIN_ARGS	(empty)	Extra drivechain-qt flags
DRIVECHAIN_DATADIR	/data	Node data directory (where the volume lands)

A smaller desktop that fits your browser window without scrolling:

SCREEN=1280x800x24 docker compose up -d --force-recreate

A private regtest chain instead of trying to reach mainnet peers:

DRIVECHAIN_ARGS="-regtest" docker compose up -d --force-recreate

Day-to-day commands

# logs from every supervised process
docker compose logs -f

# restart just the wallet, leaving X and VNC up
docker exec mainchain-gui supervisorctl -c /etc/supervisor/conf.d/supervisord.conf restart drivechain-qt

# a shell inside the container
docker exec -it mainchain-gui bash

# node log
docker exec mainchain-gui tail -f /data/debug.log

# stop, keeping the chain data
docker compose down

# stop and wipe the chain data volume
docker compose down -v

RPC from the command line needs the GUI started with -server (it then writes an auth cookie into the datadir):

DRIVECHAIN_ARGS="-server" docker compose up -d --force-recreate
docker exec mainchain-gui drivechain-cli -datadir=/data getblockchaininfo

Without -server, use the wallet's own console: This Node → Debug window → Console.

Troubleshooting

Page loads but the screen stays grey. Click once on the desktop — noVNC 0.4 sometimes needs a click before it starts drawing.

0 peers, sync stuck at 0%. Expected. This chain's hardcoded seed node (172.105.148.135:8383) refuses connections, which you can see in /data/debug.log. Use -regtest, or point at a node you control with DRIVECHAIN_ARGS="-connect=<host>:<port>".

Port 6080 or 5900 already in use. Change the left-hand side of the mapping in docker-compose.yml, e.g. "7080:6080", then browse to http://localhost:7080/.

The wallet window never appears. Check that X came up and the app is a client of it:

docker exec mainchain-gui bash -c 'DISPLAY=:1 xprop -root _NET_CLIENT_LIST'
docker compose logs drivechain-gui | grep start-gui

Verify the transports without a browser.

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:6080/     # want 200
python3 -c "import socket;s=socket.create_connection(('127.0.0.1',5900),5);print(s.recv(12))"
# want b'RFB 003.008\n'

Grab a screenshot of the virtual desktop (installs ImageMagick into the running container only, not the image):

docker exec mainchain-gui bash -c 'apt-get update >/dev/null && apt-get install -y --no-install-recommends imagemagick >/dev/null && DISPLAY=:1 import -window root /tmp/desktop.png'
docker cp mainchain-gui:/tmp/desktop.png ./desktop.png