Shadowroller

Shadowroller is work-in-progress a website that lets you roll lots of d6's and follow Shadowrun's dice rules.

There is a server (sr-server) which runs games for my friends. This system is not available for the general internet at the moment. You can run a local version of the server yourself if you'd like - it's easy if you're comfortable with the command line and port forwarding. Please read the Local development and Production environment sections first!

Local development

Editor setup

You will at the minimum want an editor which can handle Go and Typescript. IDE support for both of these languages is available via the Language Server protocol. You might need to install NodeJS and Go locally in order to have a nice editor experience, in which case it may not be worth it to run Docker.

Docker

Running Shadowroller locally with Docker can be easier than running it manually, but it can be a liiiitle slower to boot up. If you're unfamiliar with Docker, it may be a good idea to read up on the basics. You can install docker from your package manager or their website.

Shadowroller uses docker compose to run containers in development. Running Shadowroller locally is just a matter of typing

docker-compose up

in a terminal when you're at the root directory of the project. The web and server with both automatically refresh when changes are made in the web/ and server/ directories.

If you install or upgrade dependencies (i.e. package.json, package-lock.json, go.mod, or go.sum change), you'll need to rebuild the container(s) via docker-compose build web or docker-compose build server.

Locally

Take a look at the Makefile, it's got a collection of basic scripts you can run.

The easiest way to run Shadowroller locally is to use Tmuxp (a Python library) with tmux. There's a .tmuxp.yaml file which is essentially a scripted way to run all the components in different terminals in one tmux window. (If you're a tmux or screen pro and could set this up with shell script, I'll happily accept your submission!)

This requires only reflex, which you can replace with your "watch-the-.go-files-and-rerun-go run-when-one-changes" script of your choice.

Redis (https://redis.io/): At the time of writing, Shadowroller tries to add test games to the default Redis database when it boots up in a dev environment. You can use the provided configuration: redis-server redis/redis.conf. This saves a persistent database to redis/sr-server.rdb and isolates Shadowroller from any "default" Redis database. You can also simply use the built-in service manager (i.e. systemctl enable redis or brew services start redis).

Server (Go) (https://golang.org) Shadowroller may be using a version of Go newer than that provided by your package manager. Go is typically installed from its website. As mentioned above, you may want a script to restart the server automatically when its .go files change.

Frontend (Typescript) (https://nodejs.org/) Shadowroller's frontend is compiled from Typescript into a single-page app (SPA). In development, npm run start (from the web directory) will run a hot-reloading server (from Create React App). You can also build the frontend yourself (via make build) and have the server host it.

You can run the frontend and backend independently if you like, but you can't run the server without Redis.

On production

You can totally run your own version of Shadowroller on the internet if you want to! That's the power of free software! Shadowroller runs perfectly fine on a Raspberry Pi and there is plenty of configuration to help you out.

Please look at server/config/config.go to get a sense of some of the options. For example, you can:

  • use SSL termination, an automatic Let's Encrypt setup, or your own certificate
  • Host the frontend via a CDN or with the server

Please make sure you've read through config.go so you know what you're doing!

It should be fairly easy to tweak the docker-compose.yaml file to include these options, or even use Docker Swarm or Kubernetes. I've run shadowroller.net from a Raspberry Pi B (the oldest Model B, the one with a single-core CPU) without Docker.