Environment variables
Environment variables are the settings you put in .env to configure your LF instance. This reference lists the available variables, their defaults, and what each one does.
Container and database
APP_OptionalIMAGE_ TAG The Lumina Finance Docker image tag. Pinning a version doesn't disable update checks.
DB_RequiredHOST The hostname or IP address of your PostgreSQL server.
ExampleDB_HOST=postgres DB_RequiredPORT The port LF uses to connect to PostgreSQL.
ExampleDB_PORT=5432 DB_RequiredNAME The database LF connects to.
ExampleDB_NAME=lumina DB_RequiredUSER The PostgreSQL admin role LF uses at startup to create its separate migration and application roles.
ExampleDB_USER=lumina DB_RequiredPASSWORD The password for the PostgreSQL admin role.
For an existing database, this value must match its admin password.
MIGRATOR_OptionalDB_ PASSWORD The password for
lumina_migrator, the role that owns LF's database schema and runs migrations. If you leave it unset, LF generates a password and saves it in/data/secrets/migrator_db_passwordto reuse on later starts.If generated by LF, the data volume must be persisted or you risk permanently losing or corrupting your data.
APP_OptionalDB_ PASSWORD The password for
lumina_app, the role LF uses for app requests. This role follows the database's row-level security rules to keep each user's data separate.If you leave it unset, LF generates a password and saves it in
/data/secrets/app_db_password. If it is generated by LF, the data volume must be persisted or you risk permanently losing or corrupting your data.
Instance URL and update checks
APP_OptionalURL The FQDN you use to open LF. LF uses it for password-reset links, the single sign-on callback, and default passkey settings.
This address is also included in LF's allowed browser origins. See Setting the URL for the matching
.envconfiguration.ExampleAPP_URL=https://example.com UPDATE_OptionalCHECKS_ ENABLED Controls whether LF checks GitHub releases and Docker Hub for a newer version. Set it to
falseto turn off the checks and their notices. Automatic update checks explains when you'll see an update.ExampleUPDATE_CHECKS_ ENABLED=true
Stored secrets and token signing
APP_OptionalENCRYPTION_ KEY The Fernet key LF uses to encrypt stored secrets, such as authenticator secrets and OIDC client secrets. If you don't supply one, LF generates it on first start and saves it in
/data/secrets/app_encryption_key.Keep this key safe, since losing it makes those secrets unreadable. To replace an existing key, follow Rotating the encryption key.
JWT_OptionalACCESS_ PRIVATE_ KEY_ PATH The path inside the app container to the RSA private key used to sign access tokens. LF generates a key at this location if one isn't provided. To use your own file, see Signing keys and JWKS.
ExampleJWT_ACCESS_ PRIVATE_ KEY_ PATH=/data/keys/access_private.pem JWT_OptionalREFRESH_ PRIVATE_ KEY_ PATH The path inside the app container to the RSA private key used to sign refresh tokens. LF generates this key separately from the access-token key, and both files need to remain available when you recreate the container.
ExampleJWT_REFRESH_ PRIVATE_ KEY_ PATH=/data/keys/refresh_private.pem JWT_OptionalACCESS_ TOKEN_ EXPIRE_ SECONDS How long an access token is valid.
JWT_OptionalREFRESH_ TOKEN_ EXPIRE_ SECONDS How long a refresh token is valid.
JWT_OptionalISSUER The issuer LF includes in its signed tokens.
JWT_OptionalACCESS_ KID The identifier for the access-token signing key, included in token headers and the public JWKS. It doesn't need to match the key filename, and changing it doesn't generate a new key.
JWT_OptionalREFRESH_ KID The identifier for the refresh-token signing key, included in token headers and the public JWKS. As with the access-key identifier, this labels the key without replacing its file.
Passkeys and second factors
WEBAUTHN_OptionalRP_ ID The domain your passkeys are tied to, called the relying-party ID. Specify a domain name without a connection scheme, port, or path. You usually don't need to set it separately from
APP_URL.Existing passkeys remain tied to their original ID, so check the guidance on changing an existing URL before changing it.
ExampleWEBAUTHN_RP_ ID=example.com WEBAUTHN_OptionalORIGINS The browser origins LF accepts for passkey registration and sign-in. Values given here will replace the
APP_URLdefault.ExampleWEBAUTHN_ORIGINS=https://example.com WEBAUTHN_OptionalCHALLENGE_ EXPIRE_ SECONDS How long a passkey prompt stays valid.
MFA_OptionalCHALLENGE_ TOKEN_ EXPIRE_ SECONDS How long you have to complete the second-factor step after entering your password during sign-in.
TWO_OptionalFACTOR_ STAGING_ EXPIRE_ SECONDS How long an unconfirmed first passkey and pending recovery codes are kept during setup.
Password reset and email
EMAIL_OptionalBACKEND How LF handles outgoing password-reset emails. Set it to
smtpto send them through your email provider. The default,logging, writes the messages and their reset links to log.ExampleEMAIL_BACKEND=smtp SMTP_ConditionalHOST EMAIL_BACKENDThe hostname of your provider's SMTP server.
ExampleSMTP_HOST=smtp.example.com SMTP_ConditionalSMTP authenticationUSERNAME The username your provider supplies for SMTP authentication. This may be your email address or a separate username, depending on the provider.
ExampleSMTP_USERNAME=email@example.com SMTP_ConditionalSMTP authenticationPASSWORD The password your provider supplies for SMTP authentication.
SMTP_OptionalPORT The port LF connects to on your SMTP server.
ExampleSMTP_PORT=587 SMTP_OptionalUSE_ TLS Whether LF uses TLS for its connection to the SMTP server.
ExampleSMTP_USE_ TLS=true MAIL_OptionalFROM The sender address for outgoing emails. It defaults to
SMTP_USERNAME, and messages will always use the display name "Lumina Finance (Self-Hosted)".ExampleMAIL_FROM=email@example.com PASSWORD_OptionalRESET_ TOKEN_ EXPIRE_ SECONDS How long a password-reset link remains valid.
PASSWORD_OptionalRESET_ DAILY_ EMAIL_ LIMIT The maximum number of password-reset emails a user account can receive in a rolling 24-hour period. Note that increasing this limit won't allow another email to be sent while an unused, unexpired link exists.
Lumina Finance has a builtin rate limiter for the number of emails that can be sent in a given period, which is controlled by the following two env vars. If you ever have any issues receiving email reset links, please make sure you have set a sensible value for the following two variables.
Single sign-on
APP_URL must be set correctly before SSO will be turned on. An incorrect APP_URL will prevent SSO from being enabled even if all the following variables contain the correct values.
OIDC_OptionalGENERIC_ CLIENT_ ID The client ID you receive when you register LF with your identity provider.
ExampleOIDC_GENERIC_ CLIENT_ ID=lumina-finance OIDC_ConditionalGENERIC_ ISSUER OIDC_GENERIC_CLIENT_IDThe issuer URL published by your provider. Copy it exactly from your OIDC provider, including any trailing slash.
ExampleOIDC_GENERIC_ ISSUER=https://auth.example.com/application/o/lumina-finance/ OIDC_ConditionalGENERIC_ CLIENT_ SECRET OIDC_GENERIC_CLIENT_IDThe client secret issued with your client ID.
OIDC_OptionalGENERIC_ DISPLAY_ NAME The provider name on the sign-in button. Use a name you'll recognize, such as
Authentik. When the name matches a supported self-hosted app, LF uses its logo on the button.ExampleOIDC_GENERIC_ DISPLAY_ NAME='Authentik' OIDC_OptionalGENERIC_ SCOPES The information LF requests from your provider. The default includes your email address and profile information. The minimum scope is
openid.ExampleOIDC_GENERIC_ SCOPES='openid email profile' OIDC_OptionalREQUIRE_ VERIFIED_ EMAIL Whether your provider must confirm a verified email address before a first sign-in can create an LF user account. If your self-hosted provider doesn't verify email addresses, set this to
falseto allow user account creation without that confirmation.ExampleOIDC_REQUIRE_ VERIFIED_ EMAIL=true How long a pending sign-in, user account linking, or reauthentication request stays valid while you visit the provider and return to LF.
OIDC_OptionalONBOARDING_ TOKEN_ EXPIRE_ SECONDS How long you have to finish signing up after a successful first sign-in through the provider.
OIDC_OptionalREAUTH_ STEPUP_ TOKEN_ EXPIRE_ SECONDS How long a fresh confirmation with your provider remains valid for a sensitive action, such as setting your first password or managing linked providers.
Exchange rates
If Lumina Finance cannot access any frankfurter servers and you have accounts in multiple currencies, you may experience a significant delay caused by the app retrying FX requests in the background. You may also see an increase in total bandwidths used by the app, as data involving FX conversions are not cached when FX requests fail. This is an expected behaviour and currently we do not have an option to disable FX completely.
FRANKFURTER_OptionalURL The URL LF uses to retrieve exchange rates. To use your own Frankfurter instance, set this to its API address including the version path, such as
/v2. It must provide a compatible API, and the value can't be blank.ExampleFRANKFURTER_URL=https://api.frankfurter.dev/v2
Credits
Contributors
- OKok-3