Configuration

Kalzit reads its settings from three layers: built-in defaults, then the configuration file kalzit.toml, then environment variables. An environment variable wins over the file. Network and TLS settings exist only here, never in the web UI, so a wrong value cannot lock an admin out of the settings page.

Settings in the web UI arrive with M1. What is set in the file or the environment will show up there as locked, with its source.

Where the file is

Kalzit uses the first file it finds:

1. the file given with --config <file> (or the KALZIT_CONFIG variable),
2. kalzit.toml in the current directory,
3. on Windows %ProgramData%\Kalzit\kalzit.toml, on Linux /etc/kalzit/kalzit.toml.

Without a file, the defaults apply. Unknown keys are an error, so a typo does not go unnoticed. Check a file with kalzit check-config.

Environment variables

Every key has a variable named KALZIT_<SECTION>_<KEY> in upper case, for example KALZIT_SERVER_HTTP_ADDR for http_addr in [server]. The value is read as a TOML value when it is one (a number, true or false, a list like ["10.0.0.0/8"]) and as text otherwise.

Two more variables are not settings of a section:

Variable	Meaning
KALZIT_CONFIG	Path of the configuration file.
KALZIT_SETUP_TOKEN	A fixed setup code for automated installs, see First start.

An example

[server]
http_addr = "127.0.0.1:3000"
public_url = "https://kalzit.example.com"

[security]
trusted_proxies = ["127.0.0.1/32", "::1/128"]

[log]
format = "json"

[server]

Key	Default	Meaning
http_addr	"0.0.0.0:3000"	Address and port for plain HTTP. An empty string turns HTTP off.
https_addr	"" (off)	Address and port for HTTPS, for example "0.0.0.0:443". Needs tls.cert_file and tls.key_file.
public_url	not set	The address users open, for example https://kalzit.example.com. Used for the origin check and for links. Must start with http:// or https://.
redirect_http_to_https	true	When HTTPS is on, plain HTTP answers with a redirect to HTTPS. /healthz and /readyz stay reachable over HTTP.

At least one of http_addr and https_addr must be set.

[tls]

Key	Default	Meaning
cert_file	not set	Certificate chain as a PEM file.
key_file	not set	Private key as a PEM file.
min_version	"1.2"	Lowest TLS version: "1.2" or "1.3".
reload_interval_secs	60	How often the two files are checked for changes, in seconds. 0 turns reloading off.

[security]

Key	Default	Meaning
hsts	true	Send Strict-Transport-Security on HTTPS responses.
hsts_max_age_secs	31536000	HSTS duration in seconds (one year).
trusted_proxies	[]	IP ranges of reverse proxies whose X-Forwarded-* headers are trusted, for example ["10.0.0.0/8"]. Everyone else’s are ignored.
login_max_failures	10	Failed sign-ins allowed per window before further attempts are refused.
login_window_secs	900	Length of that window in seconds (15 minutes).

[sessions]

Key	Default	Meaning
lifetime_hours	720	Longest life of a session (30 days). At least 1.
idle_timeout_hours	168	A session without activity for this long ends (7 days). 0 turns the idle limit off.

[database]

Key	Default	Meaning
url	SQLite file	sqlite:... or postgres://.... Without it, Kalzit uses kalzit.db in the data directory.
max_connections	10	Size of the connection pool.

[paths]

Key	Default	Meaning
data_dir	"data"	Data directory, relative to the current directory unless absolute. Holds the SQLite database and, during setup, setup-token.txt.

[log]

Key	Default	Meaning
level	"info"	A log filter, for example "info" or "kalzit=debug,info".
format	"text"	"text" or "json".