Penombre - Environment Variables

See .example.env for a complete reference.

Core

General application settings that control the runtime identity, environment mode, and logging behavior.

ORIGIN must be set to the public URL where your instance is accessible. It is used to generate absolute URLs in OAuth callbacks and email links. In development this is typically http://localhost:3000.

Variable	Description	Default
`APP_NAME`	Application name (used in UI and emails)	`Penombre`
`APP_VERSION`	Application version (used in metadata)	/
`APP_ENV`	Environment (`dev`/`production`)	`production`
`ORIGIN`	Public origin URL (used for OAuth callbacks)	`http://localhost:3000`
`LOG_LEVEL`	`debug`, `info`, `warn`, `error`, `trace`	`info`
`LOG_FORMAT`	`console` or `json`	`console`

Database

Penombre requires a PostgreSQL database. Provide a standard connection string including credentials, host, port, and database name.

Variable	Description	Default
`DATABASE_URL`	PostgreSQL connection string	Required

Initial Setup

These variables are only used during the first-time database seed to create the initial admin account. They have no effect after the database has been initialized and can be removed from your environment afterwards.

Variable	Description	Default
`ADMIN_EMAIL`	Initial admin account email	Required
`ADMIN_PASSWORD`	Initial admin account password	Required

Authentication

Controls how users authenticate. AUTH_SECRET must be a long, random string — you can generate one with openssl rand -hex 32. Keep it secret and do not rotate it without invalidating all existing sessions.

Variable	Description	Default
`AUTH_SECRET`	Secret key for signing auth tokens	Required
`ENABLE_EMAIL_SIGNIN`	Enable email/password sign-in	`true`
`ENABLE_OAUTH_SIGNIN`	Enable OAuth sign-in	`false`
`MIN_PASSWORD_LENGTH`	Minimum password length	`8`

OAuth Providers (Optional)

Penombre supports any OIDC-compliant provider. Enable OAuth sign-in by setting ENABLE_OAUTH_SIGNIN=true and configuring at least one provider using the naming pattern OAUTH_<PROVIDER>_<SETTING>, where <PROVIDER> is an uppercase identifier of your choice (e.g. GOOGLE, GITHUB, POCKET_ID).

Variable	Description	Default
`OAUTH_<PROVIDER>_ENABLED`	Enable this provider	`true`
`OAUTH_<PROVIDER>_CLIENT_ID`	OAuth client ID	Required
`OAUTH_<PROVIDER>_CLIENT_SECRET`	OAuth client secret	Required
`OAUTH_<PROVIDER>_DISCOVERY_URL`	OIDC discovery URL	Required
`OAUTH_<PROVIDER>_PRETTY_NAME`	Display name in the UI	Provider name
`OAUTH_<PROVIDER>_PKCE`	Use PKCE	`true`
`OAUTH_<PROVIDER>_SCOPES`	Comma-separated scopes	`openid,profile,email`

SMTP (Optional)

Required for email features such as password reset and email verification. Set SMTP_ENABLED=true and provide the connection details for your mail server. If SMTP is disabled, email-dependent features will be unavailable.

Variable	Description	Default
`SMTP_ENABLED`	Enable SMTP	`false`
`SMTP_HOST`	SMTP server hostname	Required if enabled
`SMTP_PORT`	SMTP server port	`587`
`SMTP_USER`	SMTP username	Required if enabled
`SMTP_PASSWORD`	SMTP password	Required if enabled
`SMTP_FROM`	Sender email address	Required if enabled
`SMTP_SECURE`	Use TLS (`true`/`false`)	`false`