Configuration

Every chop setting and its CHOP_ environment variable, with defaults, for the command and the library.

Open as Markdown

Every setting is a CHOP_* environment variable, so a container or a service file configures chop without flags. This run limits the output widths, lowers the JPEG quality and turns AVIF off:

CHOP_ALLOWED_WIDTHS=320,640,1280 CHOP_JPEG_QUALITY=75 CHOP_AVIF=false chop --data ./uploads
chop listening on http://0.0.0.0:8080, serving /home/me/uploads

A value that can't be used stops the server with exit code 2 and names the variable or setting, so a typo shows up at startup and not in production:

CHOP_MAX_QUEUE=abc chop --data ./uploads
CHOP_MAX_QUEUE must be a whole number, got "abc".

Reference

Settings come from the CHOP_* environment variables of the command, from the options of createConfig(), or from a few command line flags. A number or boolean that can't be parsed is reported with the name of the variable, and a value that can't be used is an invalid setting.

Source and URLs

Where originals come from and how URLs are read. See Choose where originals come from.

Setting Environment variable Default Description
dataDir CHOP_DATA_DIR /data Directory with the originals, when there is no origin.
schemes CHOP_SCHEMES (comma separated) query Names of the URL schemes, tried in order. An unknown name is an invalid setting.

Limits

What one request can cost. See Prepare chop for production.

Setting Environment variable Default Description
maxConcurrency CHOP_MAX_CONCURRENCY number of CPUs Images processed at the same time.
maxQueue CHOP_MAX_QUEUE 64 Requests that wait for a slot, in arrival order. More are a 503.
maxInputBytes CHOP_MAX_INPUT_BYTES 52428800 Largest original in bytes.
maxInputPixels CHOP_MAX_INPUT_PIXELS 120000000 Largest original in pixels, which stops decompression bombs.
maxOutputDimension CHOP_MAX_OUTPUT_DIMENSION 8192 Largest output width or height.
maxUpscaleDimension CHOP_MAX_UPSCALE_DIMENSION 4096 Largest long side of an enlarged image with upscale=1.
allowedWidths CHOP_ALLOWED_WIDTHS (comma separated) unset When set, the output width of every request must be in the list, after clamping to the size of the original. A request without w is a 400 unless the original's width is listed.

Formats and quality

See Serve AVIF and WebP and Set quality and strip metadata.

Setting Environment variable Default Description
jpegQuality CHOP_JPEG_QUALITY 82 Default JPEG quality.
webpQuality CHOP_WEBP_QUALITY 80 Default lossy WebP quality.
avifQuality CHOP_AVIF_QUALITY 55 Default AVIF quality.
avif CHOP_AVIF true Whether AVIF output is enabled. false removes avif from autoFormats, and doesn't affect an explicit format=avif.
avifEffort CHOP_AVIF_EFFORT 4 AVIF encoder effort from 0 (fast) to 9 (small).
allowedInputFormats CHOP_ALLOWED_INPUT_FORMATS (comma separated) jpeg,png,gif,webp,avif The formats of the originals that are processed (jpeg or jpg, png, gif, webp, avif). Others are a 415. An empty list or an unknown name is an invalid setting. Added in 0.2.0.
autoFormats CHOP_AUTO_FORMATS (comma separated, or none) avif,webp The formats that format=auto can negotiate, in order of preference (avif, webp). An empty list (none in the environment) disables the upgrades. Unknown or repeated names are an invalid setting. Added in 0.2.0.

Caching headers

See Cache images.

Setting Environment variable Default Description
maxAge CHOP_MAX_AGE 31536000 Seconds in Cache-Control: max-age.

Remote origins and URL sources

See Serve images from an HTTPS origin, Let requests name the image URL and Secure remote origins.

Setting Environment variable Default Description
origin CHOP_ORIGIN unset Base URL that plain paths are appended to, instead of the data directory, or s3://bucket[/prefix] for an S3 bucket. Can't be combined with an explicit dataDir. Added in 0.2.0.
originAllowHttp CHOP_ORIGIN_ALLOW_HTTP false Allow http:// for the origin and for URL sources. Added in 0.2.0.
originAllowPrivate CHOP_ORIGIN_ALLOW_PRIVATE false Allow the configured origin at a loopback, private or link-local address. Never applies to URL sources. Added in 0.2.0.
originAuth CHOP_ORIGIN_AUTH unset Authorization header value for the configured origin only. Added in 0.2.0.
originConnectTimeout CHOP_ORIGIN_CONNECT_TIMEOUT 3000 Milliseconds to connect, including TLS, before a 504. Added in 0.2.0.
originTimeout CHOP_ORIGIN_TIMEOUT 10000 Milliseconds for the whole download before a 504. Added in 0.2.0.
originConcurrency CHOP_ORIGIN_CONCURRENCY 4 Downloads at the same time, outside of the processing slots. Added in 0.2.0.
originQueue CHOP_ORIGIN_QUEUE 32 Downloads that wait for a slot. More are a 503. Added in 0.2.0.
allowedHosts CHOP_ALLOWED_HOSTS (comma separated) unset Hosts that URL sources may name: host, *.example.com, host:port or *. Unset means no URL sources. Added in 0.2.0.

S3

See Serve images from S3.

Setting Environment variable Default Description
s3Endpoint CHOP_S3_ENDPOINT unset Base URL of an S3-compatible service for an s3:// origin. Unset means AWS. Added in 0.2.0.
s3Region CHOP_S3_REGION, AWS_REGION unset Region to sign for. Required on AWS, us-east-1 with an endpoint, auto for R2. Added in 0.2.0.
s3PathStyle CHOP_S3_PATH_STYLE true with an endpoint, false on AWS Put the bucket in the path instead of the host. Buckets with dots on AWS are always path-style. Added in 0.2.0.
s3AccessKeyId CHOP_S3_ACCESS_KEY_ID, AWS_ACCESS_KEY_ID unset Access key. Without a key and a secret requests are unsigned. Added in 0.2.0.
s3SecretAccessKey CHOP_S3_SECRET_ACCESS_KEY, AWS_SECRET_ACCESS_KEY unset Secret of the access key. Environment only, never logged. Added in 0.2.0.
s3SessionToken CHOP_S3_SESSION_TOKEN, AWS_SESSION_TOKEN unset Token of temporary credentials, which isn't refreshed. Environment only, never logged. Added in 0.2.0.

Variables of the command only

These are read by the chop command, and not by createConfig() or createHandler().

Variable Flag Default Description
PORT, then CHOP_PORT --port 8080 Port to listen on. 0 picks a free port.
CHOP_HOST --host 0.0.0.0 Address to listen on.
CHOP_ACCESS_LOG none unset 1 prints one JSON line per request to the standard output.

maxConcurrency defaults to the number of CPUs.