/gloomhaven-helper-headless

Headless Gloomhaven Helper server in Docker

Primary LanguageShellMIT LicenseMIT

Publish GitHub commit activity Docker Pulls Docker Image Version (latest semver)

Headless Gloomhaven Helper Server

Gloomhaven Helper has a server/client mode that has been super-useful for my friends and me. The only hiccup is since one of us has to act as the server, the server IP can change depending on who is playing, where we are, etc. If we're playing remotely this can get particularly tricky as one of us has to set up port-forwarding in our router, find our external IP, etc.

So, instead I decided to set up a long-running Gloomhaven Helper that would always be on my home server with a known/static address. All of us would always connect as clients to it. Even if only a subset of us are playing, and no matter where any of us are, our apps always connect to the same address.

But my server is headless (i.e. it has no monitor connected to it. I manage it via ssh only), so I had to run the app in a headless way. Additionally, I'm partial to using Docker for pretty much everything and that seemed like a good way to wrap all of this up nicely.

Installing and Running

The image is available on Docker Hub.

docker run -p 58888:58888 --name ghh-headless -d ghh-headless

If you then run docker logs --follow ghh-headless within a minute or so you should see:

Setting up config.
No existing config. Setting up basic one.
Starting Gloomhaven Helper
00:00  INFO: [broadcast] Listening on port: UDP 58887
00:01  INFO: [server] Listening on port: TCP 58888

Docker Compose

In this repo there's also a Docker Compose configuration for ease of set up. Either clone the repo or just download the config and then follow the instructions in Preserving State. Then run:

docker-compose up -d

Preserving State

If you run the command above, all the state of the games you run will be in the Docker container. You probably want to save it on your host so that you can safely recreate the container without losing that state.

Just create an empty directory (mkdir ghh) and then add the parameter -v $PWD/ghh:/root/.ghh to mount it into the container.

Migrating Existing State

If you already have Gloomhaven Helper running elsewhere and want to use it's state, just copy the state file from that Gloomhaven Helper's configuration directory into the directory you just created.

If you've only been using the mobile app versions of Gloomhaven Helper and want to transfer state, you still can by:

  1. Running desktop Gloomhaven Helper somewhere (with the GUI, not headless!)
  2. Set up one of the mobile apps to be a server.
  3. Connect the desktop app as a client to the mobile server.

Then, you should have the state on your desktop at ~/.ghh/state. Just copy that over.

Options

You can pass -e DEBUG=1 to get some additional debugging logs.

Port-Forwarding / DNS

If your server is behind a firewall/NAT (and if you're running it at home, it likely is), you'll need to open up your firewall as well as set up a port forward on your router so that traffic gets forwarded to your server.

Additionally, unless you have a static IP address, you'll likely want to set up a dynamic DNS so that your friends and you can enter domain name that never changes instead of an IP address that does.

Doing all of this depends on your router and other details. Lookup your router model and Google instructions on how to "port forward" with it and you should hopefully find some help.

Implementation Details

Base Requirements

To run Gloomhaven Helper you need:

I started with the official OpenJDK image based on Debian. Debian has LWGL available to install as liblwjgl-java.

Headless

This one of those "if you know about it, it's easy" type of solutions. I hadn't used it a long time, but I do remember using Xvfb for things and stuff in the past. And, hey, it's still around and available in apt.

Basically, we're creating a virtual monitor that Gloomhaven Helper can display on. It doesn't know the difference between this virtual one and a real monitor.

Configuration

Since Gloomhaven Helper is a GUI-only app, it's really meant to be configured via the GUI. And a clean install of the app will start up with the server turned off. But I knew from using it that even after quitting and restarting the app, it remembers past preferences I'd set, so it had to be saving state somewhere. It didn't take long to find a .ghh in my $HOME directory with a config file that has some JSON-esque data that isn't hard to decipher at all.

So, setting up a default config file that mimics having enabled the server in the GUI was pretty simple (or using sed to edit an existing config if it exists).

Misc

Everything else is standard Docker-ization details. Look at Dockerfile and entrypoint.sh for more details.

Support

If you'd like to support this project, you should instead support Gloomhaven Helper directly by donating or purchasing their iOS and Android apps.