Configuration

Environment Variables

Full reference for all Retrospend environment variables. These are set in your .env file. Some operational settings (audit log privacy mode, import concurrency, AI configuration, and registration controls) are managed at runtime via the Admin Panel instead.

Note

The .env.example file in the repository contains all variables with comments. Copy it to .env and fill in your values.

bashbash

cp .env.example .env
# Then edit .env with your values

Core

Variable	Required	Default	Description
AUTH_SECRET	required	-	Secret used to sign sessions and auth tokens. Generate with: openssl rand -base64 32
PUBLIC_URL	required	-	Full public URL of your instance (e.g. https://your-domain.com). Used for auth redirects and email links.
DATABASE_URL	required	-	PostgreSQL connection string. In Docker: postgresql://user:pass@postgres:5432/retrospend
TRUSTED_ORIGINS	optional	-	Comma-separated list of additional origins to trust for auth requests. Useful for tunnel setups.

Database

Variable	Required	Default	Description
POSTGRES_USER	required	postgres	PostgreSQL username.
POSTGRES_PASSWORD	required	-	PostgreSQL password. Use a strong random value.
POSTGRES_DB_NAME	required	retrospend	PostgreSQL database name.

Sidecar

Variable	Required	Default	Description
WORKER_API_KEY	required	-	Shared secret between the main app and the sidecar. Generate with: openssl rand -base64 32
SIDECAR_URL	optional	http://retrospend-sidecar:8080	Internal URL of the sidecar service (background jobs + importer).

Storage

Variable	Required	Default	Description
UPLOAD_DIR	optional	/data/uploads	Directory path for uploaded files. Mounted as a Docker volume.

AI Import (LLM)

Variable	Required	Default	Description
OPENROUTER_API_KEY	optional	-	OpenRouter API key. Required if using external AI for bank import. Get one at openrouter.ai
OPENROUTER_MODEL	optional	qwen/qwen-2.5-7b-instruct	OpenRouter model to use for import processing.
OLLAMA_ENDPOINT	optional	http://ollama:11434/api/generate	Ollama API endpoint. Use http://host.docker.internal:11434/api/generate if Ollama runs on the host.
LLM_MODEL	optional	qwen2.5:7b	Ollama model name. Must be pulled first.
ENRICH_BATCH_SIZE	optional	20	Merchants per LLM enrichment batch.
ENRICH_CONCURRENCY	optional	3	Max parallel enrichment LLM calls.
PDF_CONCURRENCY	optional	3	Max parallel PDF chunk parsing LLM calls.

Email (SMTP)

Variable	Required	Default	Description
SMTP_HOST	optional	-	SMTP server hostname.
SMTP_PORT	optional	587	SMTP server port.
SMTP_USER	optional	-	SMTP authentication username.
SMTP_PASSWORD	optional	-	SMTP authentication password.
EMAIL_FROM	optional	-	From address for outgoing emails. Example: Retrospend <[email protected]>
UNSUBSCRIBE_SECRET	optional	-	Secret used to sign one-click unsubscribe links in notification emails. Generate with: openssl rand -base64 32

App Behavior

Variable	Required	Default	Description
NEXT_PUBLIC_SHOW_LANDING_PAGE	optional	true	Show the marketing landing page at /
NEXT_PUBLIC_ENABLE_LEGAL_PAGES	optional	false	Show Terms and Privacy Policy links in the UI.

Updating

Database