Configuration

Gansey reads its settings from five places. Later ones win:

1. built-in defaults;
2. gansey.toml: the file --config (or GANSEY_CONFIG) names, else ./gansey.toml when it exists;
3. a .env file: the file GANSEY_ENV_FILE names, else ./.env when it exists;
4. the real environment;
5. command-line flags.

The .env file holds one NAME=value per line and is read into the environment at start-up. A variable already set in the real environment is left alone, which is how the environment beats the file. Quote values that contain spaces, such as GANSEY_SITE_NAME="Example Studio site". Empty values are ignored. A value that does not parse, such as a port that is not a number, stops the binary with an error that names the variable. In environment variables, booleans accept true/false, yes/no, on/off or 1/0.

A sensible split is to keep shared settings in gansey.toml and anything secret or per-machine (the database URL, SMTP password, licence key) in .env or the real environment. Copy gansey.example.toml and .env.example from the repository to start.

Flags

Flag	Commands	Sets
--config <path>	all	which gansey.toml to read
--bind <address>	serve	[server].bind
--port <n>, -p	serve	[server].port
--database-url <url>	serve, migrate, doctor, user, backup and the other database commands	[database].url
--migrate	serve	run migrations before serving

[server]

Key	Variable	Default	Meaning
bind	GANSEY_BIND	127.0.0.1	address to listen on; 0.0.0.0 for all interfaces
port	GANSEY_PORT	8080	port to listen on
env	GANSEY_ENV	local	local, dev, staging or production
error_reporting	GANSEY_ERROR_REPORTING	follows env	include error detail in responses and error pages
admin_path	GANSEY_ADMIN_PATH	/admin	where the admin answers, such as /studio

See Environments and indexing for what env changes.

[database]

Key	Variable	Default	Meaning
url	DATABASE_URL	none	Postgres URL, such as postgres://gansey:secret@localhost:5432/gansey; empty runs without a database

[site]

Key	Variable	Default	Meaning
name	GANSEY_SITE_NAME	Gansey site	site name
hostname	GANSEY_SITE_HOSTNAME	localhost	site hostname

Both are used when the site's row is first created in the database. After that the stored values win; change them in the admin under Theme & settings → Site.

[auth]

Key	Variable	Default	Meaning
public_url	GANSEY_PUBLIC_URL or GANSEY_URL	http://<bind>:<port>	the site's public origin, used in emailed links and the sitemap line in robots.txt
session_days	GANSEY_SESSION_DAYS	14	how long a browser stays signed in
secure_cookies	GANSEY_SECURE_COOKIES	on when public_url is https	mark the session cookie Secure
members_home	GANSEY_MEMBERS_HOME	/	where members land after signing in on the public site

Behind a reverse proxy, set public_url to the address visitors use, such as https://example.test, or emailed links will point at the internal address.

[email]

Leave the section out and no email is sent; see Users and sign-in for what happens instead.

Key	Variable	Default	Meaning
smtp_host	GANSEY_SMTP_HOST	required	SMTP server
smtp_port	GANSEY_SMTP_PORT	587	SMTP port
username	GANSEY_SMTP_USERNAME	none	SMTP user
password	GANSEY_SMTP_PASSWORD	none	SMTP password
from	GANSEY_EMAIL_FROM	required in the file	sender, such as Example <[email protected]>
implicit_tls	GANSEY_SMTP_IMPLICIT_TLS	false	false upgrades the connection with STARTTLS; true uses TLS from the start (usually port 465)

GANSEY_SMTP_HOST on its own switches email on; the sender then defaults to no-reply@<hostname>.

[backups]

Key	Variable	Default	Meaning
dir	GANSEY_BACKUP_DIR	./data/backups	where backups go
keep	GANSEY_BACKUP_KEEP	14	how many to keep
nightly	GANSEY_BACKUP_NIGHTLY	true	take one every night
hour	GANSEY_BACKUP_HOUR	3	the nightly hour, in UTC

[logs]

Key	Variable	Default	Meaning
dir	GANSEY_LOG_DIR	./data/logs	folder for log files
to_file	GANSEY_LOG_FILE	true	also write one JSON line per event to gansey.log.<date>
keep_days	GANSEY_LOG_KEEP_DAYS	14	delete daily files older than this

The console always gets readable lines; only gansey serve writes files. RUST_LOG sets how much is logged (default info,gansey=debug,tower_http=info).

[media]

Key	Variable	Default	Meaning
root	GANSEY_MEDIA_ROOT	./data/media	uploads and their generated sizes

[updates]

Key	Variable	Default	Meaning
hub_url	GANSEY_HUB_URL	none	the hub this site updates from; unset turns updates off
licence_key	GANSEY_LICENCE_KEY	none	licence key, GSY-XXXX-XXXX-XXXX-XXXX
channel	GANSEY_UPDATE_CHANNEL	stable	stable, beta or nightly
auto_patch	GANSEY_AUTO_PATCH	false	install x.y.Z patch releases automatically
public_key	GANSEY_UPDATE_PUBLIC_KEY	pinned on first use	hex key releases must be signed with
check_interval_hours	GANSEY_UPDATE_CHECK_HOURS	6	how often to check
hosting_attest	GANSEY_HOSTING_ATTEST	none	set by our hosting only; leave it unset

The channel, licence key and auto-patch switch can also be set under Updates in the admin. Values saved there are stored in the database and win over the file.

[modules]

Key	Variable	Default	Meaning
dir	GANSEY_MODULES_DIR	./data/modules	where module packages live
watch	GANSEY_MODULES_WATCH	true	reload a module when its files change
files_dir	GANSEY_MODULE_FILES_DIR	module-files beside the media folder	files modules store
allow_unsigned	GANSEY_MODULES_ALLOW_UNSIGNED	true	let Modules → Add your own install packages the hub has not signed; the command line always may

[signing]

Key	Variable	Default	Meaning
key_file	GANSEY_SIGNING_KEY_FILE	none	the site's ed25519 signing key, lent to modules allowed to sign files

GANSEY_SIGNING_KEY holds the key itself (hex or base64) and wins over the file. gansey signing-key new --out <file> makes one. Most sites never need it; see Publishing.