Configuration

pwikit reads its settings from command-line options, environment variables and the file pwikit.toml. This document lists every setting. Installing and running pwikit is described in Deployment.

Where settings come from

pwikit.toml is located in the data directory, next to the executable unless -data-dir or PWIKIT_DATA_DIR says otherwise. The first pwikit createsite or pwikit serve writes it as a template in which every setting is commented out. An existing file is never overwritten. On Linux and macOS the file is created readable only by its owner.

When a setting is given in more than one place, the first one found wins:

1. command-line option
2. environment variable
3. pwikit.toml
4. default

An empty environment variable, or an empty string in pwikit.toml, counts as not set. Not every setting exists in all three places; the tables below show where each one can be given.

pwikit reads its settings only at startup. Restart pwikit after changing any of them.

pwikit serve reads the whole file. The commands createsite, site, admin, user, seed, import, reindex, migrate, backup create and backup restore read only database, and only when neither -database nor DATABASE_URL is given. pwikit service install reads the whole file to check it and to decide which firewall ports to open.

Environment variables do not reach a pwikit installed as a system service. For a service, use pwikit.toml, or options given after -- when installing.

The template

The generated pwikit.toml lists every setting, commented out and with a short explanation; remove the leading # to turn a line on. The file holds database at the top level and the sections [server], [tls], [mail], [analytics] and [update], each described below. The generated file:

# Settings for pwikit. A line starting with # is an example and changes nothing
# until the # is taken away.
# A flag on the command line wins over this file, and so does an environment variable.
# Restart pwikit after changing anything here.

# A PostgreSQL of your own. Left unset, pwikit runs the one it carries.
# database = "postgres://user:password@127.0.0.1:5432/pwikit"

[server]
# listen = "127.0.0.1:8080"
# trusted_proxies = ["127.0.0.1"]
# upload_limit = "4GB"
# storage_limit = "0"

[tls]
# Left unset, pwikit serves HTTPS on ports 80 and 443 with certificates from
# Let's Encrypt once a site is bound to a public domain, and plain HTTP on
# 127.0.0.1:8080 until then. Setting listen or trusted_proxies means a proxy sits
# in front, and turns that off.
# off serves plain HTTP, file uses the certificate below, auto always obtains one.
# mode = "auto"
# listen = ":443"
# cert = "/path/to/fullchain.pem"
# key = "/path/to/privkey.pem"
# acme_email = "you@example.com"
# acme_directory = ""

[mail]
# smtp sends mail, console writes it into the log instead.
# engine = "smtp"
# host = "smtp.example.com"
# port = 587
# username = "wiki@example.com"
# password = ""
# use_tls = true
# implicit_tls = false
# from = "wiki@example.com"

[analytics]
# google_tag_id = ""

[update]
# pwikit installed as a system service looks for a new release every hour and
# installs it by itself inside the window below.
# auto = true
# Whether every visitor sees the banner announcing an automatic update, or only
# the people who can open the admin panel.
# public_banner = true
# false stops pwikit from asking for new releases at all.
# check = true
# The hours in which updates are installed, read in time_zone.
# window = "03:00-05:00"
# The time zone the window is read in, such as "Asia/Shanghai". Empty uses this
# machine's time zone.
# time_zone = ""
# How long a release must have been out before it is installed automatically.
# 0s installs it in the next window.
# min_age = "0s"
# A mirror to download from when GitHub cannot be reached. Use only a mirror you trust.
# pwikit update mirror <address> sets this line.
# mirror = ""

A key pwikit does not recognize stops startup, and the error names the key:

pwikit: /opt/pwikit/pwikit.toml has settings pwikit does not know: server.lisen

A value of the wrong type, such as port = "587" instead of port = 587, also stops startup.

Top level

Key	Type	Default	Option	Environment variable	Meaning
database	string	empty: the bundled PostgreSQL	-database	DATABASE_URL	Connection string of your own PostgreSQL, such as postgres://user:password@127.0.0.1:5432/pwikit. See Deployment.

[server]

Key	Type	Default	Option	Environment variable	Meaning
listen	string	127.0.0.1:8080; :80 when HTTPS is on	-listen	none	Address for plain HTTP. When HTTPS is on, this port redirects to HTTPS. Setting it turns automatic HTTPS off.
trusted_proxies	array of strings	empty	-trusted-proxies	none	Addresses or CIDR ranges of reverse proxies, such as ["127.0.0.1", "10.0.0.0/8"]. Only requests from these addresses may set X-Forwarded-For and X-Forwarded-Proto. The option takes a comma-separated list. Setting it turns automatic HTTPS off.
upload_limit	string	"0": no limit	-upload-limit	MEDIA_UPLOAD_LIMIT	Total size that the files currently attached to pages may reach, across all sites of the instance.
storage_limit	string	"0": no limit	-storage-limit	ABSOLUTE_MEDIA_UPLOAD_LIMIT	Total size that all stored files may reach, including deleted files still on disk, across all sites of the instance.

Sizes are a whole number followed by an optional unit: B, KB, MB, GB or TB, in upper or lower case. One KB is 1024 bytes. A number without a unit is a number of bytes. In pwikit.toml, write sizes as quoted strings, such as upload_limit = "4GB". An upload that would exceed either limit is refused.

[tls]

Key	Type	Default	Option	Environment variable	Meaning
mode	string	chosen automatically	-tls	PWIKIT_TLS	off, file or auto. See "Choosing the HTTPS mode".
listen	string	:443	-tls-listen	PWIKIT_TLS_LISTEN	Address for HTTPS.
cert	string	empty	-tls-cert	PWIKIT_TLS_CERT	Certificate chain in PEM format, for file mode.
key	string	empty	-tls-key	PWIKIT_TLS_KEY	Private key in PEM format, for file mode.
acme_email	string	empty	-acme-email	PWIKIT_ACME_EMAIL	Contact address registered with the certificate authority. Optional.
acme_directory	string	empty: Let's Encrypt	-acme-directory	PWIKIT_ACME_DIRECTORY	Directory URL of another ACME certificate authority, such as the Let's Encrypt staging directory https://acme-staging-v02.api.letsencrypt.org/directory.

Choosing the HTTPS mode

pwikit chooses how to serve at startup, in this order:

1. With -dev, pwikit serves plain HTTP on 127.0.0.1:8080, or on the port given with -listen. mode, listen and trusted_proxies from environment variables and pwikit.toml are ignored. See Deployment.
2. If mode is set by option, environment variable or pwikit.toml, that mode is used:
   • off: plain HTTP on listen, by default 127.0.0.1:8080.
   • file: HTTPS on [tls] listen with the certificate in cert and key. [server] listen, by default :80, redirects to HTTPS.
   • auto: HTTPS on [tls] listen with certificates obtained over ACME for the domains and media domains of the sites. [server] listen, by default :80, redirects to HTTPS and answers the certificate authority's validation requests.
3. If mode is not set but listen or trusted_proxies is, the mode is off. Either setting means a reverse proxy handles HTTPS.
4. Otherwise pwikit looks at the domains and media domains of all sites. If at least one is a public domain, the mode is auto and pwikit listens on :80 and on [tls] listen. If not, the mode is off on 127.0.0.1:8080.

IP addresses, names with a port, names without a dot, and names equal to or ending in localhost, localdomain, local, test, example, invalid, internal, lan, home.arpa, example.com, example.net or example.org are not public domains.

mode accepts off, file and auto in any letter case. Any other value stops startup. file mode without both cert and key also stops startup.

[mail]

Mail settings have no command-line options. An environment variable takes precedence over pwikit.toml.

Key	Type	Default	Environment variable	Meaning
engine	string	smtp	EMAIL_ENGINE	smtp sends mail through host. console writes each message to the log instead. Any other value in pwikit.toml stops startup.
host	string	empty	EMAIL_HOST	SMTP server. While empty, messages are written to the log instead of being sent.
port	integer	587	EMAIL_PORT	SMTP port. Port 465 always uses an encrypted connection from the start, as if use_tls and implicit_tls were both on.
username	string	empty	EMAIL_USERNAME	Account for signing in to the SMTP server. While empty, pwikit does not sign in.
password	string	empty	EMAIL_PASSWORD	Password for username.
use_tls	boolean	false	EMAIL_USE_TLS	Switch the connection to TLS with STARTTLS after connecting.
implicit_tls	boolean	false	EMAIL_IMPLICIT_TLS	Use TLS from the start of the connection.
from	string	empty	EMAIL_DEFAULT_FROM	Sender address. Required: without it, sending fails.

For EMAIL_USE_TLS and EMAIL_IMPLICIT_TLS, the value true turns the setting on and any other non-empty value turns it off.

pwikit sends the password only over an encrypted connection, or to a mail server on the same machine (localhost). For a remote mail server that requires signing in, turn on use_tls or implicit_tls.

On Linux and macOS, when pwikit.toml contains password and other accounts on the machine can read the file, pwikit logs this warning at startup:

pwikit.toml holds the mail password and other accounts on this machine can read it

Make the file readable only by its owner with chmod 600 pwikit.toml.

[update]

Key	Type	Default	Environment variable	Meaning
auto	boolean	true	PWIKIT_UPDATE_AUTO	Install new releases by themselves when running as a system service.
public_banner	boolean	true	PWIKIT_UPDATE_PUBLIC_BANNER	Show every visitor the update banner for the 10 minutes before an automatic update. With false, only the admin panel announces it.
check	boolean	true	PWIKIT_UPDATE_CHECK	Look for new releases. With false, pwikit neither checks nor announces, and contacts neither GitHub nor a mirror.
window	string	03:00-05:00	PWIKIT_UPDATE_WINDOW	Hours in which releases are installed automatically, read in time_zone. Checks run every hour regardless. May cross midnight and must span at least 11 minutes.
time_zone	string	empty	PWIKIT_UPDATE_TIME_ZONE	The zone window is read in. Empty uses the server's time zone; a value overrides it. Use a name from the time zone database, such as Asia/Shanghai or Asia/Tokyo; a form like UTC+9 is not accepted. For a fixed offset write Etc/GMT-9: the sign is reversed, so it means UTC+9.
min_age	string	0s	PWIKIT_UPDATE_MIN_AGE	How long a release must have been out before it is installed automatically, such as 24h. With 0s, a release is scheduled in the next window as soon as it is found.
mirror	string	empty	PWIKIT_UPDATE_MIRROR	Mirror to download from when GitHub cannot be reached.

The matching command line options are -update-auto, -update-public-banner, -update-check, -update-window, -update-time-zone, -update-min-age and -update-mirror. When updates happen, the banner and rolling back are covered in Updating and rolling back.

[analytics]

Key	Type	Default	Environment variable	Meaning
google_tag_id	string	empty	GOOGLE_TAG_ID	Google tag ID. When set, the Google tag is added to the pages of every site on the instance.

This setting has no command-line option. The environment variable takes precedence over pwikit.toml.

Settings outside pwikit.toml

These settings exist only as command-line options of pwikit serve, some also as environment variables.

Option	Environment variable	Default	Meaning
-data-dir	PWIKIT_DATA_DIR	directory holding the executable	Data directory. Accepted by every command that uses one.
-secret-key	SECRET_KEY	contents of secrets/session-key	Key that signs sign-in sessions and links sent by email.
-static-dir	none	built-in assets	Directory to serve page assets (stylesheets, scripts, fonts and images) from instead of the built-in copy. Needed only when changing the web interface. See Deployment.
-log-file	none	standard error	File that log lines are appended to. When it reaches 10 MB it is renamed to <file>.1, and up to 5 older files are kept.
-sidecar	PWIKIT_FTML_SIDECAR	none	Path to the ftml sidecar program. Needed only by a pwikit built without the built-in wikitext renderer.
-no-migrate	none	off	Start without applying pending database changes.
-dev	none	off	Development mode. See Deployment.

The secrets directory

pwikit generates these files in secrets/ inside the data directory:

File	Contents
session-key	Key that signs sign-in sessions and links sent by email. Generated on the first start unless -secret-key or SECRET_KEY is given. Replacing or deleting it signs everyone out and invalidates links already sent by email.
postgres-password	Windows with the bundled PostgreSQL only. Password of the bundled database.
certs/	Certificates and the certificate authority account key for auto mode. When deleted, pwikit requests new certificates; certificate authorities limit how often the same certificate can be issued.

Note Do not delete or edit secrets/postgres-password. pwikit would generate a new password that the existing database does not accept, and could no longer connect to it.

Environment variables

Variable	Setting	Read by
PWIKIT_DATA_DIR	Data directory	every command that uses a data directory
DATABASE_URL	database	serve, createsite, site, admin, user, seed, import, reindex, migrate, backup create, backup restore, update
SECRET_KEY	-secret-key	serve
PWIKIT_FTML_SIDECAR	-sidecar	serve, render, reindex
MEDIA_UPLOAD_LIMIT	[server] upload_limit	serve
ABSOLUTE_MEDIA_UPLOAD_LIMIT	[server] storage_limit	serve
PWIKIT_TLS	[tls] mode	serve, service install
PWIKIT_TLS_LISTEN	[tls] listen	serve, service install
PWIKIT_TLS_CERT	[tls] cert	serve
PWIKIT_TLS_KEY	[tls] key	serve
PWIKIT_ACME_EMAIL	[tls] acme_email	serve
PWIKIT_ACME_DIRECTORY	[tls] acme_directory	serve
EMAIL_ENGINE	[mail] engine	serve
EMAIL_HOST	[mail] host	serve
EMAIL_PORT	[mail] port	serve
EMAIL_USERNAME	[mail] username	serve
EMAIL_PASSWORD	[mail] password	serve
EMAIL_USE_TLS	[mail] use_tls	serve
EMAIL_IMPLICIT_TLS	[mail] implicit_tls	serve
EMAIL_DEFAULT_FROM	[mail] from	serve
GOOGLE_TAG_ID	[analytics] google_tag_id	serve
PWIKIT_UPDATE_AUTO	[update] auto	serve, update
PWIKIT_UPDATE_PUBLIC_BANNER	[update] public_banner	serve, update
PWIKIT_UPDATE_CHECK	[update] check	serve, update
PWIKIT_UPDATE_WINDOW	[update] window	serve, update
PWIKIT_UPDATE_TIME_ZONE	[update] time_zone	serve, update
PWIKIT_UPDATE_MIN_AGE	[update] min_age	serve, update
PWIKIT_UPDATE_MIRROR	[update] mirror	serve, update
PWIKIT_DATABASE_PASSWORD_FILE	File holding the database password, read when the connection string has none	every command that connects to the database
PWIKIT_CONTAINER	Says pwikit runs in a container, where it is not updated automatically. The official image sets it	serve, update, service install
LISTEN_PID, LISTEN_FDS, LISTEN_FDNAMES	Listening sockets handed over by systemd	serve
SUDO_USER	Account the service runs as, when -user is not given	service install on Linux and macOS

SUDO_USER and the three LISTEN_ variables are set by sudo and systemd; do not set them by hand.

Sockets handed over by systemd

When systemd starts pwikit with socket activation, pwikit uses the sockets it receives instead of opening its own listen addresses. Name the sockets http and https with FileDescriptorName= in the socket unit. Unnamed sockets are used in order: the first for plain HTTP, the second for HTTPS. The HTTPS mode is still chosen from the settings as described above. pwikit service install does not use socket activation.