Skip to content

VNC COnnection

You can connect via VNC to a remote machine running Surfmeter Automator to troubleshoot issues that may only be visible in the browser session. The same works for Docker deployments.

The prerequisite for that is:

  • Surfmeter must run in simulated headless mode, which is the default.
  • You have the X window daemon enabled, which is the case for our Docker images and when using the setup.sh script in our manual setup guide.

Starting the VNC Server

In the surfmeter-lab-automator directory, there is a script called run_vnc_server.sh that will launch a temporary VNC server instance.

For Debian-based systems, the following will:

  1. Install a VNC server capable of rendering X displays
  2. Ask you to create a password for connecting
  3. Launch a temporary VNC server instance
sudo apt update -qq && sudo apt install -y tigervnc-scraping-server
./run_vnc_server.sh

The script will print the port at which the server is listening for connections. You can then connect with your favorite VNC client.

Our Docker images already have the VNC server installed. You can start the VNC server permanently by setting the SURFMETER_ENABLE_VNC environment variable to 1 in your .env file.

SURFMETER_ENABLE_VNC=1

Then, (re)start the Docker container as usual. The Docker logs should show something like the following:

{"time":"2025-04-10T06:35:13.796Z","level":"info","origin":"surfmeter-docker-entrypoint","msg":"Starting VNC server in the background ..."}
{"time":"2025-04-10T06:35:13.820Z","level":"info","origin":"surfmeter-docker-entrypoint","msg":"VNC server is ready, running with PID 105"}
{"time":"2025-04-10T06:35:13.844Z","level":"info","origin":"surfmeter-docker-entrypoint","msg":"Container is ready, keeping it running ..."}

Alternatively, to run an ad-hoc server, exec into the container and run the run_vnc_server.sh script:

docker compose exec -it --user surfmeter surfmeter bash
cd surfmeter-lab-automator
./run_vnc_server.sh

Connecting to the VNC Server

You can connect to the VNC server with any VNC client at vnc://localhost:5123. The default password is surfmeter.