Skip to content

Environment Variables

Most feature settings live in the Admin panel. Environment variables configure startup, deployment behavior, and optional bootstrap defaults. This page is a reference; see Docker Install and Reverse Proxy and HTTPS for the recommended env files.

How do I bind the server and find the database?

Variable Default Purpose
PORT 3000 Express listen port
NODE_ENV development unless set Runtime environment label shown in status
DB_PATH db/bills.db for Node, /data/db/bills.db in Docker SQLite database path
BACKUP_PATH Beside the database for Node, /data/backups in Docker Managed backup directory
TZ Runtime default Container timezone
CORS_ORIGIN unset Comma-separated allowed origins for a deliberately split frontend deployment
REPO_API_URL Internal Forgejo repository API Override update-check API base

See Database Paths for the production path conventions and how /data is mounted.

How do I seed the first admin and user?

Variable Default Purpose
INIT_ADMIN_USER unset Bootstrap admin username
INIT_ADMIN_PASS unset Bootstrap admin password, minimum 8 characters
INIT_REGULAR_USER unset Optional seeded regular username
INIT_REGULAR_PASS unset Optional seeded regular password, minimum 8 characters

Remove or rotate after first use

Present values may update matching seeded account passwords on startup. Once the admin has signed in and rotated, comment these out of the Compose file so a future container restart cannot silently re-overwrite a changed password.

See First-Run Setup for the full walkthrough.

How do I set up HTTPS, cookies, and CSRF?

Variable Default Purpose
HTTPS unset Enables HSTS when true; also acts as a session-cookie Secure fallback
COOKIE_SECURE inferred Explicit Secure flag override for bt_session
CSRF_HTTP_ONLY true (changed in v0.35) httpOnly flag for the CSRF cookie. The SPA fetches the token from GET /api/auth/csrf-token and stores it in memory, so the cookie does not need to be readable by JavaScript. Set false only for custom clients that read document.cookie.
CSRF_SAME_SITE strict CSRF cookie SameSite value
CSRF_SECURE true Allows Secure CSRF cookies when the request is HTTPS
CSRF_COOKIE_NAME bt_csrf_token CSRF cookie name

See Reverse Proxy and HTTPS and Tune Security Settings for recommended combinations and the X-Forwarded-Proto setup.

How do I tune bank sync, encryption, and WebAuthn?

Variable Default Purpose
DATA_IMPORT_ENABLED true Set false to disable import endpoints
BANK_SYNC_ENABLED false SimpleFIN enable fallback when no Admin setting exists
SIMPLEFIN_SYNC_DAYS 30 Routine SimpleFIN lookback fallback (clamped to the SYNC_DAYS_MAX hard limit)
SIMPLEFIN_SYNC_INTERVAL_HOURS 4 SimpleFIN worker interval fallback
TOKEN_ENCRYPTION_KEY auto-generated in SQLite settings Optional operator-managed secret-encryption key, minimum 32 bytes. When set, all DB-key-encrypted secrets are transparently re-encrypted with the env key on first startup.
WEBAUTHN_RP_ID localhost Relying party ID for WebAuthn / FIDO2 hardware key 2FA. Set to your production domain.
WEBAUTHN_ORIGIN localhost Relying party origin for WebAuthn. Set to https://your-domain in production.
API_PORT (falls back to PORT) Vite dev-server /api proxy target. Used by vite.config.mjs when 3000 is already occupied.

Admin database settings take precedence for bank sync. For the full encryption-key story see Tune Security Settings.

How do I set up OIDC fallbacks?

These values are used only when the Admin panel has not stored a value in the database. Database-backed Admin settings always win.

Variable Default
OIDC_PROVIDER_NAME authentik
OIDC_ISSUER_URL unset
OIDC_CLIENT_ID unset
OIDC_CLIENT_SECRET unset
OIDC_TOKEN_AUTH_METHOD client_secret_basic
OIDC_REDIRECT_URI unset
OIDC_SCOPES openid email profile groups
OIDC_ADMIN_GROUP unset
OIDC_AUTO_PROVISION true

See Connect Authentik / OIDC for the full rollout checklist and the Authentik provider setup.

How do I control migrations and cleanup?

Variable Default Purpose
SESSION_CLEANUP_INTERVAL_MS 86400000 Additional expired-session cleanup interval
RUN_DB_MIGRATIONS true in Docker entrypoint Set false to bypass entrypoint migration execution

SMTP, scheduled backup, cleanup, and daily reminder settings are managed in the Admin panel and stored in SQLite — there are no environment fallbacks for them.

See also

Next steps