This is a server component for the Gloomhaven Secretariat (Source). It synchronises the game state between all clients via websockets. Access is controlled by specifying a Game ID in all messages.
It's a Java application that runs on most systems that run the old Gloomhaven Helper (by Esoteric Software®) desktop version. A headless mode is also integrated.
A public server is available at gloomhaven-secretariat.de port 8443 with secure option. I also maintain a public server list, so please contact me if you'd like to run a public instance yourself.
☕ Buy me a coffee? (or Donate directly via PayPal)
This will run a basic server for a single game code (e.g. for a group, you can still use the multi-campaign feature).
-
Install Java 17 (or higher) (Requirement changes with newer version!) Runtime Environment: Installation Guide for different OS'
-
Download the appropriate latest
jarexecutable (without-mariadb- or-postfix-suffix) from the latest release assets. -
Execute the
jarfile (should be working automatically with your Java Runtime Environment) -
You should see a similar window:
⚠️ Important: If you do not see any local IP address listed besideslocalhost, please check your Firewall settings! After allowing the application in your network and restarting the app, you should see your local IP starting with192.[...]in most cases! -
Click the Install latest client button, afterwards window should look like this:
-
On any device in your local network, you should now be able to access the client with the listed address
http://192.[...]:8080/index.htmland connect to your server viaHost: 192.[...]andPort: 8080.ℹ️ Notice: Connecting from a different client running with HTTPS (like gloomhaven-secretariat.de) won't work! If you want the server to be accessbile from HTTPS, see Enable SSL.
All data is stored in <your-home-folder>/.ghs (List of home-folders for different OS').
If you want to reset the server, just delete the ghs.sqlite database file in this directory.
If you want to configure your server in detail or create a public server, here are some advanced installation and configuration steps.
If you want to use Docker to run on port 8080, execute the following
docker pull gloomhavensecretariat/ghs-server
docker run --rm -p 8080:8080 --name ghs-server gloomhavensecretariat/ghs-serverIf you want to configure the application.properties file, replace the docker run command with
docker run --rm -p 8080:8080 -v {local_path}:/root/.ghs --name ghs-server gloomhavensecretariat/ghs-serverThe .ghs folder is now accessible from your {local_path}.
For use with docker compose, just run docker compose up -d.
The Server is also able to serve the Client. Simply click on the "Install latest client" button in the GUI. Then you can open the client directly in your browser by clicking on the appropriate button.
If you are running headless, just download the zip file (NOT the source code!) of the Gloomhaven Secretariat Release and extract it to the folder <your-home-folder>/.ghs/gloomhavensecretariat. After that GHS is accessible at http://{your-ip}:{server-port} (http://localhost:8080 with default values). To automatically install the latest client on startup, edit the application.properties file in the GHS server configuration folder <your-home-folder>/.ghs and add the following line: ghs-server.lastestClientOnStartup=true.
To run the server in headless mode, simply set the -Djava.awt.headless=true parameter for execution. For example java -jar ghs-server-*.jar -Djava.awt.headless=true.
To run the server on a different port (default: 8080), edit the application.properties file in the GHS server config folder <your-home-folder>/.ghs and add the following line: server.port=<NEW PORT>.
Replace <NEW PORT> with the port of your choice.
A public server will accept any Game Code and create a game for it. The Game Code is therefore more of an identifier for a single game than a password protection. To make a public server, edit the application.properties file in the GHS server configuration folder <your-home-folder>/.ghs and add the following line: ghs-server.public=true.
If you want to connect to the server from a client using HTTPS (NOTE: this is not the case if you run your own client locally!), the websocket connection will be upgraded to wss by any modern browser. Therefore, connecting to a server on the local network is only possible if SSL is enabled. A self-signed certificate is already included (yes, including a hardcoded password visible to everyone). So to easily enable SSL, just edit the application.properties file in the GHS server configuration folder <your-home-folder>/.ghs and add the following line: server.ssl.enabled=true. As a self-signed certificate is used, it is untrusted by all modern browsers. To connect, just type https://{your-ip}:{server-port} (https://localhost:8080 with default values) and accept the security warnings. You should then be able to connect using SSL. (This must be done for each client).
To serve with your own certificate, overwrite the following properties in your application.properties file
server.ssl.key-store-type=
server.ssl.key-store=
server.ssl.key-store-password=
server.ssl.key-alias=
To generate a certificate file from your Let's Encrypt certificate, use
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -CAfile chain.pem -caname root -name ghs-server -out ghs-server.p12
This will prompt for a password and then create a ghs-server.p12 file which will be referenced as server.ssl.key-store.
When running with SSL, a non-SSL server is automatically available on port 8081. To change this port, edit the application.properties file in the GHS server configuration folder <your-home-folder>/.ghs and add the following line: server.http.port=<HTTP PORT>.
It is possible to replace the sqlite database with a PostgreSQL or MariaDB database. Download the corresponding artifact or build your own package with profile db-postgresql or db-mariadb.
Afterwards, add the following lines to the application.properties file in the GHS server configuration folder <your-home-folder>/.ghs:
# keep those blank
spring.datasource.driverClassName=
spring.jpa.database-platform=
# postgresql: replace <database>, <username> and <password> to your needs, remove *mariadb* lines below
spring.liquibase.change-log=classpath:db/postgresql/main.xml
spring.datasource.url=jdbc:postgresql://localhost/<database>
spring.datasource.username=<username>
spring.datasource.password=<password>
# mariadb: replace <database>, <username> and <password> to your needs, remove *postgresql* lines above
spring.liquibase.change-log=classpath:db/mariadb/main.xml
spring.datasource.url=jdbc:mariadb://localhost:3306/<database>
spring.datasource.username=<username>
spring.datasource.password=<password>
You can also use the server component to be used as GHS Backup Server to accept game payloads and store to file system. The upload url is http://{your-ip}:{server-port}/backup. To enable, add the following lines to the application.properties file in the GHS server configuration folder <your-home-folder>/.ghs:
# replace <path-to-backup> with an accessible path to store the backup files and <token> as authorization header for authentication.
ghs-server.backup.path=<path-to-backup>
ghs-server.backup.authorization=<token>
Go to the main menu in Gloomhaven Secretariat (GHS) and click on Connect to Server. Enter the IP/Hostname of the server in Host (on the same machine just use localhost), set Port to 8080 (if not changed default port).
When you run the game for the first time, simply select a Game Code of your choice. This will create a new game with that Game Code. After that, each time you connect to the server, you will need to set the same Game Code (it is now unchangeable!). Alternatively, you can make the instance public to allow multiple games/Game Codes.
- updated GUI (it's more of a placeholder now)
- add/change/update Game Codes/permissions
- optional: track undo/redo on server too
- The database is a simple
ghs.sqlitefile in the GHS server config folder<your-home-folder>/.ghs. You can manipulate the file directly withSqlite. To reset the database, simply delete thesqlitefile. - On startup, all Game Codes are written to syslog in clear text. (Can be disabled in the
application.propertiesviaghs-server.gameCodesDump=false)
This application does NOT collect any personal data other than GHS game state, authentication and permission data. Please note that this data is NOT ENCRYPTED. Be aware that you must trust any third party provider of a server component not to collect any other data such as IP addresses.
Gloomhaven and all related properties, images and text are owned by Cephalofair Games.
The source code is licensed under AGPL
This is a hobby project I do in my spare time. The software fills a practical need due to the demise of the original Helper application, so I am following the Quick'n'Dirty approach to get things done quickly. This of course leads to a lack of quality and testing and the code base is definitely not in line with my profession.