I'm getting errors when I try to run the mapshot CLI render command on my headless linux server.

I downloaded mapshot-linux from github and placed it in /opt/factorio/mods. I'm not sure if I'm installing mapshot correctly; I've never installed mods on the headless server before. I am able to run and connect to the server from the Factorio client.

Here is the command and output when I run mapshot from the factorio root directory:

/opt/factorio$ mods/mapshot-linux render /opt/factorio/saves/my-save.zip --factorio_binary /opt/factorio/bin/x64/factorio --factorio_datadir /opt/factorio/
Generating mapshot "my-save" using file /opt/factorio/saves/my-save.zip
Starting Factorio...
Error: factorio exited early; err=exit status 1

The readme examples run mapshot from the current directory. When I cd to the mods directory and run mapshot, it says it can't find the mods directory:

/opt/factorio/mods$ ./mapshot-linux render /opt/factorio/saves/my-save.zip
Generating mapshot "my-save" using file /opt/factorio/saves/my-save.zip
Error: unable to read directory "mods": open mods: no such file or directory

When I move mapshot-linux to /opt/factorio and run it, I get the same output as the first command ("factorio exited early").

My Factorio server setup:
Factorio 1.0.0 headless linux x64
Ubuntu 20.4

You can get more details about the failure by adding the flag --factorio_verbose. That will give more details about why Factorio fails. You can use pastebin or similar to share them if they're large.

That being said, my guess would be that it is caused by the lack of X server on your headless setup. Mapshot starts Factorio normally - i.e., not in headless mode. So, Factorio probably looks for a X server (through DISPLAY env var) and fails. The reason for Mapshot to start Factorio normally is that headless Factorio does not load graphic data, making screenshot non functionals unfortunately.

If you are connecting to your server through a Linux, you can try to use ssh -C -Y to enable X forwarding. This is just a workaround, I'm not sure it works and overall is likely to be a terrible experience.

An option I was looking at before would be to run Factorio with Xvfb (or similar) - i.e., attaching Factorio to a virtual display server which might be enough to make Factorio work on a headless server. I haven't dig into it so far as I was not sure if there was an interest, but the dedicated server case is one, I might look into it further. Depending on how Linux-savvy you are, you can try it - I cannot give precise instructions nor guarantee that it would work, but the idea would be to start Xvfb, set DISPLAY env to it and then run mapshot. YMMV.

I've updated the doc with how to render on headless server. Basically, you just need a recent version of Xvfb (e.g., Ubuntu 18.04 does not work, but Ubuntu 20.04 does). Once installed (apt-get install xvfb, depends on your distro), you just need to start your command with xvfb-run; for example in your case:

xvfb-run ./mapshot-linux render /opt/factorio/saves/my-save.zip