#Server Configuration

The server can be configured by creating a config.toml file in the server’s data folder. When no config file is provided, PA will use default values. The default config can be seen here.

When a partial config file is provided, missing fields will similarly be replaced with default values were relevant.

#Format

As the extension of the config implies, the config is formatted using TOML.

The config is split up in smaller sections which have a [section] heading, with subsections being denoted by [section.some.subsection]. Each (sub)section is then followed by separate lines to configure particular values.

Detailed information on how the TOML format works is out of scope of this document, but after checking the default config you should have a good grasp of how it works.

#Default config

[general]
save_file = "data/planar.sqlite"
allow_signups = true
enable_export = true
max_log_size_in_bytes = 200000
max_log_backups = 5

[assets]
max_single_asset_size_in_bytes = 0
max_total_asset_size_in_bytes = 0

[webserver]
max_upload_size_in_bytes = 10485760

[webserver.connection]
type = "hostport"
host = "0.0.0.0"
port = 8000

#Sections

Here all the possible options will be listed along with their default values. If at any point this info would become out of date and causes errors, the source of truth can be found on github in code form.

#General

Section name: general

#Field: save_file

Default: "data/planar.sqlite"
Type: string

Path to the save file. This is a crucial setting that when modified will have a big impact.

If the server starts and the chosen path does not exist, the server will create a new save file.

#Field: client_url

Default: N/A - optional field
Type: string
It’s generally recommended to configure this field, but it’s not required for a minimal setup.

When set this should be the full base URL of the frontend application. (e.g. “https://app.planarally.io”).

This is used in the invite URL and forgot password mails. When missing the invite URL will look at the current URL in the browser when generated. Email URLs will however not contain the root URL info as the server cannot predict this.

#Field: allow_signups

Default: true
Type: boolean

This setting dictates whether users can register a new account using the frontend. When disabled account creation is only available through database manipulation.

#Field: enable_export

Default: true
Type: boolean

When this setting is enabled account export and import is available for users.

This is generally recommended as this allows users to move their data to/from a different server as well as provide me with data for debugging.

#Field: max_log_size_in_bytes

Default: 200_000
Type: integer

The max size in bytes for a single log file. This is used together with the next field to determine the logging strategy of PlanarAlly.

#Field: max_log_backups

Default: 5
Type: integer

Number of log files to keep around. This is used to prevent a million log files from being kept.

#Webserver

Section name: webserver

#Subsection: connection

This is a subsection (see the Default Config for an example on how to configure this).

This configures how the server is connected to the network stack. It has to be either a HostPort configuration or a socket configuration. By default a HostPort combination is used.

#field: type

Default: "hostport"
Type: `“hostport” or “socket”

The type field is what ultimately determines which connection type is used.

# Either a hostport connection is configured
[webserver.connection]
type = "hostport"
...

# Or a socket connection
[webserver.connection]
type = "socket"
...

#HostPort fields

#field: host

Default: "0.0.0.0"
Type: string

The IP on which the server will attempt to bind.

#field: port

Default: 8000
Type: integer

The port on which the server will attempt to bind.

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.

#Example HostPort config

[webserver.connection]
type = "hostport"
host = "192.168.0.1"
port = "80"

#Socket fields

#field: socket

Default: N/A
Type: string

The path to the socket that will be used to bind.

#Example Socket config

[webserver.connection]
type = "socket"
socket = "/var/run/pa.sock"

#Subsection: ssl

This is an optional subsection, when omitted no SSL config is applied to the PA server itself. This does not prevent you from setting up SSL higher up in the chain (e.g. in your reverse proxy).

It is strongly recommended to ensure that SSL is set up somewhere in the chain!

#Field: enabled

Default: false
Type: boolean

Allows you to enable/disable the ssl config without having to completely remove the SSL section or comment it. Only when this value is set to true will the SSL config actually be applied.

#Field: fullchain

Default: N/A
Type: string

Path to the full chain certificate.

#Field: privkey

Default: N/A
Type: string

Path to the private key certificate.

#Example SSL config

[webserver.ssl]
enabled = true
fullchain = "/etc/letsencrypt/live/planarally/fullchain.pem"
privkey = "/etc/letsencrypt/live/planarally/privkey.pem"

#Field: cors_allowed_origins

Default: N/A (optional field)
Type: string / List of strings

CORS configuration for the websocket server.

This value is passed to the socketio server, more info can be found in the socketio docs. A value of '*' can be set to allow all origins, this is useful for testing purposes, but not secure.

#Field: max_upload_size_in_bytes

Default: 10_586_760 (10 * 1024 ** 2 == 10 MB)
Type: integer

The maximum size a single upload of data from the client can be.

It should be noted that this will mostly act as a chunking strategy. Asset uploads and campaigns transfers will be chunked according to this maximum, but the total size of these can thus exceed the limit! See the assets section of the config for info on how to limit user’s asset sizes.

#API server

Section name: apiserver

This is an optional section and is by default not enabled.

The same values as the server section apply, but the hostport or socket must be different than the main webserver.

#Assets

#Field: max_single_asset_size_in_bytes

Default: 0
Type: integer

The maximum size a single user uploaded asset can have in bytes.

A value of 0 or smaller will be interpretted as no limit.

Users will not be able to upload assets that are bigger and will receive an error notification.

#Field: max_total_asset_size_in_bytes

Default: 0
Type: integer

The maximum size a user can store on the server (assets only).

A value of 0 or smaller will be interpretted as no limit.

Users will not be able to upload an asset if it would bring their total storage on the server over this limit.

Note that this setting will only affect new uploads and does not shrink/remove already uploaded assets if you lower this value at a later time.

#Field: directory

Default: "static/assets"
Type: string

This can be used to specify a different path to where assets are located.

This is mostly an experimental setting, use at your own risk.

#Mail

Section name: mail

This is an optional section and is by default not enabled.

It’s currently only used to send mails as part of the forgot-password flow.

#Field: enabled

Default: false
Type: boolean

Allows you to enable/disable the mail config without having to completely remove the section or comment it. Only when this value is set to true will the mail config actually be applied.

#Field: host

Default: N/A
Type: string

The host of the SMTP mailserver, this must be filled in.

#Field: port

Default: N/A
Type: integer

The port of the SMTP mailserver, this must be filled in.

#Field: username

Default: N/A (optional)
Type: string

If applicable, the username can be specified to authenticate with.

#Field: password

Default: N/A (optional)
Type: string

If applicable, the password can be specified to authenticate with.

#Field: default_from_address

Default: N/A
Type: email-string

The default email address to use when sending mails.

#Field: ssl_mode

Default: "starttls"
Type: Literal["ssl", "tls", "starttls", "lmtp"]
Added: v2025.2.1

This configures the client connection mode used. By default the starttls method is used which should cover a wide range.

This can sometimes not work correctly, in which case you can try the "ssl" mode or any of the other modes instead.

#Stats

Section name: stats

This is an optional section that when not specified will use a default set of values. It controls the collection and transmission of anonymous usage statistics.

See this github PR for some information on what and why.

#Field: enabled

Default: true
Type: boolean

Allows you to enable/disable the mail config without having to completely remove the section or comment it. When set to false no stats collection will happen at all.

#Field: enable_export

Default: true
Type: boolean

Allows you to disable the export of statistics to the PA stats server. Local collection will still be done.

#Field: export_frequency_in_seconds

Default: 24 * 60 * 60 (1 day)
Type: int

This determines how frequent the stats are sent to the PA stats server.

It’s not recommended to put this any lower than 1 day. Recommended rates are 1 day, 1 week or 1 month.

#Field: stats_url

Default: https://stats.planarally.io Type: string

The receiving URL of the stats data.