Environment Variables

Environment variables

The released Pinchflat-ngx container reads these settings when it starts.

Common settings

Variable	Default	Notes
TZ	UTC	IANA timezone used by the interface, jobs, and logs. TIMEZONE is also accepted and takes precedence.
LOG_LEVEL	debug	Elixir logger level. Use info when debug output is too noisy.
UMASK	022	File-creation mask applied by the startup script.
BASIC_AUTH_USERNAME	Unset	Enables Basic Auth when paired with BASIC_AUTH_PASSWORD and OIDC is disabled.
BASIC_AUTH_PASSWORD	Unset	Password paired with BASIC_AUTH_USERNAME.
EXPOSE_FEED_ENDPOINTS	Disabled	Any non-empty value exposes podcast feed endpoints.
ENABLE_IPV6	Disabled	Any non-empty value enables the IPv6 listener.
ENABLE_PROMETHEUS	Disabled	Any non-empty value enables Prometheus metrics.
PORT	8945 in the container	HTTP port inside the published image. Change the host-side port mapping instead when possible.
BASE_ROUTE_PATH	/	Base path for route generation. A reverse proxy must strip the prefix.
JOURNAL_MODE	wal	SQLite journal mode. Read the network-storage warning below. Ignored by the PostgreSQL image.
DATABASE_POOL_SIZE	10	Database connection-pool size.
SECRET_KEY_BASE	Built-in self-hosted default	Set a long random value for an internet-facing deployment and keep it stable.

Database adapter

The published images bake the adapter in. Use ghcr.io/thebadfella/pinchflat-ngx:latest (SQLite) or ghcr.io/thebadfella/pinchflat-ngx:latest-postgres (PostgreSQL). Do not point the SQLite image at PostgreSQL.

Variable	Default	Notes
DATABASE_ADAPTER	sqlite on latest; postgres on *-postgres	Built into the image.
DATABASE_URL	Unset	Required on the PostgreSQL image. Ecto URL, for example ecto://user:pass@postgres/pinchflat-ngx.

See Installation for a PostgreSQL 18 Compose example.

Optional download helpers

Variable	Default	Notes
POT_PROVIDER_URL	Unset	Internal http(s) URL of a bgutil-compatible PO-token provider, without credentials or query parameters. Blank or unset disables the provider.
DOWNLOAD_STAGING_PATH	Unset	Absolute container path used to finish a download before transferring files to MEDIA_PATH. Blank or unset writes directly to the media library.
POSTGRES_BACKUP_PATH	/config/extras/backups	Directory for in-app PostgreSQL dumps. Only used by the PostgreSQL image. Keep it on a persistent volume.

DOWNLOAD_STAGING_PATH must differ from the media root. Each download gets its own staging directory. The database is updated only after the complete artifact set reaches the media library.

Advanced settings

Variable	Default	Notes
DNS_CLUSTER_QUERY	Unset	DNS query used for distributed Erlang clustering. A normal single-container deployment does not need it.

Container paths

These defaults match the published image and normally should not be changed.

Variable	Default
CONFIG_PATH	/config
MEDIA_PATH	/downloads
DATABASE_PATH	/config/db/pinchflat.db (SQLite image)
LOG_PATH	/config/logs/pinchflat.log
METADATA_PATH	/config/metadata
EXTRAS_PATH	/config/extras
TMPFILE_PATH	System temporary directory under pinchflat/data
TZ_DATA_PATH	/config/extras/elixir_tz_data

Worker concurrency

Worker limits can be changed in Settings. Environment variables override those saved values while they remain set.

Variable	Default	Queue
YT_DLP_WORKER_CONCURRENCY	5	Fallback for all three yt-dlp limits.
YT_DLP_DOWNLOAD_WORKER_CONCURRENCY	Fallback value	Media downloads.
YT_DLP_INDEX_WORKER_CONCURRENCY	Fallback value	Source indexing.
YT_DLP_REMOTE_METADATA_WORKER_CONCURRENCY	Fallback value	Remote metadata work.

Leave these unset to manage concurrency in the interface. Lower download concurrency if YouTube rate-limits the server.

OIDC

See OIDC single sign-on for provider setup and all OIDC settings.

Network-storage warning

SQLite WAL mode is unreliable on many network file systems. Prefer local storage for /config. If a network share is unavoidable, back up the database before considering JOURNAL_MODE=delete. Changing journal modes on an existing database carries a risk of corruption or data loss.