Subpath hosting

PlanarAlly can be hosted without effort at a root level (e.g. https://www.planarally.io) or at a subdomain (e.g. https://dnd.planarally.io). When hosting at a subpath however some additional work needs to be done (e.g. https://www.planarally.io/dnd/).

You need to signal to the server and the client that they’re supposed to run on a subpath. Additionally you might also need to do some changes to your proxy.

The rest of these docs will sometimes refer to the PA_BASEPATH environment variable, this should match the desired subpath. For example:

export PA_BASEPATH="/planarally/"
Changed behaviour

Since 2022.1 there have been some changes to the subpath handling, make sure to reread these docs properly if you’ve used them in the past!

In particular the client now always has to be build manually and the docker container uses —build-arg instead of —env.

Client changes

When you want to use a subpath, you have to build the client yourself. The subpath info needs to be baked into the build output files. This can simply be done by building the client while the PA_BASEPATH environment variable is set.

Server changes

The server also needs to know about the subpath, simply make sure the PA_BASEPATH environment variable is set before running the server.

Docker

When using the docker image, this env variable needs to be passed to the container. Add the following part to your docker command.

--build-arg PA_BASEPATH='/planarally/'

Proxy

Nginx

When using nginx, you will have a very similar setup as the one described in proxy, but all location parts will start with /planarally if that is your desired subpath.

Additionally you need to make one small modification to the socket.io specific location rule:

The proxy_pass (or host:port pass) needs to be changed to include the subpath. (e.g. proxy_pass http://subaiohttp/subpath/socket.io/;)

Apache

Make sure to setup the proxypass and reverse on the subpath!

ProxyPass /planarally http://127.0.0.1:8000/planarally
ProxyPassReverse /planarally http://127.0.0.1:8000/planarally