Configuration reference

Vaultigen is configured through .env like any Laravel application.

• Docker Compose: the .env next to compose.yaml. Apply changes with docker compose up -d --wait. See Docker Compose for what is fixed and what you can change.
• Manual installation: the .env in the application directory. Run php artisan config:clear (or config:cache again) and restart the queue worker after every change.

Docker Compose

Where settings come from

Compose reads .env in two ways:

1. To fill in compose.yaml itself: VAULTIGEN_IMAGE_TAG, VAULTIGEN_DOMAIN, DB_PASSWORD, COMPOSE_FILE and the proxy network settings.
2. As the environment of every application container (env_file), so every variable on this page can be set there.

compose.yaml then sets a few values explicitly, and these win over .env. They are fixed because the stack depends on them:

Fixed in compose.yaml	Value
APP_ENV, APP_DEBUG	production, false
APP_URL	https:// + VAULTIGEN_DOMAIN
SESSION_SECURE_COOKIE	true
DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME	pgsql, database, 5432, vaultigen, vaultigen
VAULTIGEN_APP_KEY_FILE, VAULTIGEN_INSTALLATION_FILE, VAULTIGEN_KEK_FILE, VAULTIGEN_BACKUP_KEY_FILE	/keys/app.key, /keys/installation.json, /keys/kek.json, /keys/backup.json
VAULTIGEN_KEK_PROVIDER	file
VAULTIGEN_BACKUP_ROOT	/backups
VAULTIGEN_WEB_MODE	https (http with the proxy override)

MAIL_MAILER defaults to smtp and can be changed in .env. An APP_KEY in .env takes precedence over /keys/app.key; it is only needed when you move a manual installation. Variables exported in your shell take precedence over .env when Compose fills in compose.yaml; do not export Vaultigen settings in the shell.

Values in .env are literal. Put values containing $, #, spaces or quotes inside single quotes and escape an apostrophe as \'. Never source the file.

Each container builds its own configuration cache at start. After any change, run docker compose up -d --wait; Compose recreates the containers whose settings changed. docker compose restart does not load edited settings.

Docker-only settings

Variable	Default	Purpose
VAULTIGEN_IMAGE_TAG	— (required)	Exact image release for every application service. Changing it is an update.
VAULTIGEN_DOMAIN	— (required)	Public hostname; also the HTTPS certificate name.
DB_PASSWORD	— (required)	Password of the bundled PostgreSQL database. At least 24 characters; never change it after setup.
COMPOSE_FILE	compose.yaml	Set to compose.yaml:compose.proxy.yaml for an existing reverse proxy.
VAULTIGEN_HTTP_PORT	8080	Loopback port of the proxy override.
VAULTIGEN_NETWORK_SUBNET, VAULTIGEN_NETWORK_GATEWAY, VAULTIGEN_NETWORK_RANGE, VAULTIGEN_WEB_ADDRESS	172.31.250.0/24, .1, .128/25, .10	Fixed private network of the proxy override; change only on a collision.
VAULTIGEN_TRUSTED_PROXIES	the network gateway (proxy override)	Set for a proxy in another container or host, or 172.31.250.10 with rootless Podman.

The template env.example also turns on the nightly backup (VAULTIGEN_BACKUP_SCHEDULE_ENABLED=true), which is off by default for manual installations.

Persistent paths

Host (next to compose.yaml)	Container	Contents
data/postgres/	/var/lib/postgresql (database)	PostgreSQL data
data/storage/	/app/storage	Attachments, retained imports, runtime files
data/keys/	/keys	app.key, installation.json, kek.json, backup.json
data/caddy/	/data (web)	HTTPS certificates
backups/	/backups	Verified backup sets

The defaults in the tables below are those of a manual installation. On a Docker host, storage/ is data/storage/, the key files are in data/keys/ and backup sets are in backups/.

Application

Variable	Default	Purpose
APP_ENV	—	Must be production on real installations.
APP_DEBUG	—	Must be false in production.
APP_URL	—	The public HTTPS address.
APP_KEY	—	Created once with key:generate. Never change it afterwards.

Web and proxies

Variable	Default	Purpose
VAULTIGEN_TRUSTED_PROXIES	empty	Comma-separated proxy addresses or CIDRs whose forwarded headers are trusted.
VAULTIGEN_TRUSTED_HOSTS	empty	Regular expressions of accepted host names.
VAULTIGEN_HSTS_MAX_AGE	31536000	HSTS max age in seconds; 0 disables HSTS.
VAULTIGEN_HSTS_INCLUDE_SUBDOMAINS	false	Add includeSubDomains.
VAULTIGEN_HSTS_PRELOAD	false	Add preload.

Keys

Variable	Default	Purpose
VAULTIGEN_KEK_PROVIDER	file	file or environment.
VAULTIGEN_KEK_FILE	storage/app/private/kek.json	Location of the KEK keyring.
VAULTIGEN_KEK_KEYRING	—	KEK keyring JSON when the provider is environment.
VAULTIGEN_BACKUP_KEY_FILE	storage/app/private/backup.json	Location of the backup keyring.
VAULTIGEN_BACKUP_KEYRING	—	Backup keyring supplied through the environment.
VAULTIGEN_INSTALLATION_FILE	storage/app/private/installation.json	Location of the installation identity file.
VAULTIGEN_APP_KEY_FILE	—	Protected file holding the application key; used only when APP_KEY is empty.
VAULTIGEN_INSTALLATION_ID	from installation.json	Installation ID override.
VAULTIGEN_AUDIT_KEY	from installation.json	Audit key override.
PASSKEYS_USER_HANDLE_SECRET	from installation.json	Passkey secret override.

Storage, backups and jobs

Variable	Default	Purpose
VAULTIGEN_BACKUP_ROOT	storage/app/private/backups	Where backup sets are written.
VAULTIGEN_BACKUP_TEMPORARY_ROOT	storage/app/private/backup-work	Private disk-backed snapshot/restore staging; provision adequate free space.
VAULTIGEN_BACKUP_SCHEDULE_ENABLED	false	Opt in to scheduler-driven backups; remove old backup cron first.
VAULTIGEN_BACKUP_SCHEDULE	30 2 * * *	Valid five-field cron expression.
VAULTIGEN_BACKUP_TIMEZONE	UTC	Valid timezone for backups and local pruning.
VAULTIGEN_BACKUP_MAX_AGE_HOURS	48	Positive age limit for the Operations backup warning.
VAULTIGEN_BACKUP_RETENTION_ENABLED	false	Opt in to pruning verified expired local sets at 05:00; always preserves the newest verified set.
VAULTIGEN_BACKUP_RETENTION_DAYS	30	Positive local retention in days; independent of off-host copying.
VAULTIGEN_STORAGE_PATH	storage/app/private	Volume checked for storage headroom.
VAULTIGEN_MIN_FREE_BYTES	268435456	Headroom warning threshold (256 MB).
VAULTIGEN_ATTACHMENT_MAX_BYTES	26214400	Maximum size of one attachment (25 MB).
VAULTIGEN_VAULT_ATTACHMENT_MAX_BYTES	524288000	Maximum total attachments per vault (500 MB).
VAULTIGEN_BACKUP_JOB_TIMEOUT	3600	Backup job timeout in seconds.
VAULTIGEN_ROTATION_JOB_TIMEOUT	3600	Key-rotation job timeout in seconds.
VAULTIGEN_IMPORT_JOB_TIMEOUT	3600	Import job timeout in seconds.
VAULTIGEN_IMPORT_QUEUE_TIMEOUT	3600	How long an import may wait for a worker.
VAULTIGEN_IMPORT_ATTACHMENT_MAX_BYTES	67108864	Maximum total size of all attachments in one import (64 MB).

License

Variable	Default	Purpose
VAULTIGEN_LICENSE	—	The license block on one line. When set, it overrides the license installed in the application. See Installing a license.

Development only

Variable	Purpose
VAULTIGEN_MFA_DISABLED	Skips the second factor. Honored only with APP_ENV=local or testing; the application refuses to start with it set anywhere else.

Settings that administrators change at runtime (MFA methods, sessions, retention, vault creation, site icons, security recipients) live in System → Settings, not in .env.