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`

Redis (Optional)

Penombre includes an in-memory cache for file listings and metadata. By default, each app instance maintains its own cache in-process. To share the cache across multiple instances or preserve it across restarts, you can connect an external Redis server.

When REDIS_URL is set, all caching is offloaded to Redis. When it is not set, caching falls back to an in-process memory cache (production) or is disabled entirely (development).

Variable	Description	Default
`REDIS_URL`	Redis connection string	/

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`

Storage

Controls where uploaded files are stored. The default local backend stores files on the host filesystem. Set STORAGE_BACKEND=s3 to use any S3-compatible service instead. See Storage for a full setup guide.

Variable	Description	Default
`STORAGE_BACKEND`	`local` or `s3`	`local`
`STORAGE_PATH`	Local filesystem path (local backend only)	`/data/storage`
`S3_BUCKET`	Bucket name (S3 backend only)	Required
`S3_ACCESS_KEY_ID`	Access key ID (S3 backend only)	Required
`S3_SECRET_ACCESS_KEY`	Secret access key (S3 backend only)	Required
`S3_ENDPOINT`	Custom endpoint URL (non-AWS providers)	/
`S3_REGION`	Bucket region	`us-east-1`
`S3_PATH_STYLE`	Use path-style URLs (`true`/`false`)	`false`

Environment Variables

On this page