How to set up a remote desktop (VNC) on a headless Debian server

Running a Debian server without a monitor ("headless") is standard practice for efficiency, but sometimes the command line isn't enough. Whether you are managing complex file directories or just prefer a visual interface for certain tools, having a full graphical desktop available on demand is incredibly useful.

In this guide, we will set up a lightweight Xfce desktop environment on a headless Debian machine and access it securely using TigerVNC.

Why TigerVNC?

You might see older tutorials recommending TightVNC. While popular, TightVNC lacks support for modern display extensions (specifically RandR). This often leads to frustrating errors—like being unable to change the wallpaper or resize the window—because the desktop environment can't detect a "real" monitor.

We are using TigerVNC because it emulates a modern display perfectly, giving you a stable, resizable desktop without the glitches.

Step 1: Install the desktop environment

First, we need a graphical interface. Xfce is the ideal choice for servers because it is fast, stable, and low-resource.

SSH into your server and run:

sudo apt update
sudo apt install task-xfce-desktop

Step 2: Install the VNC server

Now, install the TigerVNC standalone server and common tools.

sudo apt install tigervnc-standalone-server tigervnc-common

Step 3: Configure the VNC password

Run the server once to initialize the configuration and set your access password.

vncserver

Enter a secure password.
When asked for a "view-only" password, you can type n.

Once done, kill this initial session so we can configure it properly:

vncserver -kill :1

Step 4: Create the startup script

We need to tell the VNC server exactly what to launch when it starts.

Create a new file:
```
nano ~/.vnc/xstartup
```

Paste this configuration:

#!/bin/sh

# Prevent session confusion
unset SESSION_MANAGER
unset DBUS_SESSION_BUS_ADDRESS

# Load X resources (colors, fonts)
[ -r $HOME/.Xresources ] && xrdb $HOME/.Xresources

# Start the Xfce desktop
exec startxfce4

Save (Ctrl+O, Enter) and exit (Ctrl+X), then make it executable:
```
chmod +x ~/.vnc/xstartup
```

Step 5: Start the VNC server

Launch your new desktop instance:

vncserver

You should see output confirming the desktop is running on display :1 (which corresponds to port 5901). You might see a different display number, for example :2 (which corresponds to port 5902).

Note

The VNC server is not automatically started on system startup, so you have to run vncserver each time you want to access the remote desktop.

Step 6: Install and configure the VNC viewer

I recommend TigerVNC viewer because it supports dynamic resizing: if you resize your VNC viewer window on your client machine, the remote Debian desktop automatically resizes to fit. This is RandR at work.

On your local computer, open a terminal and run:

sudo apt update
sudo apt install tigervnc-viewer tigervnc-tools

Optionally create a password file for TigerVNC viewer (so you don't have to type it every time). Use the vncpasswd command, which is the same tool used to set the server password, but you can save the output to a specific file on your client machine.
```
vncpasswd ~/.config/tigervnc/passwd
```

Step 7: Connect securely (SSH tunnel)

VNC traffic is not encrypted by default. Opening port 5901 to the internet is dangerous. The best practice is to use an SSH tunnel.

Create an SSH tunnel to your server on port 5901:
```
ssh -L 5901:localhost:5901 user@your-server-ip
```
Change 5901 to whichever port the VNC server is running on.
Open TigerVNC viewer and connect to address localhost:5901. Enter your password when prompted.

Alternatively, you can connect via the command line:
```
xtigervncviewer -SecurityTypes VncAuth -passwd ~/.config/tigervnc/passwd :1
```
Replace :1 by the display number your VNC server is running on.

Your VNC traffic is now traveling securely inside your SSH connection.