Monitor requirements

Xorg will fail to launch if it doesn’t believe you have a monitor attached. There are a couple of ways to handle this situaion.

1. Attach an actual monitor

Nothing more to say, really. If you have an actual monitor, and you can get it physically close to your server, you can just use that. The Xorg desktop will show on the monitor, though, which may be undesirable.

2. Use a dummy plug

You can get dummy plugs for HDMI and DisplayPort that pretend to be a monitor by returning built-in EDID data when plugged in. They’re relatively inexpensive, and they don’t take up much space, so this is a popular option. You can also unplug the dummy and plug in a monitor as needed, which may or may not be a benefit depending on your situation.

3. Force Xorg to use a custom EDID

By setting up some custom configuration, you can force Xorg to behave as though a monitor is plugged in even when nothing is. This sounds like a slam-dunk for "best overall option" but the configuration is significantly more complex than simply plugging in a dummy, so it’s not necessarily the best option for everyone. Below is a summary of the changes you’ll need to make.

3.1. Obtaining an EDID file

EDID data is how Xorg determines what resolutions and timings your monitor supports without having to be explicitly configured for it. In the headless case we’re setting up, that means that the EDID file you supply needs to declare support for whatever resolution you want to run at. The exact steps for creating an EDID file will vary wildly depending on your setup and goals, so it’s a bit beyond the scope of this guide. Having said that, here are some pointers.

The EDID file can either be a .bin binary file containing the exact 256 bytes of EDID data, or it can be a .txt file where each byte is represented as 2 hexadecimal characters, with the bytes separated by spaces. For example, this file, which has support for several resolutions up to 1920x1080.

If that file doesn’t meet your needs, you still have options. One possibility is to read in the EDID from a connected monitor and use that. Alternatively, you can try to generate your own file using a tool like edid-generator, but that’s not something we’ve tested before.

3.2. Xorg screen configuration

Create a new file somewhere called xorg-screen.conf. In it, put this configuration:

Section "Screen"
    Identifier     "Screen0"
    Device         "Device0"
    Monitor        "Monitor0"
    DefaultDepth    24
    Option         "AllowEmptyInitialConfiguration" "True"
    Option         "UseDisplayDevice" "DP-0"
    Option         "CustomEDID" "DP-0:/home/retro/edid.txt"
    Option         "ConnectedMonitor" "DP-0"
    SubSection     "Display"
        Depth       24
    EndSubSection
EndSection

3.3. Docker configuration

Next, make sure Docker knows how to find your new configuration and EDID files. Add lines like these to the volumes section under xorg in your compose/headless.yml to mount them into the Xorg image.

services:
  xorg:
    # ...
    volumes:
      # START ADDING HERE
      - /path/to/edid.txt:/home/retro/edid.txt:ro
      - /path/to/xorg-screen.conf:/usr/share/X11/xorg.conf.d/01-xorg-screen.conf:ro
      # END ADDING HERE

3.4. Environment

Last but not least, make sure the XORG_DISPLAY_PORT variable in env/headless.env is set to the same value as the UseDisplayDevice option in your xorg-screen.conf file. If you copied the snippet above, the correct value should be DP-0.

Now you should be able to launch GOW as normal, without any monitor-related issues.