Configuration

Both deployments read the same variable names; what differs is who does the reading.

File	Read by	Applies to
.env beside run.py	Longbox itself, in app/config.py	anything that imports the app — run.py and the CLI
/etc/longbox.env	systemd, via EnvironmentFile=	only the units systemd starts: the service and the backup timer

Two consequences are worth knowing. Precedence runs opposite ways: .env is applied with setdefault, so a real environment variable beats it, while /etc/longbox.env is loaded last by the unit and beats the unit's own Environment= lines. And .env is found relative to run.py rather than to your shell, so on a systemd install the path would be /opt/longbox/.env — which the installer symlinks to /etc/longbox.env precisely so that a command run by hand sees the same configuration the service does.

Under Docker neither applies: .env is excluded from the image, though docker compose still reads it for ${VAR} substitution into the environment: block, which is a different mechanism that reaches only the variables that block names.

The settings that are not in a file

Two groups of settings can be set either in the environment or on the admin pages, and the admin page wins: SMTP (Admin → Mail) and the OAuth client credentials (Admin → Sign-in). The admin form writes to the setting table in the database, and the database is consulted before the environment.

This is worth knowing for exactly one reason, and it is the reason a migration goes wrong: copying /etc/longbox.env to a new host does not carry those settings, because they were never in it. They move with the database. See Migrating to a new machine — this catches people.

Everything else — paths, ports, trusted proxies, the public URL — lives only in the environment.

Variable reference

.env.example in the repository is the authoritative list and carries the reasoning for each one; this is the summary.

Paths

Variable	Default	What it does
LONGBOX_DATA_DIR	./data	Database, covers, uploads. The directory to back up. On systemd, changing it means re-running the installer — see Where the files go.
LONGBOX_UPLOAD_DIR	<data>/uploads	Browser-uploaded comics, one subdirectory per account. Holds the only copy of anything added that way.
LONGBOX_BROWSE_ROOTS	(empty)	Comma-separated directories the server-side file browser may enter. Empty means admins can browse anywhere the process can read.
LONGBOX_PAGE_CACHE_DIR	/var/cache/longbox	Extracted pages. Regenerable by definition, so never worth backing up or migrating.
LONGBOX_PAGE_CACHE_MB	2048	How large that cache may grow before whole comics are evicted.
LONGBOX_BACKUP_DIR	<data>/backups	Automatic database snapshots. Schedule and retention are set on the admin page, not here.

Network and security

Variable	Default	What it does
LONGBOX_HOST	0.0.0.0	Set to 127.0.0.1 behind a reverse proxy, so the port cannot be reached around it.
LONGBOX_PORT	8000	The port Longbox listens on.
LONGBOX_PUBLIC_URL	(empty)	The externally visible base URL. Required behind a proxy — password and OAuth links are built from it, and without it they take whatever Host header the caller sent.
LONGBOX_SECURE_COOKIES	(off)	Send session cookies only over HTTPS. Turning it on deliberately breaks sign-in over plain http://.
LONGBOX_TRUSTED_PROXIES	127.0.0.1,::1	Whose X-Forwarded-For to believe. Getting this wrong disables the login throttle or applies it to everyone at once — see Reverse proxy and HTTPS. Never *.
LONGBOX_TRUSTED_ORIGINS	(empty)	Extra origins allowed to submit forms, beyond the host the request arrived on.

Metadata and mail

Variable	Set on the admin page instead?	What it does
COMICVINE_API_KEY	Per account, on Settings	A server-wide fallback key. Each account can save its own.
LONGBOX_SMTP_*	Yes — Admin → Mail wins	Host, port, security, username, password, from address.
LONGBOX_OAUTH_*_CLIENT_ID / _SECRET	Yes — Admin → Sign-in wins	Google, Apple and Facebook credentials.