The configuration of the software is done in the client and campaign settings.
While you actually could modify the configuration stored in the save file (see below), it is not recommended and, thus, not documented, here.
In contrast, this section focuses on the configuration that should be done within the central configuration file, which is
The configuration file is divided up into two sections: Webserver, and General.
These sections are indicated by these designations, within square brackets (e.g.
Within each section, there are certain variables defined via a name and their value, using the scheme
name = value, followed by a line-break.
# denotes a comment; every line with a leading
# will be ignored.
Only change the configuration if something does not work accordingly and you know what you’re doing.
This section contains several variables concerning the webserver that distributes the client to the players.
0.0.0.0, accepting strings resolveable by DNS) tells the server on what (IP-) address it is reachable.
The default is set to
0.0.0.0 which, in this context, means: ‘Any IP on this machine’.
Most likely, you won’t need to change this setting, unless you’re sharing the machine with others (e.g. on a shared (v)server) or run several servers on the machine with different addresses.
8000) tells the server on which port to listen.
Be sure that the port you use is not used by any other application. Also, make sure the port you use is also accessible from outside of the machine. Especially when running from within a private network (e.g. at home) you might need to enable port forwarding in your router’s configuration.
This configuration key will not be used, when
socket is used, i.e. the
socket is removed.
/tmp/planarally.sock, accepting a filepath) tells the server where to look for a shared socket.
This is an alternative to communicating via a host:port.
socket option is disabled by default.
If you activate the configuration-key by removing the leading
#, sockets, regardless of
socket’s value, will be used instead of
PlanarAlly supports to encrypt communication in between the server and the players via Secure Sockets Layer (SSL).
Despite the name, this is independent from the socket configuration, above.
The SSL-configuration needs three variables to be configured:
SSL is disabled by default. It is strongly recommended to make sure you serve to your endusers over https.
It’s possible that your reverse proxy handles these things for you, in which case you can ignore these settings here.
false, accepting true/false) tells the server whether SSL should be used.
If set to
false (default), the other two settings will simply be ignored as they are not needed by the server.
cert/fullchain.pem, accepting a filepath) tells the server where to look for the
*.pem-file containing the certificate containing the ‘full chain’ of certificates to your certificate authority (CA).
Please note that neither the folder
cert, nor the file
fullchain.pem are shipped with PlanarAlly, but have to be generated/referred to for each individual installation by yourself.
cert/privkey.pem, accepting a filepath) tells the server where to look for the
*.pem-file containing your private certification key.
Please note that neither the folder
cert, nor the file
privkey.pem are shipped with PlanarAlly, but have to be generated/referred to for each individual installation by yourself.
Please also take the ‘private’ in ‘private key’ very seriously!
This setting allows you to configure Cross Origin Resource Sharing. This functionality is deactivated by default and only accepts resources from the same origin.
cors_allowed_origins (disabled by default, default:
See python-socketio on readthedocs.io for more information on the meaning of the allowed values.
The socketio API expects strings (e.g.
'*'). The config file is already interpretting things as strings, so don’t
add the extra
'', but just write
To prevent users from overloading the server, there is a limit to the size of the files being uploaded.
10MB, accepts: a number interpretted as bytes)
This section contains general settings for PlanarAlly.
This setting is used to specify an alternate location to save/load raw asset data from.
By Default this is the
assets_directory (disabled by default. Accepts path to a folder)
save_file (active by default, default:
planar.sqlite) tells the server where to look for the central save file wherein all users, settings, locations, assets and so on are saved.
Note that, at this moment, PlanarAlly only supports storing the saves in .sqlite format.
While the server is running, extra files might be showing up (e.g.
These files are essential for the server functionality.
When copying a save file, make sure to copy these files as well if they exist. (they should not exist if the server is not running)
public_name (inactive default, accepting valid ip or hostname) is used to set an ip or hostname address that is inserted into the invitation url via the DM’s campaign settings.
If inactive or empty, the server falls back to normal operation and uses the ip/hostname address it is accessed with.
These settings configure the logging behaviour of PA.
A rotation logger is used that will keep track of a maximum of
max_log_backups files each containing maximum
max_log_size_in_bytes bytes of logs.
This setting simply disables the option to register new users when set to
This is useful for private servers, where the owner manually creates accounts for new users.
This setting determines if the server allows users to import/export campaigns.
The API server is an administration server on which some API calls can be made. This contains the same options as the settings of the configuration of the webserver, but applying them to the API server.
Thus, only major differences are listed here:
- Always use a different port or socket than for the webserver.
hostis defaulted to
0.0.0.0to limit access.
portis defaulted to
8001(using the port next to the webserver’s default).