Environment Variables

This reference is based on these source files:

• cashlytics/.env.example
• cashlytics/docker-compose.selfhost.yml

Required baseline for self-hosting

Set these before first boot:

POSTGRES_PASSWORD=replace_with_long_random_password
AUTH_SECRET=replace_with_long_random_secret
NEXT_PUBLIC_APP_URL=https://your-domain.tld
AUTH_TRUST_HOST=true
SINGLE_USER_MODE=true

Full variable reference

Variable	Required	Default	Purpose	Recommended value
DATABASE_URL	Yes (manual setup)	Generated in Compose from POSTGRES_PASSWORD	PostgreSQL connection string used by the app	postgresql://cashlytics:<password>@postgres:5432/cashlytics
POSTGRES_PASSWORD	Yes	None	Password for PostgreSQL container user	Long random secret (32+ chars)
NEXT_PUBLIC_APP_URL	Yes	http://localhost:3000	Public URL used by frontend/runtime	Your real HTTPS domain
NEXT_PUBLIC_DEFAULT_LOCALE	No	de	Default language for new sessions	en or de
NEXT_PUBLIC_DEFAULT_CURRENCY	No	EUR	Default currency in UI	EUR, USD, GBP, CHF
AUTH_SECRET	Yes	None	Auth.js secret for tokens/session security	Strong random secret (npx auth secret)
AUTH_TRUST_HOST	Strongly recommended	true in Compose	Trust forwarded host headers behind proxy/domain	true for VPS/reverse proxy
SINGLE_USER_MODE	Required by policy	true in Compose	Registration policy	true for personal use, false for open registration
SINGLE_USER_EMAIL	No	Empty	Used by migration/backfill flows in single-user setups	Owner email address
OPENAI_API_KEY	No	Empty	Enables AI Assistant features	Valid OpenAI API key
EMAIL_TRANSPORT	No	Auto/empty	Email backend mode (smtp or sendmail)	smtp in most setups
SMTP_HOST	No*	Empty	SMTP server hostname	Provider hostname
SMTP_PORT	No*	Empty	SMTP server port	587 (STARTTLS) or 465 (TLS)
SMTP_USER	No*	Empty	SMTP auth username	SMTP account username
SMTP_PASS	No*	Empty	SMTP auth password/token	App password or provider token
SMTP_FROM	No*	SMTP_USER fallback	Sender address for outgoing mails	noreply@your-domain.tld
APP_URL	No	NEXT_PUBLIC_APP_URL fallback	Server-side absolute URL for email links	Same as public app URL
VAPID_PUBLIC_KEY	No**	Empty	Public key for browser push subscription	Generated via web-push
VAPID_PRIVATE_KEY	No**	Empty	Private key to sign push messages	Generated via web-push
VAPID_SUBJECT	No**	Empty	Contact URI for VAPID identity	mailto:ops@your-domain.tld
CRON_SECRET	No**	Empty	Bearer token for protected cron endpoint	Random hex secret
NOTIFICATION_SCHEDULE	No**	0 8 * * *	Cron schedule for upcoming-payment checks	Keep default or adjust timezone needs

* Required only if SMTP/password-reset/welcome-email features are enabled.
** Required only if push notifications and reminder scheduling are enabled.

Recommended profiles

Minimal (no AI, no SMTP, no push)

POSTGRES_PASSWORD=...
AUTH_SECRET=...
NEXT_PUBLIC_APP_URL=https://app.example.com
AUTH_TRUST_HOST=true
SINGLE_USER_MODE=true

AI enabled

OPENAI_API_KEY=sk-...

SMTP enabled

EMAIL_TRANSPORT=smtp
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=mailer@example.com
SMTP_PASS=...
SMTP_FROM=noreply@example.com
APP_URL=https://app.example.com

Push reminders enabled

VAPID_PUBLIC_KEY=...
VAPID_PRIVATE_KEY=...
VAPID_SUBJECT=mailto:ops@example.com
CRON_SECRET=...
NOTIFICATION_SCHEDULE=0 8 * * *

Validation and safety checks

• Keep .env out of git.
• Use long random values for POSTGRES_PASSWORD, AUTH_SECRET, and CRON_SECRET.
• Keep NEXT_PUBLIC_APP_URL and APP_URL aligned with your real domain.
• If authentication behaves incorrectly behind a proxy, verify AUTH_TRUST_HOST=true.
• If emails fail, check SMTP transport mode, port, credentials, and sender domain policies.