Environment Variables

Every configuration option can be set via an environment variable or the corresponding CLI flag. CLI flags take precedence over environment variables when both are provided.

Server

Variable	CLI Flag	Default	Description
`PP_PORT`	`--port`	`8080`	Server listen port
`PP_APP_ENV`	`--env`	`development`	Environment: `development` or `production`
`PP_MAX_CONCURRENT_REQUESTS`	`--max-concurrent-requests`	`256`	Max number of concurrent requests
`PP_TTL`	`--ttl`	`86400`	General response TTL in seconds
`RUST_LOG`	`--rust-log`	`previewproxy=info,tower_http=info`	Log level filter

Example - run production on port 9000 with higher concurrency and a 1-hour TTL:

PP_PORT=9000
PP_APP_ENV=production
PP_MAX_CONCURRENT_REQUESTS=512
PP_TTL=3600
RUST_LOG=previewproxy=debug,tower_http=debug

Security

See HMAC Signing, Allowed Hosts, and Source URL Encryption for details.

Variable	CLI Flag	Default	Description
`PP_HMAC_KEY`	`--hmac-key`	(none)	HMAC-SHA256 signing key. If unset, all requests are unauthenticated
`PP_ALLOWED_HOSTS`	`--allowed-hosts`	(empty = allow all)	Comma-separated list of allowed upstream hostnames
`PP_SOURCE_URL_ENCRYPTION_KEY`	`--source-url-encryption-key`	(none)	Hex-encoded AES key (32, 48, or 64 hex chars) for source URL encryption/decryption

Example - lock down upstream hosts and enable source URL encryption:

PP_HMAC_KEY=replace-with-long-random-secret
PP_ALLOWED_HOSTS=images.example.com,cdn.example.com
PP_SOURCE_URL_ENCRYPTION_KEY=1eb5b0e971ad7f45324c1bb15c947cb207c43152fa5c6c7f35c4f36e0c18e0f1

Upstream Fetching

Variable	CLI Flag	Default	Description
`PP_FETCH_TIMEOUT_SECS`	`--fetch-timeout-secs`	`10`	Upstream fetch timeout in seconds
`PP_FETCH_RETRY_COUNT`	(env only)	`3`	Number of retries on connection errors (reset, broken pipe). Set to `0` to disable. Timeouts are not retried.
`PP_FETCH_RETRY_DELAY_MS`	(env only)	`0`	Delay in milliseconds between retry attempts
`PP_MAX_SOURCE_BYTES`	`--max-source-bytes`	`20971520` (20 MB)	Maximum source image size in bytes

Example - allow larger files and wait longer for slow origins:

PP_FETCH_TIMEOUT_SECS=20
PP_FETCH_RETRY_COUNT=3
PP_FETCH_RETRY_DELAY_MS=100
PP_MAX_SOURCE_BYTES=52428800

Cache

See Caching Overview and Cache Tuning for details.

Variable	CLI Flag	Default	Description
`PP_CACHE_MEMORY_MAX_MB`	`--cache-memory-max-mb`	`256`	L1 in-memory cache size in MB
`PP_CACHE_MEMORY_TTL_SECS`	`--cache-memory-ttl-secs`	`3600`	L1 cache TTL in seconds
`PP_CACHE_DIR`	`--cache-dir`	`/tmp/previewproxy`	L2 disk cache directory
`PP_CACHE_DISK_TTL_SECS`	`--cache-disk-ttl-secs`	`86400`	L2 disk cache TTL in seconds
`PP_CACHE_DISK_MAX_MB`	`--cache-disk-max-mb`	(empty = unlimited)	L2 disk cache max size in MB
`PP_CACHE_CLEANUP_INTERVAL_SECS`	`--cache-cleanup-interval-secs`	`600`	Cache cleanup interval in seconds

Example - tune cache for a medium traffic deployment:

PP_CACHE_MEMORY_MAX_MB=512
PP_CACHE_MEMORY_TTL_SECS=1800
PP_CACHE_DIR=/var/cache/previewproxy
PP_CACHE_DISK_TTL_SECS=172800
PP_CACHE_DISK_MAX_MB=10240
PP_CACHE_CLEANUP_INTERVAL_SECS=300

Video

See Video Thumbnails for details.

Variable	CLI Flag	Default	Description
`PP_FFMPEG_PATH`	`--ffmpeg-path`	`ffmpeg`	Path to the ffmpeg binary
`PP_FFPROBE_PATH`	`--ffprobe-path`	(same directory as ffmpeg)	Path to the ffprobe binary

Example - pin ffmpeg/ffprobe from a custom installation:

PP_FFMPEG_PATH=/opt/ffmpeg/bin/ffmpeg
PP_FFPROBE_PATH=/opt/ffmpeg/bin/ffprobe

CORS

Variable	CLI Flag	Default	Description
`PP_CORS_ALLOW_ORIGIN`	`--cors-allow-origin`	`*`	Comma-separated allowed CORS origins
`PP_CORS_MAX_AGE_SECS`	`--cors-max-age-secs`	`600`	CORS preflight max-age in seconds

Example - allow only app domains and cache preflight longer:

PP_CORS_ALLOW_ORIGIN=https://app.example.com,https://admin.example.com
PP_CORS_MAX_AGE_SECS=3600

Disallow Lists

See Disallow Lists for details. Use disallow lists to block specific input formats, output formats, or transform operations at the server level. Values are comma-separated.

Variable	CLI Flag	Default	Allowed values
`PP_INPUT_DISALLOW_LIST`	`--input-disallow-list`	(empty)	`jpeg,png,gif,webp,avif,jxl,bmp,tiff,pdf,psd,video`
`PP_OUTPUT_DISALLOW_LIST`	`--output-disallow-list`	(empty)	`jpeg,png,gif,webp,avif,jxl,bmp,tiff,ico`
`PP_TRANSFORM_DISALLOW_LIST`	`--transform-disallow-list`	(empty)	`resize,rotate,flip,grayscale,brightness,contrast,blur,watermark,gif_anim`

Example - block PDF input and prevent format conversion to AVIF:

PP_INPUT_DISALLOW_LIST=pdf
PP_OUTPUT_DISALLOW_LIST=avif

S3 Source

See S3 Source for details.

Variable	CLI Flag	Default	Description
`PP_S3_ENABLED`	`--s3-enabled`	`false`	Enable S3 source
`PP_S3_BUCKET`	`--s3-bucket`	(required if PP_S3_ENABLED)	S3 bucket name
`PP_S3_REGION`	`--s3-region`	`us-east-1`	S3 region
`PP_S3_ACCESS_KEY_ID`	`--s3-access-key-id`	(required if PP_S3_ENABLED)	S3 access key ID
`PP_S3_SECRET_ACCESS_KEY`	`--s3-secret-access-key`	(required if PP_S3_ENABLED)	S3 secret access key
`PP_S3_ENDPOINT`	`--s3-endpoint`	(AWS default)	Custom S3 endpoint URL (for Cloudflare R2, RustFS, etc.)

Example - enable AWS S3 source:

PP_S3_ENABLED=true
PP_S3_BUCKET=my-preview-assets
PP_S3_REGION=us-east-1
PP_S3_ACCESS_KEY_ID=AKIA...
PP_S3_SECRET_ACCESS_KEY=replace-with-secret

Local Filesystem Source

See Local Filesystem Source for details.

Variable	CLI Flag	Default	Description
`PP_LOCAL_ENABLED`	`--local-enabled`	`false`	Enable local filesystem source
`PP_LOCAL_BASE_DIR`	`--local-base-dir`	(required if PP_LOCAL_ENABLED)	Base directory for local file serving

Example - enable local file source:

PP_LOCAL_ENABLED=true
PP_LOCAL_BASE_DIR=/srv/preview-assets

Best Format

See Best Format for details.

Controls automatic format selection when format=best is used or PP_BEST_FORMAT_BY_DEFAULT is enabled.

Variable	CLI Flag	Default	Description
`PP_BEST_FORMAT_COMPLEXITY_THRESHOLD`	`--best-format-complexity-threshold`	`5.5`	Sobel edge density threshold (0-100). Images below this are treated as low-complexity and may be encoded as PNG
`PP_BEST_FORMAT_MAX_RESOLUTION`	`--best-format-max-resolution`	(empty)	When set, images with resolution (in megapixels) above this skip the multi-encode trial and pick one format directly
`PP_BEST_FORMAT_BY_DEFAULT`	`--best-format-by-default`	`false`	When true and no `format` is specified, use best-format selection instead of returning source format
`PP_BEST_FORMAT_ALLOW_SKIPS`	`--best-format-allow-skips`	`false`	When true, skip re-encoding if the selected best format matches the source format and no other transforms are applied
`PP_BEST_FORMAT_PREFERRED_FORMATS`	`--best-format-preferred-formats`	`jpeg,webp,png`	Comma-separated list of formats to trial. Add `avif` or `jxl` for better compression at the cost of slower encoding

Example - enable best-format by default with AVIF/WebP preference:

PP_BEST_FORMAT_BY_DEFAULT=true
PP_BEST_FORMAT_COMPLEXITY_THRESHOLD=6.0
PP_BEST_FORMAT_MAX_RESOLUTION=8
PP_BEST_FORMAT_ALLOW_SKIPS=true
PP_BEST_FORMAT_PREFERRED_FORMATS=avif,webp,jpeg,png

Fallback Image

Configure an optional fallback image returned when upstream fetch/processing fails.

Variable	CLI Flag	Default	Description
`PP_FALLBACK_IMAGE_DATA`	`--fallback-image-data`	(none)	Base64-encoded fallback image payload
`PP_FALLBACK_IMAGE_PATH`	`--fallback-image-path`	(none)	Local file path for fallback image
`PP_FALLBACK_IMAGE_URL`	`--fallback-image-url`	(none)	Remote URL to fetch fallback image
`PP_FALLBACK_IMAGE_HTTP_CODE`	`--fallback-image-http-code`	`200`	HTTP status code for fallback responses; set `0` to preserve original error
`PP_FALLBACK_IMAGE_TTL`	`--fallback-image-ttl`	(uses `PP_TTL`)	TTL in seconds for fallback responses; set `0`/unset to inherit `PP_TTL`

Example - use a CDN fallback image, preserve upstream error status, and apply a shorter fallback TTL:

PP_FALLBACK_IMAGE_URL=https://cdn.example.com/fallback.png
PP_FALLBACK_IMAGE_HTTP_CODE=0
PP_FALLBACK_IMAGE_TTL=300

URL Aliases

See URL Aliases for details.

Variable	CLI Flag	Default	Description
`PP_URL_ALIASES`	`--url-aliases`	(empty)	Comma-separated alias definitions in the form `name=<scheme>://base/path`

Alias targets support three schemes:

https:// / http:// - forward to an HTTP upstream
s3:/ - forward to the configured S3 source (requires S3 to be enabled)
local:/ - forward to the configured local filesystem source (requires local to be enabled)

Examples:

# HTTP alias
PP_URL_ALIASES=cdn=https://cdn.example.com

# S3 alias - resolves myimages:/photo.jpg -> s3:/uploads/photo.jpg
PP_URL_ALIASES=myimages=s3:/uploads

# Local filesystem alias - resolves assets:/logo.png -> local:/static/logo.png
PP_URL_ALIASES=assets=local:/static

# Multiple aliases (comma-separated)
PP_URL_ALIASES=cdn=https://cdn.example.com,thumbs=s3:/thumbnails,assets=local:/static

# Internal service alias - bypasses SSRF private IP blocking (aliases are operator-trusted)
PP_URL_ALIASES=internal=http://192.168.1.10/images

Alias targets bypass PP_ALLOWED_HOSTS and private IP blocking - they are defined in server config and implicitly trusted. See URL Aliases for full usage.

Monitoring

See Prometheus for details.

Variable	CLI Flag	Default	Description
`PP_PROMETHEUS_BIND`	`--prometheus-bind`	(none)	Address to expose Prometheus metrics (e.g. `:9464`). Leave empty to disable
`PP_PROMETHEUS_NAMESPACE`	`--prometheus-namespace`	(empty)	Prefix added to all Prometheus metric names. Leave empty for no prefix

Example - expose metrics on a dedicated port with a namespace prefix:

PP_PROMETHEUS_BIND=:9464
PP_PROMETHEUS_NAMESPACE=previewproxy

All Environment Variables

Check all environment variables in .env.sample

Production checklist

Before going to production, verify the following:

Set PP_HMAC_KEY - without a signing key, any caller can request arbitrary transforms against any URL
Set PP_ALLOWED_HOSTS - without an allowlist, PreviewProxy can be used to proxy any host on the internet (open proxy)
Set PP_APP_ENV=production - enables production-appropriate logging and disables development defaults
Tune cache sizes - review PP_CACHE_MEMORY_MAX_MB, PP_CACHE_DISK_MAX_MB, and PP_CACHE_DISK_TTL_SECS for your expected traffic and available disk space

Server​

Security​

Upstream Fetching​

Cache​

Video​

CORS​

Disallow Lists​

S3 Source​

Local Filesystem Source​

Best Format​

Fallback Image​

URL Aliases​

Monitoring​