From 4f4c6c5f2653303f1e87f9fc713760214b74b8d8 Mon Sep 17 00:00:00 2001 From: Viktor Sokolov Date: Fri, 3 Apr 2026 17:40:29 +0200 Subject: [PATCH 1/7] Version 4.0-rc docs --- docs/configuration/options.mdx | 148 ++++++++++++++------ docs/features/cache.mdx | 117 ++++++++++++++++ docs/features/object_classification.mdx | 69 +++++++++ docs/features/object_detection.mdx | 36 +++-- docs/image_formats_support.mdx | 30 +++- docs/image_sources/amazon_s3.mdx | 11 ++ docs/image_sources/azure_blob_storage.mdx | 11 ++ docs/image_sources/google_cloud_storage.mdx | 11 ++ docs/image_sources/openstack_swift.mdx | 11 ++ docs/monitoring/datadog.mdx | 1 + docs/monitoring/new_relic.mdx | 23 +-- docs/monitoring/open_telemetry.mdx | 39 ++---- docs/monitoring/prometheus.mdx | 8 -- docs/usage/getting_info.mdx | 75 ++++++++++ docs/usage/processing.mdx | 18 +++ sidebars.ts | 10 ++ 16 files changed, 506 insertions(+), 112 deletions(-) create mode 100644 docs/features/cache.mdx create mode 100644 docs/features/object_classification.mdx diff --git a/docs/configuration/options.mdx b/docs/configuration/options.mdx index b67b41d..55933c0 100644 --- a/docs/configuration/options.mdx +++ b/docs/configuration/options.mdx @@ -16,16 +16,6 @@ imgproxy allows URLs to be signed with a key and a salt. This feature is disable You can specify multiple key/salt pairs by dividing the keys and salts with a comma (`,`). imgproxy will check URL signatures with each pair. This is useful when you need to change key/salt pairs in your application while incurring zero downtime. -You can also specify file paths using the command line by referencing a separate file containing hex-coded keys and salts line by line: - -```bash -imgproxy -keypath /path/to/file/with/key -saltpath /path/to/file/with/salt -``` - -:::warning -`-keypath` and `-saltpath` command line arguments are deprecated and will be removed in imgproxy v4. Please use `IMGPROXY_KEY` and `IMGPROXY_SALT` environment variables instead. -::: - If you need a random key/salt pair really fast, as an example, you can quickly generate one using the following snippet: ```bash @@ -38,14 +28,14 @@ echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n') * [`IMGPROXY_BIND`]: the address and port or Unix socket to listen to. Default: `:8080` * [`IMGPROXY_NETWORK`]: the network to use. Known networks are `tcp`, `tcp4`, `tcp6`, `unix`, and `unixpacket`. Default: `tcp` -* [`IMGPROXY_TIMEOUT`]: _(deprecated alias: [`IMGPROXY_WRITE_TIMEOUT`])_ the maximum duration (in seconds) for processing the response. Default: `10` +* [`IMGPROXY_TIMEOUT`]: the maximum duration (in seconds) for processing the response. Default: `10` * [`IMGPROXY_GRACEFUL_STOP_TIMEOUT`]: the maximum duration (in seconds) to wait for ongoing requests to finish before shutting down the server. Default: twice the `IMGPROXY_TIMEOUT` value -* [`IMGPROXY_READ_REQUEST_TIMEOUT`]: _(deprecated alias: [`IMGPROXY_READ_TIMEOUT`])_ the maximum duration (in seconds) for reading the entire incoming HTTP request, including the body. Default: `10` +* [`IMGPROXY_READ_REQUEST_TIMEOUT`]: the maximum duration (in seconds) for reading the entire incoming HTTP request, including the body. Default: `10` * [`IMGPROXY_WRITE_RESPONSE_TIMEOUT`]: the maximum duration (in seconds) for writing the HTTP response body. Default: `10` * [`IMGPROXY_KEEP_ALIVE_TIMEOUT`]: the maximum duration (in seconds) to wait for the next request before closing the connection. When set to `0`, keep-alive is disabled. Default: `10` * [`IMGPROXY_CLIENT_KEEP_ALIVE_TIMEOUT`]: the maximum duration (in seconds) to wait for the next request before closing the HTTP client connection. The HTTP client is used to download source images. When set to `0`, keep-alive is disabled. Default: `90` * [`IMGPROXY_DOWNLOAD_TIMEOUT`]: the maximum duration (in seconds) for downloading the source image. Default: `5` -* [`IMGPROXY_WORKERS`]: _(alias: `IMGPROXY_CONCURRENCY`)_ the maximum number of images an imgproxy instance can process simultaneously without creating a queue. Default: the number of CPU cores multiplied by two +* [`IMGPROXY_WORKERS`]: the maximum number of images an imgproxy instance can process simultaneously without creating a queue. Default: the number of CPU cores multiplied by two :::info When running in AWS Lambda, imgproxy automatically sets `IMGPROXY_WORKERS` to `1` since each Lambda instance processes only one request at a time. ::: @@ -118,10 +108,6 @@ imgproxy can process animated images (GIF, WebP), but since this operation is pr imgproxy doesn't check the number of chained pipelines used in presets ::: -To check if the source image is SVG, imgproxy reads some amount of bytes; by default it reads a maximum of 32KB. However, you can change this value using the following variable: - -* [`IMGPROXY_MAX_SVG_CHECK_BYTES`]: the maximum number of bytes imgproxy will read to recognize SVG files. If imgproxy is unable to recognize your SVG, try increasing this number. Default: `32768` (32KB) - Requests to some image sources may go through too many redirects or enter an infinite loop. You can limit the number of allowed redirects: * [`IMGPROXY_MAX_REDIRECTS`]: the max number of redirects imgproxy can follow while requesting the source image. When set to `0`, no redirects are allowed. Default: `10` @@ -358,6 +344,10 @@ You can use the `best` value for the [format](../usage/processing.mdx#format) op Check out the [Best format](../features/best_format.mdx) guide to learn more. +## Colorspace and HDR + +* [`IMGPROXY_PRESERVE_HDR`]: when `true`, imgproxy will preserve 16-bit images as 16-bit. When `false`, imgproxy will convert 16-bit images to 8-bit. Colorspace (color/grayscale) is always preserved regardless of this setting. See the [Colorspace and HDR preservation](../image_formats_support.mdx#colorspace-and-hdr-preservation) guide for more details. Default: `false` + ## Client Hints support imgproxy can use the `Width` and `DPR` HTTP headers to determine default width and DPR options using Client Hints. This feature is disabled by default and can be enabled by the following option: @@ -417,8 +407,6 @@ imgproxy Pro can apply unsharp masking to your images. imgproxy can detect objects on the image and use them to perform smart cropping, to blur the detections, or to draw the detections. -* [`IMGPROXY_OBJECT_DETECTION_CONFIG`]: ((pro)) the path to the neural network config in DarkNet format. Default: blank -* [`IMGPROXY_OBJECT_DETECTION_WEIGHTS`]: ((pro)) the path to the neural network weights in DarkNet format. Default: blank * [`IMGPROXY_OBJECT_DETECTION_NET`]: ((pro)) a path to the neural network model in ONNX format. Default: blank * [`IMGPROXY_OBJECT_DETECTION_NET_TYPE`]: ((pro)) the type of the neural network model. Default: `yolox` * [`IMGPROXY_OBJECT_DETECTION_CLASSES`]: ((pro)) the path to the text file with the classes names, one per line. Default: blank @@ -434,6 +422,91 @@ imgproxy can detect objects on the image and use them to perform smart cropping, Read the [Object Detection guide](../features/object_detection.mdx) for more info. +## Object classification + +imgproxy can classify detected objects on the image and provide detailed information about what the objects are. + +* [`IMGPROXY_OBJECT_CLASSIFY_NET`]: ((pro)) a path to the classification neural network model in ONNX format. Default: blank +* [`IMGPROXY_OBJECT_CLASSIFY_CLASSES`]: ((pro)) the path to the text file with the class names, one per line. Default: blank +* [`IMGPROXY_OBJECT_CLASSIFY_NET_SIZE`]: ((pro)) the size of the neural network input. The width and the heights of the inputs should be the same, so this config value should be a single number. Default: 224 +* [`IMGPROXY_OBJECT_CLASSIFY_THRESHOLD`]: ((pro)) classifications with confidence below this value will be discarded. Default: 0.5 +* [`IMGPROXY_OBJECT_CLASSIFY_NORMALIZATION`]: ((pro)) the normalization type to apply to the input image. Possible values are: + * `none`: _(default)_ no normalization + * `half`: normalize to [-0.5, 0.5] range + * `full`: normalize to [-1, 1] range + * `imagenet`: normalize using ImageNet mean and standard deviation +* [`IMGPROXY_OBJECT_CLASSIFY_LAYOUT`]: ((pro)) the data layout of the neural network input. Possible values are: + * `nchw`: _(default)_ channels first + * `nhwc`: channels last + +Read the [Object Classification guide](../features/object_classification.mdx) for more info. + +## Cache + +imgproxy can cache processed images in various storage backends to improve performance and reduce processing overhead. + +* [`IMGPROXY_CACHE_USE`]: ((pro)) the cache storage adapter to use. Can be `filesystem`, `s3`, `gcs`, `abs` (Azure Blob Storage), or `swift`. When blank, the cache is disabled. Default: blank +* [`IMGPROXY_CACHE_PATH_PREFIX`]: ((pro)) a path prefix for the cache files. This can be useful to organize cache files in a specific directory structure. Default: blank +* [`IMGPROXY_CACHE_BUCKET`]: ((pro)) the bucket name for cloud storage adapters (S3, GCS, ABS, Swift). When using filesystem adapter, this can be used as an additional path component. Default: blank +* [`IMGPROXY_CACHE_KEY_HEADERS`]: ((pro)) a comma-separated list of HTTP request headers to include in the cache key. This allows caching different versions of the same image based on request headers. Default: blank +* [`IMGPROXY_CACHE_KEY_COOKIES`]: ((pro)) a comma-separated list of HTTP request cookies to include in the cache key. This allows caching different versions of the same image based on cookies. Default: blank +* [`IMGPROXY_CACHE_REPORT_ERRORS`]: ((pro)) when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` + +### Cache storage: Local filesystem {#cache-storage-local-filesystem} + +imgproxy can store cached images on the local filesystem. To use filesystem cache, set `IMGPROXY_CACHE_USE` to `filesystem`: + +* [`IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT`]: ((pro)) the root directory for filesystem cache. Default: blank + +### Cache storage: Amazon S3 {#cache-storage-amazon-s3} + +imgproxy can store cached images in Amazon S3 buckets or S3-compatible storage. To use S3 cache, set `IMGPROXY_CACHE_USE` to `s3`: + +* [`IMGPROXY_CACHE_S3_REGION`]: ((pro)) the S3 region for the cache bucket +* [`IMGPROXY_CACHE_S3_ENDPOINT`]: ((pro)) a custom S3 endpoint for the cache. Useful for S3-compatible services like MinIO, Cloudflare R2, DigitalOcean Spaces, etc. Default: blank +* [`IMGPROXY_CACHE_S3_ENDPOINT_USE_PATH_STYLE`]: ((pro)) controls how the S3 bucket endpoint is constructed. When `true`, the endpoint will be constructed using the path style (`https://your-endpoint.com/%bucket`). When `false`, the endpoint will be constructed using the virtual host style (`https://%bucket.your-endpoint.com`). Default: `true` +* [`IMGPROXY_CACHE_S3_USE_DECRYPTION_CLIENT`]: ((pro)) when `true`, enables client-side decryption for cached objects. Default: `false` +* [`IMGPROXY_CACHE_S3_ASSUME_ROLE_ARN`]: ((pro)) the ARN of an IAM role to assume for cache access +* [`IMGPROXY_CACHE_S3_ASSUME_ROLE_EXTERNAL_ID`]: ((pro)) the external ID required to assume the IAM role for cache access + +:::info +Credentials for S3 cache can be provided using the same methods as for S3 image sources: IAM roles, `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables, or a shared credentials file. +::: + +### Cache storage: Google Cloud Storage {#cache-storage-google-cloud-storage} + +imgproxy can store cached images in Google Cloud Storage buckets. To use GCS cache, set `IMGPROXY_CACHE_USE` to `gcs`: + +* [`IMGPROXY_CACHE_GCS_KEY`]: ((pro)) the Google Cloud JSON key for cache access. When running inside Google Cloud infrastructure, imgproxy will try to use the default service account credentials if this is not set. Default: blank +* [`IMGPROXY_CACHE_GCS_ENDPOINT`]: ((pro)) a custom Google Cloud Storage endpoint for cache. Default: blank + +### Cache storage: Azure Blob Storage {#cache-storage-azure-blob-storage} + +imgproxy can store cached images in Azure Blob Storage containers. To use Azure cache, set `IMGPROXY_CACHE_USE` to `abs`: + +* [`IMGPROXY_CACHE_ABS_NAME`]: ((pro)) the Azure account name for cache storage. Default: blank +* [`IMGPROXY_CACHE_ABS_KEY`]: ((pro)) the Azure account key for cache storage. Default: blank +* [`IMGPROXY_CACHE_ABS_ENDPOINT`]: ((pro)) a custom Azure Blob Storage endpoint for cache. Default: blank + +:::info +Azure cache also supports authentication via Managed Identity or Service Principal using the same `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, and related environment variables as Azure Blob Storage image sources. +::: + +### Cache storage: OpenStack Swift {#cache-storage-openstack-swift} + +imgproxy can store cached images in OpenStack Object Storage (Swift). To use Swift cache, set `IMGPROXY_CACHE_USE` to `swift`: + +* [`IMGPROXY_CACHE_SWIFT_USERNAME`]: ((pro)) the username for Swift API access for cache. Default: blank +* [`IMGPROXY_CACHE_SWIFT_API_KEY`]: ((pro)) the API key for Swift API access for cache. Default: blank +* [`IMGPROXY_CACHE_SWIFT_AUTH_URL`]: ((pro)) the Swift Auth URL for cache. Default: blank +* [`IMGPROXY_CACHE_SWIFT_AUTH_VERSION`]: ((pro)) the Swift auth version for cache. Set to 1, 2 or 3 or leave at 0 for autodetect. Default: 0 +* [`IMGPROXY_CACHE_SWIFT_TENANT`]: ((pro)) the tenant name for cache (optional, v2 auth only). Default: blank +* [`IMGPROXY_CACHE_SWIFT_DOMAIN`]: ((pro)) the Swift domain name for cache (optional, v3 auth only). Default: blank +* [`IMGPROXY_CACHE_SWIFT_TIMEOUT_SECONDS`]: ((pro)) the data channel timeout in seconds for cache operations. Default: 60 +* [`IMGPROXY_CACHE_SWIFT_CONNECT_TIMEOUT_SECONDS`]: ((pro)) the connect channel timeout in seconds for cache operations. Default: 10 + +Read the [Cache guide](../features/cache.mdx) for more info. + ## Fallback image You can set up a fallback image that will be used in case imgproxy is unable to fetch the requested one. Use one of the following variables: @@ -481,28 +554,6 @@ There are two ways to define presets: with_objects=detect_objects:1 ``` -#### Using a command line argument - -:::warning -`-presets` and `-info-presets` command line arguments are deprecated and will be removed in imgproxy v4. Please use `IMGPROXY_PRESETS_PATH` and `IMGPROXY_INFO_PRESETS_PATH` environment variables instead. -::: - -```bash -imgproxy -presets /path/to/file/with/presets -info-presets /path/to/file/with/info-presets -``` - -This file should contain preset definitions, one per line. Lines starting with `#` are treated as comments. Example: - -```imgproxy_presets -default=resizing_type:fill/enlarge:1 - -# Sharpen the image to make it look better -sharp=sharpen:0.7 - -# Blur the image to hide details -blurry=blur:2 -``` - ### Using only presets imgproxy can be switched into "presets-only mode". In this mode, imgproxy accepts only `preset` option arguments as processing options. Example: `http://imgproxy.example.com/unsafe/thumbnail:blurry:watermarked/plain/http://example.com/images/curiosity.jpg@png` @@ -537,6 +588,8 @@ imgproxy can process files from Amazon S3 buckets, but this feature is disabled * [`IMGPROXY_S3_USE_DECRYPTION_CLIENT`]: when `true`, enables client-side decryption. Default: `false` * [`IMGPROXY_S3_ASSUME_ROLE_ARN`]: a custom role to assume * [`IMGPROXY_S3_ASSUME_ROLE_EXTERNAL_ID`]: the external ID required to assume a custom role +* [`IMGPROXY_S3_ALLOWED_BUCKETS`]: a comma-separated list of S3 bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed) +* [`IMGPROXY_S3_DENIED_BUCKETS`]: a comma-separated list of S3 bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank Check out the [Serving files from S3](../image_sources/amazon_s3.mdx) guide to learn more. @@ -545,8 +598,10 @@ Check out the [Serving files from S3](../image_sources/amazon_s3.mdx) guide to l imgproxy can process files from Google Cloud Storage buckets, but this feature is disabled by default. To enable it, set the value of `IMGPROXY_USE_GCS` to `true`: * [`IMGPROXY_USE_GCS`]: when `true`, enables image fetching from Google Cloud Storage buckets. Default: `false` -* [`IMGPROXY_GCS_KEY`]: the Google Cloud JSON key. When set, enables image fetching from Google Cloud Storage buckets. Default: blank +* [`IMGPROXY_GCS_KEY`]: the Google Cloud JSON key. Default: blank * [`IMGPROXY_GCS_ENDPOINT`]: a custom Google Cloud Storage endpoint to being used by imgproxy +* [`IMGPROXY_GCS_ALLOWED_BUCKETS`]: a comma-separated list of GCS bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed) +* [`IMGPROXY_GCS_DENIED_BUCKETS`]: a comma-separated list of GCS bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank Check out the [Serving files from Google Cloud Storage](../image_sources/google_cloud_storage.mdx) guide to learn more. @@ -558,6 +613,8 @@ imgproxy can process files from Azure Blob Storage containers, but this feature * [`IMGPROXY_ABS_NAME`]: the Azure account name. Default: blank * [`IMGPROXY_ABS_KEY`]: the Azure account key. Default: blank * [`IMGPROXY_ABS_ENDPOINT`]: the custom Azure Blob Storage endpoint to be used by imgproxy. Default: blank +* [`IMGPROXY_ABS_ALLOWED_BUCKETS`]: a comma-separated list of Azure Blob Storage container names that imgproxy is allowed to access. When set, imgproxy will only process images from these containers. Default: blank (all containers allowed) +* [`IMGPROXY_ABS_DENIED_BUCKETS`]: a comma-separated list of Azure Blob Storage container names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these containers. Default: blank Check out the [Serving files from Azure Blob Storage](../image_sources/azure_blob_storage.mdx) guide to learn more. @@ -573,6 +630,8 @@ imgproxy can process files from OpenStack Object Storage, but this feature is di * [`IMGPROXY_SWIFT_DOMAIN`]: the Swift domain name (optional, v3 auth only): Default: blank * [`IMGRPOXY_SWIFT_TIMEOUT_SECONDS`]: the data channel timeout in seconds. Default: 60 * [`IMGRPOXY_SWIFT_CONNECT_TIMEOUT_SECONDS`]: the connect channel timeout in seconds. Default: 10 +* [`IMGPROXY_SWIFT_ALLOWED_BUCKETS`]: a comma-separated list of Swift container names that imgproxy is allowed to access. When set, imgproxy will only process images from these containers. Default: blank (all containers allowed) +* [`IMGPROXY_SWIFT_DENIED_BUCKETS`]: a comma-separated list of Swift container names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these containers. Default: blank Check out the [Serving files from OpenStack Object Storage](../image_sources/openstack_swift.mdx) guide to learn more. @@ -609,6 +668,7 @@ imgproxy can send its metrics to New Relic. Specify your New Relic license key t * [`IMGPROXY_NEW_RELIC_KEY`]: the New Relic license key * [`IMGPROXY_NEW_RELIC_APP_NAME`]: a New Relic application name. Default: `imgproxy` * [`IMGPROXY_NEW_RELIC_LABELS`]: the list of New Relic labels, semicolon divided. Example: `label1=value1;label2=value2`. Default: blank +* [`IMGPROXY_NEW_RELIC_PROPAGATE_EXTERNAL`]: when `true`, imgproxy will propagate New Relic tracing headers to external requests such as image downloads. Default: `false` Check out the [New Relic](../monitoring/new_relic.mdx) guide to learn more. @@ -627,6 +687,7 @@ imgproxy can send its metrics to Datadog: * [`IMGPROXY_DATADOG_ENABLE`]: when `true`, enables sending metrics to Datadog. Default: false * [`IMGPROXY_DATADOG_ENABLE_ADDITIONAL_METRICS`]: when `true`, enables sending the additional metrics to Datadog. Default: false +* [`IMGPROXY_DATADOG_PROPAGATE_EXTERNAL`]: when `true`, imgproxy will propagate Datadog tracing headers to external requests such as image downloads. Default: `false` :::warning Since the additional metrics are treated by Datadog as custom, Datadog can additionally bill you for their usage. Please, check out Datadog's [Custom Metrics Billing](https://docs.datadoghq.com/account_management/billing/custom_metrics/) page for additional details. @@ -640,10 +701,12 @@ imgproxy can send request traces to an OpenTelemetry collector: * [`IMGPROXY_OPEN_TELEMETRY_ENABLE`]: when `true`, enables sending request traces to OpenTelemetry collector. Default: false * [`IMGPROXY_OPEN_TELEMETRY_ENABLE_METRICS`]: when `true`, imgproxy will send metrics over OpenTelemetry Metrics API. Default: `false` +* [`IMGPROXY_OPEN_TELEMETRY_ENABLE_LOGS`]: when `true`, imgproxy will send logs to OpenTelemetry collector. Default: `false` * [`IMGPROXY_OPEN_TELEMETRY_SERVER_CERT`]: OpenTelemetry collector TLS certificate, PEM-encoded (you can replace line breaks with `\n`). Default: blank * [`IMGPROXY_OPEN_TELEMETRY_CLIENT_CERT`]: OpenTelemetry client TLS certificate, PEM-encoded (you can replace line breaks with `\n`). Default: blank * [`IMGPROXY_OPEN_TELEMETRY_CLIENT_KEY`]: OpenTelemetry client TLS key, PEM-encoded (you can replace line breaks with `\n`). Default: blank * [`IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR`]: OpenTelemetry trace ID generator. Supported generators are `xray` and `random`. Default: `xray` +* [`IMGPROXY_OPEN_TELEMETRY_PROPAGATE_EXTERNAL`]: when `true`, imgproxy will propagate OpenTelemetry tracing headers to external requests such as image downloads. Default: `false` Check out the [OpenTelemetry](../monitoring/open_telemetry.mdx) guide to learn more. @@ -662,6 +725,7 @@ Check out the [CloudWatch](../monitoring/cloud_watch.mdx) guide to learn more. imgproxy can report occurred errors to Bugsnag, Honeybadger and Sentry: * [`IMGPROXY_REPORT_DOWNLOADING_ERRORS`]: when `true`, imgproxy will report downloading errors. Default: `true` +* [`IMGPROXY_DEVELOPMENT_ERRORS_MODE`]: when `true`, imgproxy will respond with detailed error messages and stack traces in a pretty HTML format. Useful for development and debugging. Default: `false` ### Bugsnag diff --git a/docs/features/cache.mdx b/docs/features/cache.mdx new file mode 100644 index 0000000..2a2fa4e --- /dev/null +++ b/docs/features/cache.mdx @@ -0,0 +1,117 @@ +--- +title: Cache +description: Learn about how to configure and use imgproxy's internal cache +--- + +# Cache ((pro)) + +imgproxy Pro provides an internal cache that stores processed images on disk or in cloud storage. This cache can act as both a primary cache and a secondary cache that serves as a fallback when your CDN cache misses. + +:::tip +While putting a CDN in front of imgproxy is and will always be a best practice, the internal cache provides long-term storage for cases that require an additional caching layer. +::: + +## Why use internal cache? + +The internal cache provides long-term persistent storage for processed images, unlike CDNs that typically delete rarely accessed content. It stores images in a single location rather than across multiple edge stores, eliminating cache misses when requests hit different edges. The cache is designed specifically for imgproxy, working seamlessly with features like modern image format detection and client hints support that generic external caches don't understand. + +The cache is protected by the same security measures as imgproxy itself, including URL signatures and processing restrictions. Importantly, URL signatures are not part of the cache key, so you can rotate keys or use multiple key/salt pairs without invalidating cached images. You maintain full control over where the cache is stored and how it integrates with your infrastructure. + +## Configuration + +You need to define the following config variables to enable the internal cache: + +* [`IMGPROXY_CACHE_USE`]: the cache storage adapter to use. Can be `filesystem`, `s3`, `gcs`, `abs` (Azure Blob Storage), or `swift`. When blank, the cache is disabled. Default: blank +* [`IMGPROXY_CACHE_PATH_PREFIX`]: _(optional)_ a path prefix for the cache files. This can be useful to organize cache files in a specific directory structure. Default: blank +* [`IMGPROXY_CACHE_BUCKET`]: _(optional)_ the bucket name for cloud storage adapters (S3, GCS, ABS, Swift). When using filesystem adapter, this can be used as an additional path component. Default: blank +* [`IMGPROXY_CACHE_KEY_HEADERS`]: _(optional)_ a list of HTTP request headers (comma-separated) to include in the cache key. This allows caching different versions of the same image based on request headers. Default: blank +* [`IMGPROXY_CACHE_KEY_COOKIES`]: _(optional)_ a list of HTTP request cookies (comma-separated) to include in the cache key. This allows caching different versions of the same image based on cookies. Default: blank +* [`IMGPROXY_CACHE_REPORT_ERRORS`]: when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` + +### Storage configuration + +The internal cache supports all the storage backends that imgproxy can read source images from: local filesystem, Amazon S3 and compatible services (Cloudflare R2, DigitalOcean Spaces, MinIO, etc.), Google Cloud Storage, Microsoft Azure Blob Storage, and OpenStack Swift. + +Configure the storage backend using the same configuration options as for image sources, but with the `IMGPROXY_CACHE_` prefix instead: + +* For filesystem cache, use [`IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT`](../configuration/options.mdx#cache-storage-local-filesystem) +* For S3 cache, use `IMGPROXY_CACHE_S3_*` [variables](../configuration/options.mdx#cache-storage-amazon-s3) (e.g., `IMGPROXY_CACHE_S3_REGION`, `IMGPROXY_CACHE_S3_ENDPOINT`) +* For GCS cache, use `IMGPROXY_CACHE_GCS_*` [variables](../configuration/options.mdx#cache-storage-google-cloud-storage) +* For Azure Blob Storage cache, use `IMGPROXY_CACHE_ABS_*` [variables](../configuration/options.mdx#cache-storage-azure-blob-storage) +* For Swift cache, use `IMGPROXY_CACHE_SWIFT_*` [variables](../configuration/options.mdx#cache-storage-openstack-swift) + +See the [configuration options](../configuration/options.mdx#cache) documentation for the full list of available variables. + +## Examples + +### Filesystem cache + +```bash +IMGPROXY_CACHE_USE=filesystem +IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT=/var/cache/imgproxy +IMGPROXY_CACHE_PATH_PREFIX=images +``` + +### S3 cache + +```bash +IMGPROXY_CACHE_USE=s3 +IMGPROXY_CACHE_BUCKET=my-imgproxy-cache +IMGPROXY_CACHE_S3_REGION=us-east-1 +# AWS credentials are provided via IAM role or environment variables +``` + +### Google Cloud Storage cache + +```bash +IMGPROXY_CACHE_USE=gcs +IMGPROXY_CACHE_BUCKET=my-imgproxy-cache +IMGPROXY_CACHE_GCS_KEY=/path/to/credentials.json +``` + +### Azure Blob Storage cache + +```bash +IMGPROXY_CACHE_USE=abs +IMGPROXY_CACHE_BUCKET=imgproxy-cache +IMGPROXY_CACHE_ABS_NAME=mystorageaccount +IMGPROXY_CACHE_ABS_KEY=your_account_key +``` + +## Cache key + +The cache key is generated based on: + +* Source image URL +* Processing options +* Output format +* Optional: Request headers specified in `IMGPROXY_CACHE_KEY_HEADERS` +* Optional: Request cookies specified in `IMGPROXY_CACHE_KEY_COOKIES` + +URL signature is **not** a part of the cache key, which allows key rotation without invalidating the cache. + +## Limitations + +* **No manual cache invalidation**: Currently, imgproxy doesn't provide built-in means to invalidate the cache. However, imgproxy includes the [cachebuster](../usage/processing.mdx#cache-buster) in the cache key, so you can use it to force cache invalidation when needed. Most storage offerings also support object expiration, so you can set a reasonable expiration time for cached images. +* **No cache for info requests**: The internal cache is currently only used for image processing requests. Requests to the `/info` endpoint are not cached. + +## How it works + +When a request comes in: + +1. imgproxy checks the URL signature (if enabled) +2. imgproxy generates the cache key from the request parameters +3. imgproxy checks if a cached image exists in the configured storage +4. If the cached image exists and is valid, imgproxy serves it directly +5. If not, imgproxy processes the image and stores the result in the cache before serving it + +## Monitoring + +Monitor cache performance with metrics: + +* Cache hit rate +* Cache size +* Cache evictions +* Cache latency + +These metrics are available through [monitoring endpoints](../monitoring/prometheus.mdx). diff --git a/docs/features/object_classification.mdx b/docs/features/object_classification.mdx new file mode 100644 index 0000000..40a4566 --- /dev/null +++ b/docs/features/object_classification.mdx @@ -0,0 +1,69 @@ +--- +title: Object classification +description: Learn about how to classify objects in your images with imgproxy +--- + +# Object classification ((pro)) + +imgproxy Pro can classify objects detected in images, providing detailed information about what the objects are. This feature extends [object detection](object_detection.mdx) by not only detecting objects but also identifying their specific classes or categories. + +:::info +Object classification requires [object detection](object_detection.mdx) to be configured and enabled. Classification is performed on the objects detected by the object detection model. +::: + +You can use object classification for content moderation, image organization, and automatic tagging. You can [fetch the classified objects info](../usage/getting_info.mdx#classify-objects) via the info handler. + +## Configuration + +:::tip +If you're using an imgproxy Pro Docker image with a tag suffixed with `-ml`, a basic classification model is included. For advanced classification, you may want to configure your own model. +::: + +You need to define the following config variables to enable object classification: + +* [`IMGPROXY_OBJECT_CLASSIFY_NET`]: a path to the classification neural network model in ONNX format +* [`IMGPROXY_OBJECT_CLASSIFY_CLASSES`]: a path to the [class names file](#class-names-file) +* [`IMGPROXY_OBJECT_CLASSIFY_NET_SIZE`]: the size of the neural network input. The width and the heights of the inputs should be the same, so this config value should be a single number. Default: 224 +* [`IMGPROXY_OBJECT_CLASSIFY_THRESHOLD`]: classifications with confidence below this value will be discarded. Default: 0.5 +* [`IMGPROXY_OBJECT_CLASSIFY_NORMALIZATION`]: the normalization type to apply to the input image. Possible values: + * `none`: no normalization + * `half`: normalize to [-0.5, 0.5] range + * `full`: normalize to [-1, 1] range + * `imagenet`: normalize using ImageNet mean and standard deviation + + Default: `none` +* [`IMGPROXY_OBJECT_CLASSIFY_LAYOUT`]: the data layout of the neural network input. Possible values: + * `nchw`: channels first (default) + * `nhwc`: channels last + + Default: `nchw` + +### Class names file + +The class names file is used to map the class indexes from the neural network output to human-readable class names. The path to the class names file should be defined in the `IMGPROXY_OBJECT_CLASSIFY_CLASSES` config variable. + +The class names file should contain one class name per line. The class names should be in the same order as the classes in the neural network output. Example: + +```text +person +bicycle +car +``` + +## Getting classification info + +Object classification is available via the info handler using the `co` (classify objects) endpoint. Fetch classification results by specifying the number of top classes to return: + +```imgproxy_url +.../info/co:5/... +``` + +Where `5` is the number of top classes to return. + +The response is an array of objects, each containing: + +* `class_id`: The numeric ID of the class +* `name`: The class name from the class names file +* `confidence`: The confidence score for this classification + +See [getting info documentation](../usage/getting_info.mdx#classify-objects) for more details. diff --git a/docs/features/object_detection.mdx b/docs/features/object_detection.mdx index 5d10841..22818c4 100644 --- a/docs/features/object_detection.mdx +++ b/docs/features/object_detection.mdx @@ -5,9 +5,9 @@ description: Learn about how to detect objects in your images and use them with # Object detection ((pro)) -imgproxy can detect objects in the image and use them for smart cropping, blurring the detections, or drawing the detections. You can also [fetch the detected objects info](../usage/getting_info.mdx#detect-objects). +imgproxy can detect objects in the image and use them for smart cropping, blurring the detections, drawing the detections, or cropping to detected objects. You can also [fetch the detected objects info](../usage/getting_info.mdx#detect-objects). -For object purposes, imgproxy uses the YOLO (You Only Look Once) model family. imgproxy supports models in DarkNet or ONNX format. We provide Docker images with a model trained for face detection, but you can use any YOLO model found on the internet or train your own model. +For object purposes, imgproxy uses the YOLO (You Only Look Once) model family. imgproxy supports models in ONNX format. We provide Docker images with a model trained for face detection, but you can use any YOLO model found on the internet or train your own model. ## Configuration @@ -15,24 +15,6 @@ For object purposes, imgproxy uses the YOLO (You Only Look Once) model family. i You don't need to configure object detection if you're using an imgproxy Pro Docker image with a tag suffixed with `-ml` and you want to use the face detection model. The model is already included in the image and the configuration is already set up. ::: -:::info -DarkNet model format has priority over ONNX model format. If you define both, imgproxy will use the DarkNet model. -::: - -### DarkNet model format - -:::warning -DarkNet models support is deprecated and will be removed in imgproxy v4. Please use ONNX models instead. -::: - -You need to define the following config variables to enable object detection with a [DarkNet](https://github.com/AlexeyAB/darknet) model: - -* [`IMGPROXY_OBJECT_DETECTION_CONFIG`]: a path to the neural network config in DarkNet format -* [`IMGPROXY_OBJECT_DETECTION_WEIGHTS`]: a path to the neural network weights in DarkNet format -* [`IMGPROXY_OBJECT_DETECTION_CLASSES`]: a path to the [class names file](#class-names-file) - -### ONNX model format - You need to define the following config variables to enable object detection with an ONNX model: * [`IMGPROXY_OBJECT_DETECTION_NET`]: a path to the neural network model in ONNX format @@ -336,6 +318,20 @@ You can make imgproxy [draw bounding boxes](../usage/processing.mdx#draw-detecti .../draw_detections:1:face/... ``` +### Crop to detected objects + +You can make imgproxy [crop the image](../usage/processing.mdx#crop-objects) to fit all detected objects of the desired classes: + +```imgproxy_url +.../crop_objects:1.2:face:person/... +``` + +This will automatically crop the image to include all detected faces and persons with 20% padding around them. You can omit class names to crop to all detected objects: + +```imgproxy_url +.../co:1.0/... +``` + ### Fetch the detected objects' info You can [fetch the detected objects info](../usage/getting_info.mdx#detect-objects) using the `/info` endpoint: diff --git a/docs/image_formats_support.mdx b/docs/image_formats_support.mdx index 7d92ae9..9baf00d 100644 --- a/docs/image_formats_support.mdx +++ b/docs/image_formats_support.mdx @@ -21,6 +21,7 @@ At the moment, imgproxy supports only the most popular image formats: | TIFF | `tiff` | :white_check_mark: | :white_check_mark: | | PDF ((pro)) | `pdf` | :white_check_mark: | [See notes](#pdf-support) | | PSD ((pro)) | `psd` | [See notes](#psd-support) | :x: | +| RAW ((pro)) | | [See notes](#raw-support) | :x: | | MP4 (h264) ((pro)) | `mp4` | [See notes](#video-thumbnails) | :white_check_mark: | | Other video formats ((pro)) | | [See notes](#video-thumbnails) | :x: | @@ -36,10 +37,6 @@ imgproxy supports SVG sources without limitations, but SVG results are not suppo When the source image is SVG and an SVG result is requested, imgproxy returns the source image without modifications. -imgproxy reads some amount of bytes to check if the source image is SVG. By default it reads a maximum of 32KB, but you can change this: - -* `IMGPROXY_MAX_SVG_CHECK_BYTES`: the maximum number of bytes imgproxy will read to recognize SVG. If imgproxy can't recognize your SVG, try to increase this number. Default: `32768` (32KB) - ## Animated images support Since the processing of animated images is a pretty heavy process, only one frame is processed by default. You can increase the maximum of animation frames to process with the following variable: @@ -70,6 +67,12 @@ We tested imgproxy with all variants of PSD/PSB files that we could find or prod We couldn't find any PSD/PSB files with their image data compressed with ZIP, so imgproxy renders them as solid white images. If you had such files, we would very much appreciate it if you could share them with us. ::: +## RAW support ((pro)) {#raw-support} + +RAW image formats from digital cameras are supported as source images only (read-only). RAW files are decoded and converted to standard image formats during processing. + +imgproxy uses [libraw](https://www.libraw.org/) to process RAW files. For a complete list of supported camera models and RAW formats, see the [libraw supported cameras list](https://www.libraw.org/supported-cameras). + ## Converting animated images to MP4 ((pro)) {#converting-animated-images-to-mp4} Animated image results can be converted to MP4 by specifying the `mp4` extension. @@ -84,3 +87,22 @@ Since this still requires more data to be downloaded, video thumbnail generation * `IMGPROXY_ENABLE_VIDEO_THUMBNAILS`: when true, enables video thumbnail generation. Default: `false` * `IMGPROXY_VIDEO_THUMBNAIL_SECOND`: the timestamp of the frame (in seconds) that will be used for the thumbnail. Default: `1`. + +## Colorspace and HDR preservation + +imgproxy always preserves the source image's colorspace: + +* Color images remain color images +* Grayscale images remain grayscale images +* Colorspace types are maintained + +The bit depth handling depends on the [IMGPROXY_PRESERVE_HDR](configuration/options.mdx#IMGPROXY_PRESERVE_HDR) configuration setting: + +**When `IMGPROXY_PRESERVE_HDR` is enabled:** + +* 16-bit images remain 16-bit in the output (eg. GRAYSCALE16 remains GRAYSCALE16, scRGB remains scRGB) + +**When `IMGPROXY_PRESERVE_HDR` is disabled (default):** + +* 16-bit images are converted to 8-bit (eg. GRAYSCALE16 becomes GRAYSCALE8, RGB and scRGB become sRGB) +* 8-bit images remain 8-bit diff --git a/docs/image_sources/amazon_s3.mdx b/docs/image_sources/amazon_s3.mdx index 6024dbd..8d60917 100644 --- a/docs/image_sources/amazon_s3.mdx +++ b/docs/image_sources/amazon_s3.mdx @@ -78,6 +78,17 @@ This allows imgproxy to access buckets in any region. However, the initial reque * If your most frequently used buckets are in the same region, set the region to that one. * If your buckets are spread across multiple regions, set the region to the closest one to your imgproxy instance. +## Restricting bucket access + +For security purposes, you can restrict which S3 buckets imgproxy is allowed to access: + +* `IMGPROXY_S3_ALLOWED_BUCKETS`: a comma-separated list of bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed) +* `IMGPROXY_S3_DENIED_BUCKETS`: a comma-separated list of bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank + +:::tip +Use `IMGPROXY_S3_ALLOWED_BUCKETS` to create an allowlist of trusted buckets, or use `IMGPROXY_S3_DENIED_BUCKETS` to block specific buckets. If both are set, allowed buckets take precedence. +::: + ## MinIO [MinIO](https://github.com/minio/minio) is an object storage server released under Apache License v2.0. It is compatible with Amazon S3, so it can be used with imgproxy. diff --git a/docs/image_sources/azure_blob_storage.mdx b/docs/image_sources/azure_blob_storage.mdx index 80ee513..e555368 100644 --- a/docs/image_sources/azure_blob_storage.mdx +++ b/docs/image_sources/azure_blob_storage.mdx @@ -50,3 +50,14 @@ For certificate authentication: ### Using Storage Account Key Alternatively, you can set `IMGPROXY_ABS_KEY` to your Azure Blob Storage account key. See the [Manage storage account access keys](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage) guide for more info. + +## Restricting container access + +For security purposes, you can restrict which Azure Blob Storage containers imgproxy is allowed to access: + +* `IMGPROXY_ABS_ALLOWED_BUCKETS`: a comma-separated list of container names that imgproxy is allowed to access. When set, imgproxy will only process images from these containers. Default: blank (all containers allowed) +* `IMGPROXY_ABS_DENIED_BUCKETS`: a comma-separated list of container names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these containers. Default: blank + +:::tip +Use `IMGPROXY_ABS_ALLOWED_BUCKETS` to create an allowlist of trusted containers, or use `IMGPROXY_ABS_DENIED_BUCKETS` to block specific containers. If both are set, allowed containers take precedence. +::: diff --git a/docs/image_sources/google_cloud_storage.mdx b/docs/image_sources/google_cloud_storage.mdx index 76cbb62..2d21fe6 100644 --- a/docs/image_sources/google_cloud_storage.mdx +++ b/docs/image_sources/google_cloud_storage.mdx @@ -36,3 +36,14 @@ Otherwise, set `IMGPROXY_GCS_KEY` environment variable to the content of Google :::warning For security reasons, imgproxy accepts only service account keys for Google Cloud Storage integration. ::: + +## Restricting bucket access + +For security purposes, you can restrict which GCS buckets imgproxy is allowed to access: + +* `IMGPROXY_GCS_ALLOWED_BUCKETS`: a comma-separated list of bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed) +* `IMGPROXY_GCS_DENIED_BUCKETS`: a comma-separated list of bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank + +:::tip +Use `IMGPROXY_GCS_ALLOWED_BUCKETS` to create an allowlist of trusted buckets, or use `IMGPROXY_GCS_DENIED_BUCKETS` to block specific buckets. If both are set, allowed buckets take precedence. +::: diff --git a/docs/image_sources/openstack_swift.mdx b/docs/image_sources/openstack_swift.mdx index 7900b03..8e8c98a 100644 --- a/docs/image_sources/openstack_swift.mdx +++ b/docs/image_sources/openstack_swift.mdx @@ -20,3 +20,14 @@ imgproxy can process images from OpenStack Object Storage, also known as Swift. :::tip If filenames in your OpenStack Object Storage may contain `?`, you may want to set [IMGPROXY_SOURCE_URL_QUERY_SEPARATOR](../configuration/options.mdx#IMGPROXY_SOURCE_URL_QUERY_SEPARATOR) to another string that is not used in filenames or set it to blank to disable query string extraction. ::: + +## Restricting container access + +For security purposes, you can restrict which Swift containers imgproxy is allowed to access: + +* `IMGPROXY_SWIFT_ALLOWED_BUCKETS`: a comma-separated list of container names that imgproxy is allowed to access. When set, imgproxy will only process images from these containers. Default: blank (all containers allowed) +* `IMGPROXY_SWIFT_DENIED_BUCKETS`: a comma-separated list of container names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these containers. Default: blank + +:::tip +Use `IMGPROXY_SWIFT_ALLOWED_BUCKETS` to create an allowlist of trusted containers, or use `IMGPROXY_SWIFT_DENIED_BUCKETS` to block specific containers. If both are set, allowed containers take precedence. +::: diff --git a/docs/monitoring/datadog.mdx b/docs/monitoring/datadog.mdx index 319672e..48beedd 100644 --- a/docs/monitoring/datadog.mdx +++ b/docs/monitoring/datadog.mdx @@ -23,6 +23,7 @@ imgproxy can send its metrics to Datadog. To use this feature, do the following: * `DD_TRACE_STARTUP_LOGS`: causes various startup info to be written when the tracer starts. Default: `true` * `DD_TRACE_DEBUG`: enables detailed logs. Default: `false` 4. _(optional)_ Set the `IMGPROXY_DATADOG_ENABLE_ADDITIONAL_METRICS` environment variable to `true` to collect the [additional metrics](#additional-metrics). +5. _(optional)_ Set the `IMGPROXY_DATADOG_PROPAGATE_EXTERNAL` environment variable to `true` to propagate Datadog tracing headers to external requests such as image downloads. Default: `false`. imgproxy will send the following info to Datadog: diff --git a/docs/monitoring/new_relic.mdx b/docs/monitoring/new_relic.mdx index 44a9f98..a8f3eb7 100644 --- a/docs/monitoring/new_relic.mdx +++ b/docs/monitoring/new_relic.mdx @@ -10,6 +10,7 @@ imgproxy can send its metrics to New Relic. To use this feature, do the followin 2. Set the `IMGPROXY_NEW_RELIC_KEY` environment variable to the license key. 3. _(optional)_ Set the `IMGPROXY_NEW_RELIC_APP_NAME` environment variable to be the desired application name. 4. _(optional)_ Set the `IMGPROXY_NEW_RELIC_LABELS` environment variable to be the desired list of labels. Example: `label1=value1;label2=value2`. +5. _(optional)_ Set the `IMGPROXY_NEW_RELIC_PROPAGATE_EXTERNAL` environment variable to `true` to propagate New Relic tracing headers to external requests such as image downloads. Default: `false`. imgproxy will send the following info to New Relic: @@ -20,15 +21,15 @@ imgproxy will send the following info to New Relic: * Image processing time * Errors that occurred while downloading and processing an image -Additionally, imgproxy sends the following metrics over [Metrics API](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/): +Additionally, imgproxy sends the following metrics over [Metrics API](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/) as timescales: -* `imgproxy.workers`: the configured number of imgproxy workers -* `imgproxy.requests_in_progress`: the number of requests currently in progress -* `imgproxy.images_in_progress`: the number of images currently in progress -* `imgproxy.workers_utilization`: the percentage of imgproxy's workers utilization. Calculated as `imgproxy.requests_in_progress / imgproxy.workers * 100` -* `imgproxy.buffer.size`: a summary of the download buffers sizes (in bytes) -* `imgproxy.buffer.default_size`: calibrated default buffer size (in bytes) -* `imgproxy.buffer.max_size`: calibrated maximum buffer size (in bytes) -* `imgproxy.vips.memory`: libvips memory usage (in bytes) -* `imgproxy.vips.max_memory`: libvips maximum memory usage (in bytes) -* `imgproxy.vips.allocs`: the number of active vips allocations +* `Custom/imgproxy/workers`: the configured number of imgproxy workers +* `Custom/imgproxy/requests_in_progress`: the number of requests currently in progress +* `Custom/imgproxy/images_in_progress`: the number of images currently in progress +* `Custom/imgproxy/workers_utilization`: the percentage of imgproxy's workers utilization. Calculated as `Custom/imgproxy/requests_in_progress / Custom/imgproxy/workers * 100` +* `Custom/imgproxy/buffer/size`: a summary of the download buffers sizes (in bytes) +* `Custom/imgproxy/buffer/default_size`: calibrated default buffer size (in bytes) +* `Custom/imgproxy/buffer/max_size`: calibrated maximum buffer size (in bytes) +* `Custom/imgproxy/vips/memory`: libvips memory usage (in bytes) +* `Custom/imgproxy/vips/max_memory`: libvips maximum memory usage (in bytes) +* `Custom/imgproxy/vips/allocs`: the number of active vips allocations diff --git a/docs/monitoring/open_telemetry.mdx b/docs/monitoring/open_telemetry.mdx index e2c5542..b91281d 100644 --- a/docs/monitoring/open_telemetry.mdx +++ b/docs/monitoring/open_telemetry.mdx @@ -9,15 +9,16 @@ imgproxy can send request traces to an OpenTelemetry collector. To use this feat 1. Install & configure the [OpenTelemetry collector](https://opentelemetry.io/docs/collector/). 2. Set the `IMGPROXY_OPEN_TELEMETRY_ENABLE` environment variable to `true` to enable sending request traces to the collector. Default: `false`. 3. _(optional)_ Set the `IMGPROXY_OPEN_TELEMETRY_ENABLE_METRICS` environment variable to `true` to enable sending metrics to the collector. Default: `false`. -4. _(optional)_ Specify the collector protocol with `OTEL_EXPORTER_OTLP_PROTOCOL` environment variable. +4. _(optional)_ Set the `IMGPROXY_OPEN_TELEMETRY_ENABLE_LOGS` environment variable to `true` to enable sending logs to the collector. Default: `false`. +5. _(optional)_ Specify the collector protocol with `OTEL_EXPORTER_OTLP_PROTOCOL` environment variable. :::tip - You can specify different protocols for traces and metrics by using the `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` and `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` environment variables. + You can specify different protocols for traces, metrics, and logs by using the `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`, `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL`, and `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` environment variables. ::: Supported protocols are: * `grpc` _(default)_ * `http/protobuf` (aliases: `http`, `https`) -5. _(optional)_ Specify the collector endpoint with `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable. +6. _(optional)_ Specify the collector endpoint with `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable. :::tip Use `https://` scheme for secure connections (you may need to configure [TLS certificates](#tls-configuration)) and `http://` for insecure connections. ::: @@ -27,18 +28,18 @@ imgproxy can send request traces to an OpenTelemetry collector. To use this feat ::: :::tip - You can specify different endpoints for traces and metrics by using the `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` and `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` environment variables. If the `http/protobuf` protocol is used, these signal-specific endpoints should include the signal-specific paths like `/v1/traces` or `/v1/metrics`. + You can specify different endpoints for traces, metrics, and logs by using the `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, and `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` environment variables. If the `http/protobuf` protocol is used, these signal-specific endpoints should include the signal-specific paths like `/v1/traces`, `/v1/metrics`, or `/v1/logs`. ::: Defaults are: * For the `grpc` protocol: `https://localhost:4317` * For the `http/protobuf` protocol: `https://localhost:4318` -6. _(optional)_ Set the `OTEL_SERVICE_NAME` environment variable to be the desired service name. Default: `imgproxy`. -7. _(optional)_ [Set up TLS certificates](#tls-configuration). -8. _(optional)_ Set the `IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR` environment variable to be the desired trace ID generator. Supported values are: +7. _(optional)_ Set the `OTEL_SERVICE_NAME` environment variable to be the desired service name. Default: `imgproxy`. +8. _(optional)_ [Set up TLS certificates](#tls-configuration). +9. _(optional)_ Set the `IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR` environment variable to be the desired trace ID generator. Supported values are: * `xray`: _(default)_ Amazon X-Ray compatible trace ID generator * `random`: random trace ID generator -9. _(optional)_ Use [OpenTelemetry configuration environment variables](#configuration) to further customize the behavior. +10. _(optional)_ Use [OpenTelemetry configuration environment variables](#configuration) to further customize the behavior. imgproxy will send the following info to the collector: @@ -67,11 +68,12 @@ If `IMGPROXY_OPEN_TELEMETRY_ENABLE_METRICS` is set to `true`, imgproxy will also imgproxy supports the standard [general](https://opentelemetry.io/docs/languages/sdk-configuration/general/) and [OTLP exporter-specific](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/) environment variables with the following specifics: * `http/json` protocol` is not supported. -* `OTEL_TRACES_EXPORTER` and `OTEL_METRICS_EXPORTER` environment variables are ignored as imgproxy always uses the OTLP exporter. -* Logs-related environment variables are ignored as imgproxy does not support sending logs to OpenTelemetry. +* `OTEL_TRACES_EXPORTER`, `OTEL_METRICS_EXPORTER`, and `OTEL_LOGS_EXPORTER` environment variables are ignored as imgproxy always uses the OTLP exporter. Also, imgproxy supports the following environment variables: +* `IMGPROXY_OPEN_TELEMETRY_ENABLE_LOGS`: when `true`, imgproxy will send logs to OpenTelemetry collector. Default: `false` +* `IMGPROXY_OPEN_TELEMETRY_PROPAGATE_EXTERNAL`: when `true`, imgproxy will propagate OpenTelemetry tracing headers to external requests such as image downloads. Default: `false` * `IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR`: the desired trace ID generator. Supported values are: * `xray`: _(default)_ Amazon X-Ray compatible trace ID generator * `random`: random trace ID generator @@ -91,20 +93,3 @@ If your collector uses mTLS for mutual authentication, you'll also need to speci :::warning If `IMGPROXY_OPEN_TELEMETRY_SERVER_CERT` is set and the `grpc` protocol is used, imgproxy will try to establish a secure connection to the collector even if the collector's endpoint scheme is `http://`. ::: - -## Deprecated Environment Variables - -The following environment variables are deprecated and will be removed in the future: - -* `IMGPROXY_OPEN_TELEMETRY_ENDPOINT`: use `OTEL_EXPORTER_OTLP_ENDPOINT` instead and explicitly enable OpenTelemetry support with `IMGPROXY_OPEN_TELEMETRY_ENABLE` environment variable. - :::warning - Unlike `IMGPROXY_OPEN_TELEMETRY_ENDPOINT`, `OTEL_EXPORTER_OTLP_ENDPOINT` should contain a URL scheme (`http://` or `https://`). - ::: -* `IMGPROXY_OPEN_TELEMETRY_PROTOCOL`: use `OTEL_EXPORTER_OTLP_PROTOCOL` instead. -* `IMGPROXY_OPEN_TELEMETRY_GRPC_INSECURE`: use `OTEL_EXPORTER_OTLP_ENDPOINT` with `http://` scheme instead. -* `IMGPROXY_OPEN_TELEMETRY_SERVICE_NAME`: use `OTEL_SERVICE_NAME` instead. -* `IMGPROXY_OPEN_TELEMETRY_PROPAGATORS`: use `OTEL_PROPAGATORS` instead. -* `IMGPROXY_OPEN_TELEMETRY_CONNECTION_TIMEOUT`: use `OTEL_EXPORTER_OTLP_TIMEOUT` instead. - :::warning - Unlike `IMGPROXY_OPEN_TELEMETRY_CONNECTION_TIMEOUT`, `OTEL_EXPORTER_OTLP_TIMEOUT` should be specified in milliseconds instead of seconds. - ::: diff --git a/docs/monitoring/prometheus.mdx b/docs/monitoring/prometheus.mdx index 688dfa5..103d38c 100644 --- a/docs/monitoring/prometheus.mdx +++ b/docs/monitoring/prometheus.mdx @@ -28,11 +28,3 @@ imgproxy will collect the following metrics: * `vips_max_memory_bytes`: libvips maximum memory usage * `vips_allocs`: the number of active vips allocations * Some useful Go metrics like memstats and goroutines count - -### Deprecated metrics - -The following metrics are deprecated and can be removed in future versions. Use `request_span_duration_seconds` instead. - -* `download_duration_seconds`: a histogram of the source image downloading latency (in seconds) -* `processing_duration_seconds`: a histogram of the image processing latency (in seconds) - diff --git a/docs/usage/getting_info.mdx b/docs/usage/getting_info.mdx index 3c2c177..df54ee8 100644 --- a/docs/usage/getting_info.mdx +++ b/docs/usage/getting_info.mdx @@ -303,6 +303,38 @@ Default: `false`. } ``` +### Classify objects {#classify-objects} + +:::slow[Slow] +This option requires the image to be fully downloaded and processed. +::: + +```imgproxy_url_option +classify_objects:%top_k +co:%top_k +``` + +When `top_k` is greater than zero, imgproxy will classify the image and return the top K classes with the highest confidence scores. Read the [object classification](../features/object_classification.mdx) manual to learn how to configure object classification. + +Default: `0`. + +**Response example:** + +```json +[ + { + "class_id": 68, + "name": "Bus", + "confidence": 0.8745117 + }, + { + "class_id": 351, + "name": "Person", + "confidence": 0.7734375 + } +] +``` + ### Colorspace :::slow[Slow] @@ -577,6 +609,49 @@ Default: `0:0` } ``` +### ThumbHash {#thumb-hash} + +:::slow[Slow] +This option requires the image to be fully downloaded and processed. +::: + +```imgproxy_url_option +thumb_hash:1 +th:1 +``` + +When set, imgproxy will calculate and return the image's [ThumbHash](https://evanw.github.io/thumbhash/). ThumbHash is a compact representation of an image that can be used to generate a placeholder while the actual image is loading. + +**Response example:** + +```json +{ + "thumb_hash": "0BE7810C80365AF29266578A660CB7A6707A80867738A87804" +} +``` + +### Perceptual hash {#perceptual-hash} + +:::slow[Slow] +This option requires the image to be fully downloaded and processed. +::: + +```imgproxy_url_option +perceptual_hash:1 +phash:1 +ph:1 +``` + +When set, imgproxy will calculate and return the perceptual hash of the image. Perceptual hashes can be used to find similar or duplicate images. + +**Response example:** + +```json +{ + "perceptual_hash": "9797306d694b4e94" +} +``` + ### Calc hashsums :::slow[Slow] diff --git a/docs/usage/processing.mdx b/docs/usage/processing.mdx index 4ef5667..6d11333 100644 --- a/docs/usage/processing.mdx +++ b/docs/usage/processing.mdx @@ -582,6 +582,24 @@ dd:%draw:%class_name1:%class_name2:...:%class_nameN When `draw` is set to `1`, `t` or `true`, imgproxy [detects objects](../features/object_detection.mdx) of the provided classes and draws their bounding boxes, classes, and confidences. If class names are omitted, imgproxy draws the bounding boxes of all the detected objects. +### Crop objects ((pro)) {#crop-objects} + +```imgproxy_url_option +crop_objects:%scale_factor:%class_name1:%class_name2:...:%class_nameN +co:%scale_factor:%class_name1:%class_name2:...:%class_nameN +``` + +imgproxy [detects objects](../features/object_detection.mdx) of the provided classes and crops the image to fit all detected objects. + +* `scale_factor`: a float value that defines how much the crop area should be scaled relative to the detected objects. For example, `1.0` crops exactly to the detected objects, while `1.2` adds 20% padding around them. +* `class_name1`, `class_name2`, ..., `class_nameN`: _(optional)_ names of the object classes to detect. If class names are omitted, imgproxy crops to all detected objects. + +This option is useful when you want to automatically extract the area containing specific objects from an image, such as extracting all faces from a group photo or isolating products from a catalog image. + +:::info +When no objects are detected, imgproxy will not crop the image and will process it as usual. +::: + ### Colorize ((pro)) {#colorize} ```imgproxy_url_option diff --git a/sidebars.ts b/sidebars.ts index 472d736..a3e5ff2 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -60,6 +60,11 @@ const sidebars: SidebarsConfig = { id: "features/object_detection", className: "menu__list-item--badge badge--pro", }, + { + type: "doc", + id: "features/object_classification", + className: "menu__list-item--badge badge--pro", + }, { type: "doc", id: "features/autoquality", @@ -75,6 +80,11 @@ const sidebars: SidebarsConfig = { id: "features/chained_pipelines", className: "menu__list-item--badge badge--pro", }, + { + type: "doc", + id: "features/cache", + className: "menu__list-item--badge badge--pro", + }, ], }, { From 7116b34db3c9cfa9d1b62c42b9c0bce0157588be Mon Sep 17 00:00:00 2001 From: Viktor Sokolov Date: Mon, 6 Apr 2026 17:42:17 +0200 Subject: [PATCH 2/7] Cache docs --- docs/cache/external.mdx | 209 +++++++++++++++++++ docs/cache/internal.mdx | 79 +++++++ docs/cache/internal/amazon_s3.mdx | 72 +++++++ docs/cache/internal/azure_blob_storage.mdx | 60 ++++++ docs/cache/internal/google_cloud_storage.mdx | 33 +++ docs/cache/internal/local_filesystem.mdx | 29 +++ docs/cache/internal/openstack_swift.mdx | 35 ++++ docs/configuration/options.mdx | 33 +-- docs/features/cache.mdx | 115 +--------- docs/features/object_classification.mdx | 10 +- docs/image_formats_support.mdx | 10 +- docs/image_sources/amazon_s3.mdx | 4 +- docs/image_sources/azure_blob_storage.mdx | 4 +- docs/image_sources/google_cloud_storage.mdx | 4 +- docs/image_sources/openstack_swift.mdx | 4 +- docs/usage/processing.mdx | 2 +- sidebars.ts | 36 +++- src/css/badge.css | 2 +- 18 files changed, 587 insertions(+), 154 deletions(-) create mode 100644 docs/cache/external.mdx create mode 100644 docs/cache/internal.mdx create mode 100644 docs/cache/internal/amazon_s3.mdx create mode 100644 docs/cache/internal/azure_blob_storage.mdx create mode 100644 docs/cache/internal/google_cloud_storage.mdx create mode 100644 docs/cache/internal/local_filesystem.mdx create mode 100644 docs/cache/internal/openstack_swift.mdx diff --git a/docs/cache/external.mdx b/docs/cache/external.mdx new file mode 100644 index 0000000..ec4905b --- /dev/null +++ b/docs/cache/external.mdx @@ -0,0 +1,209 @@ +--- +description: External cache options for imgproxy, including CDNs, nginx, and Varnish +--- + +# External cache + +External cache refers to caching layers in front of imgproxy, such as CDNs, reverse proxies, or caching appliances. These solutions provide edge caching, geo-distribution, and high-performance image delivery. + +## CDN options + +Most major CDNs (Cloudflare, Fastly, AWS CloudFront, Akamai, etc.) can cache imgproxy responses: + +### Recommended CDN settings + +* **Origin shield** - Add a secondary cache layer between your CDN and imgproxy origin +* **Image optimization** - Disable CDN image optimization to avoid double-processing +* **Compression** - Enable gzip/Brotli compression for bandwidth savings +* **HTTP/2 Server Push** - Push critical images to reduce latency + +## nginx caching + +nginx can act as a reverse proxy cache in front of imgproxy: + +```nginx +proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=imgproxy_cache:10m max_size=50g inactive=30d; + +upstream imgproxy { + server localhost:8080; +} + +server { + listen 80; + server_name images.example.com; + + # Include request and feature signals that can change imgproxy output + proxy_cache_key "$scheme$request_method$host$request_uri:accept=$http_accept:dpr=$http_dpr:width=$http_width:chdpr=$http_sec_ch_dpr:chwidth=$http_sec_ch_width"; + + location / { + proxy_pass http://imgproxy; + + # Cache configuration + proxy_cache imgproxy_cache; + proxy_cache_valid 200 24h; + proxy_cache_valid 304 24h; + proxy_cache_valid 404 1m; + proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; + proxy_cache_background_update on; + proxy_cache_lock on; + proxy_cache_bypass $http_pragma $http_authorization; + proxy_no_cache $http_pragma $http_authorization; + + # Add cache status header for debugging + add_header X-Cache-Status $upstream_cache_status; + } +} +``` + +### Possible cache key setup + +The exact key depends on which imgproxy features can change output for the same URL. + +1. Basic key when output depends only on URL/path options: + +```nginx +proxy_cache_key "$scheme$proxy_host$request_uri"; +``` + +2. Include format negotiation signal when WebP/AVIF/JXL preference can vary by client: + +```nginx +proxy_cache_key "$scheme$proxy_host$request_uri$http_accept"; +``` + +3. Include Client Hints dimensions when width/DPR affects output: + +```nginx +proxy_cache_key "$scheme$request_method$host$request_uri:accept=$http_accept:dpr=$http_dpr:width=$http_width:chdpr=$http_sec_ch_dpr:chwidth=$http_sec_ch_width"; +``` + +Use the smallest key that still prevents collisions for your traffic profile. + +### Key recommendations + +* Include `Accept` in the cache key if format negotiation is used. +* Include DPR/width-related hints in the cache key if Client Hints are used to vary output. +* Set long `inactive` timeout (30d) to keep popular images in cache. +* Configure `proxy_cache_use_stale` for graceful degradation during origin issues. +* Monitor `/proc/sys/fs/file-max` and increase if needed for large caches. +* Use separate cache zones for different image types if needed. + +## Varnish caching + +Varnish is a powerful reverse proxy cache optimized for HTTP performance: + +```vcl +vcl 4.1; + +backend imgproxy { + .host = "localhost"; + .port = "8080"; + .connect_timeout = 600ms; + .first_byte_timeout = 600s; + .between_bytes_timeout = 60s; +} + +sub vcl_recv { + set req.backend_hint = imgproxy; + + # Cache only GET and HEAD requests + if (req.method != "GET" && req.method != "HEAD") { + return (pass); + } + + # Include important headers in cache key + if (req.http.Accept) { + set req.http.X-Accept = req.http.Accept; + } + + # Keep DPR if Client Hints are not enabled + if (req.http.DPR) { + set req.http.X-DPR = req.http.DPR; + } + + if (req.http.Width) { + set req.http.X-Width = req.http.Width; + } + + if (req.http.Sec-CH-DPR) { + set req.http.X-CH-DPR = req.http.Sec-CH-DPR; + } + + if (req.http.Sec-CH-Width) { + set req.http.X-CH-Width = req.http.Sec-CH-Width; + } +} + +sub vcl_hash { + # Base hash + hash_data(req.url); + hash_data(req.http.Host); + + # Include Accept header for format negotiation + if (req.http.X-Accept) { + hash_data(req.http.X-Accept); + } + + # Include DPR if present + if (req.http.X-DPR) { + hash_data(req.http.X-DPR); + } + + if (req.http.X-Width) { + hash_data(req.http.X-Width); + } + + if (req.http.X-CH-DPR) { + hash_data(req.http.X-CH-DPR); + } + + if (req.http.X-CH-Width) { + hash_data(req.http.X-CH-Width); + } +} + +sub vcl_backend_response { + # Cache successful responses for 24 hours + if (beresp.status == 200) { + set beresp.ttl = 24h; + set beresp.keep = 24h; + } + + # Cache 404s for a short period + if (beresp.status == 404) { + set beresp.ttl = 1m; + } + + # Enable cache using stale object if backend is down + set beresp.grace = 24h; +} + +sub vcl_deliver { + # Add cache hit/miss header + if (obj.hits > 0) { + set resp.http.X-Cache = "HIT"; + set resp.http.X-Cache-Hits = obj.hits; + } else { + set resp.http.X-Cache = "MISS"; + } +} +``` + +### Key recommendations + +* Use `sub vcl_hash` to customize cache key behavior. +* Include `Accept` for format negotiation. +* Include DPR/width-related headers when they can affect output (`DPR`, `Width`, `Sec-CH-DPR`, `Sec-CH-Width`). +* Set grace period (`beresp.grace`) for graceful error handling. +* Monitor Varnish statistics with `varnishstat`. +* Use tags for efficient cache purging: add `set beresp.http.Surrogate-Key = "images:product:123"` in `vcl_backend_response`. +* Configure workspace limits if caching many large images. + +## Cache headers from imgproxy + +imgproxy sends the following headers useful for external caching: + +* `Cache-Control: public, max-age=31536000` - Long-term caching (1 year default, configurable with `IMGPROXY_TTL`) +* `ETag` - If `IMGPROXY_USE_ETAG=true` (by default), enables conditional requests +* `Last-Modified` - If `IMGPROXY_USE_LAST_MODIFIED=true` (by default), enables conditional requests +* `Content-Type` - Important for cache key if not in `Accept` header diff --git a/docs/cache/internal.mdx b/docs/cache/internal.mdx new file mode 100644 index 0000000..64face6 --- /dev/null +++ b/docs/cache/internal.mdx @@ -0,0 +1,79 @@ +--- +title: Internal cache +description: Learn about how to configure and use imgproxy's internal cache +--- + +# Internal cache ((pro)) + +imgproxy Pro provides an internal cache that stores processed images on disk or in cloud storage. This cache can act as both a primary and a secondary cache, serving as a fallback when your CDN cache misses. + +:::tip +While putting a CDN in front of imgproxy is and will always be a best practice, the internal cache provides long-term storage for cases that require an additional caching layer. +::: + +## Why use internal cache? + +The internal cache provides long-term persistent storage for processed images, unlike CDNs which typically delete rarely accessed content. It stores images in a single location rather than across multiple edge stores, eliminating cache misses when requests hit different edges. The cache is designed specifically for imgproxy, working seamlessly with features like modern image format detection and client hints support that generic external caches don't understand. + +The cache is protected by the same security measures as imgproxy itself, including URL signatures and processing restrictions. Importantly, URL signatures are not part of the cache key, so you can rotate keys or use multiple key/salt pairs without invalidating cached images. You maintain full control over where the cache is stored and how it integrates with your infrastructure. + +## Configuration + +You need to define the following config variables to enable the internal cache: + +* [`IMGPROXY_CACHE_USE`]: the cache storage adapter to use. Can be `fs`, `s3`, `gcs`, `abs` (Azure Blob Storage), or `swift` (OpenStack Swift). When blank, the cache is disabled. Default: blank +* [`IMGPROXY_CACHE_PATH_PREFIX`]: _(optional)_ a path prefix for the cache files. This can be useful to organize cache files in a specific directory structure. Default: blank +* [`IMGPROXY_CACHE_BUCKET`]: _(optional)_ the bucket name for cloud storage adapters (S3, GCS, ABS, Swift). When using the filesystem adapter, this can be used as an additional path component. Default: blank +* [`IMGPROXY_CACHE_KEY_HEADERS`]: _(optional)_ a list of HTTP request headers (comma-separated) to include in the cache key. This allows caching different versions of the same image based on request headers. Default: blank +* [`IMGPROXY_CACHE_KEY_COOKIES`]: _(optional)_ a list of HTTP request cookies (comma-separated) to include in the cache key. This allows caching different versions of the same image based on cookies. Default: blank +* [`IMGPROXY_CACHE_REPORT_ERRORS`]: When `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` + +### Storage configuration + +The internal cache supports all the storage backends that imgproxy can read source images from: local filesystem, Amazon S3 and compatible services (Cloudflare R2, DigitalOcean Spaces, MinIO, etc.), Google Cloud Storage, Microsoft Azure Blob Storage, and OpenStack Swift. + +Configure the storage backend using `IMGPROXY_CACHE_*` variables: + +* For filesystem cache, see [Cache storage: Local filesystem](./internal/local_filesystem.mdx). +* For S3 cache, see [Cache storage: Amazon S3](./internal/amazon_s3.mdx). +* For GCS cache, see [Cache storage: Google Cloud Storage](./internal/google_cloud_storage.mdx). +* For Azure Blob Storage cache, see [Cache storage: Azure Blob Storage](./internal/azure_blob_storage.mdx). +* For Swift cache, see [Cache storage: OpenStack Object Storage ("Swift")](./internal/openstack_swift.mdx). + +## Cache key + +The cache key is generated based on: + +* Source image URL +* Processing options +* Output format +* Optional: Request headers specified in `IMGPROXY_CACHE_KEY_HEADERS` +* Optional: Request cookies specified in `IMGPROXY_CACHE_KEY_COOKIES` + +URL signature is **not** part of the cache key, allowing key rotation without invalidating the cache. + +## Limitations + +* **No manual cache invalidation**: Currently, imgproxy doesn't provide a built-in means to invalidate the cache. However, imgproxy includes the [cachebuster](../usage/processing.mdx#cache-buster) in the cache key, so you can use it to force cache invalidation when needed. Most storage offerings also support object expiration, so you can set a reasonable expiration time for cached images. +* **No cache for info requests**: The internal cache is currently used only for image processing requests. Requests to the `/info` endpoint are not cached. + +## How it works + +When a request comes in: + +1. imgproxy checks the URL signature (if enabled). +2. imgproxy generates the cache key from the request parameters. +3. imgproxy checks if a cached image exists in the configured storage. +4. If the cached image exists and is valid, imgproxy serves it directly. +5. If not, imgproxy processes the image and stores the result in the cache before serving it. + +## Monitoring + +Monitor cache performance with metrics: + +* Cache hit rate +* Cache size +* Cache evictions +* Cache latency + +These metrics are available through [monitoring endpoints](../monitoring/prometheus.mdx). diff --git a/docs/cache/internal/amazon_s3.mdx b/docs/cache/internal/amazon_s3.mdx new file mode 100644 index 0000000..7d1a865 --- /dev/null +++ b/docs/cache/internal/amazon_s3.mdx @@ -0,0 +1,72 @@ +--- +description: Learn about how to configure Amazon S3 cache in imgproxy +--- + +# Cache storage: Amazon S3 + +imgproxy can store cached images in Amazon S3 buckets or S3-compatible storage. To use S3 cache, do the following: + +1. Set the `IMGPROXY_CACHE_USE` environment variable to `s3`. +2. [Set up the necessary credentials](#set-up-credentials) to grant access to your cache bucket. +3. _(optional)_ Specify the AWS region with `IMGPROXY_CACHE_S3_REGION`. Default: `us-west-1` +4. _(optional)_ Specify the cache bucket name with `IMGPROXY_CACHE_BUCKET`. +5. _(optional)_ Specify the S3 endpoint with `IMGPROXY_CACHE_S3_ENDPOINT`. You can also set `IMGPROXY_CACHE_S3_ENDPOINT_USE_PATH_STYLE=false` to use the virtual host style for the endpoint. +6. _(optional)_ Specify the AWS IAM Role to Assume with `IMGPROXY_CACHE_S3_ASSUME_ROLE_ARN`. +7. _(optional)_ Specify the External ID to pass to the AWS IAM Role when assuming it using `IMGPROXY_CACHE_S3_ASSUME_ROLE_EXTERNAL_ID`. This will have no effect if the assume role ARN is not specified. + +### Configuration + +* `IMGPROXY_CACHE_USE`: set to `s3` to enable S3 cache. +* `IMGPROXY_CACHE_BUCKET`: the S3 bucket name for cache storage. Default: blank +* `IMGPROXY_CACHE_S3_REGION`: the S3 region for the cache bucket. Default: blank +* `IMGPROXY_CACHE_S3_ENDPOINT`: a custom S3 endpoint for the cache. Useful for S3-compatible services like MinIO, Cloudflare R2, DigitalOcean Spaces, etc. Default: blank +* `IMGPROXY_CACHE_S3_ENDPOINT_USE_PATH_STYLE`: controls how the S3 bucket endpoint is constructed. When `true`, the endpoint will be constructed using the path style (`https://your-endpoint.com/%bucket`). When `false`, the endpoint will be constructed using the virtual host style (`https://%bucket.your-endpoint.com`). Default: `true` +* `IMGPROXY_CACHE_S3_ASSUME_ROLE_ARN`: the ARN of an IAM role to assume for cache access. Default: blank +* `IMGPROXY_CACHE_S3_ASSUME_ROLE_EXTERNAL_ID`: the external ID required to assume the IAM role for cache access. Default: blank +* `IMGPROXY_CACHE_PATH_PREFIX`: a path prefix for the cache files. Default: blank +* `IMGPROXY_CACHE_KEY_HEADERS`: a comma-separated list of HTTP request headers to include in the cache key. Default: blank +* `IMGPROXY_CACHE_KEY_COOKIES`: a comma-separated list of HTTP request cookies to include in the cache key. Default: blank +* `IMGPROXY_CACHE_REPORT_ERRORS`: when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` + +### Set up credentials + +There are three ways to specify your AWS credentials. The credentials need to have read/write rights for the cache bucket: + +#### IAM Roles + +If you're running imgproxy on an Amazon Web Services platform, you can use IAM roles to get the security credentials to make calls to AWS S3. + +* **Elastic Container Service (ECS):** Assign an [IAM role to a task](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html). +* **Elastic Kubernetes Service (EKS):** Assign a [service account to a pod](https://docs.aws.amazon.com/eks/latest/userguide/pod-configuration.html). +* **Elastic Beanstalk:** Assign an [IAM role to an instance](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/iam-instanceprofile.html). + +#### Environment variables + +You can specify an AWS Access Key ID and a Secret Access Key by setting the standard `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables. + +```bash +AWS_ACCESS_KEY_ID=my_access_key AWS_SECRET_ACCESS_KEY=my_secret_key imgproxy + +# same for Docker +docker run -e AWS_ACCESS_KEY_ID=my_access_key -e AWS_SECRET_ACCESS_KEY=my_secret_key -it ghcr.io/imgproxy/imgproxy +``` + +#### Shared credentials file + +Alternatively, you can create the `.aws/credentials` file in your home directory with the following content: + +```ini +[default] +aws_access_key_id = %access_key_id +aws_secret_access_key = %secret_access_key +``` + +#### Cross-Account Access + +Cache S3 access credentials may be acquired by assuming a role using STS. To do so, specify the IAM Role ARN with the `IMGPROXY_CACHE_S3_ASSUME_ROLE_ARN` environment variable. Additionally, if you require an external ID to be passed when assuming a role, specify the `IMGPROXY_CACHE_S3_ASSUME_ROLE_EXTERNAL_ID` environment variable. This approach still requires you to provide initial AWS credentials by using one of the ways described above. The provided credentials role should allow assuming the role with the provided ARN. + +### Choosing the AWS region + +The AWS region specified with the `IMGPROXY_CACHE_S3_REGION` environment variable determines the S3 endpoint used by imgproxy for the initial request to the bucket. If AWS reports that the bucket is in a different region, imgproxy will remember this, retry the request, and use the new region for all subsequent requests for this bucket. + +This allows imgproxy to access buckets in any region. However, the initial request to the bucket in a region other than the one specified in the environment variable may introduce some latency. diff --git a/docs/cache/internal/azure_blob_storage.mdx b/docs/cache/internal/azure_blob_storage.mdx new file mode 100644 index 0000000..890f514 --- /dev/null +++ b/docs/cache/internal/azure_blob_storage.mdx @@ -0,0 +1,60 @@ +--- +description: Learn about how to configure Azure Blob Storage cache in imgproxy +--- + +# Cache storage: Azure Blob Storage + +imgproxy can store cached images in Azure Blob Storage containers. To use Azure cache, do the following: + +1. Set the `IMGPROXY_CACHE_USE` environment variable to `abs`. +2. Set `IMGPROXY_CACHE_ABS_NAME` to your Azure account name. +3. [Set up the necessary credentials](#set-up-credentials). +4. _(optional)_ Specify the cache container name with `IMGPROXY_CACHE_BUCKET`. +5. _(optional)_ Specify the Azure Blob Storage endpoint with `IMGPROXY_CACHE_ABS_ENDPOINT`. + +### Configuration + +* `IMGPROXY_CACHE_USE`: set to `abs` to enable Azure Blob Storage cache. +* `IMGPROXY_CACHE_ABS_NAME`: the Azure account name for cache storage. Default: blank +* `IMGPROXY_CACHE_BUCKET`: the Azure container name for cache storage. Default: blank +* `IMGPROXY_CACHE_ABS_KEY`: the Azure account key for cache storage. Default: blank +* `IMGPROXY_CACHE_ABS_ENDPOINT`: a custom Azure Blob Storage endpoint for cache. Default: blank +* `IMGPROXY_CACHE_PATH_PREFIX`: a path prefix for the cache files. Default: blank +* `IMGPROXY_CACHE_KEY_HEADERS`: a comma-separated list of HTTP request headers to include in the cache key. Default: blank +* `IMGPROXY_CACHE_KEY_COOKIES`: a comma-separated list of HTTP request cookies to include in the cache key. Default: blank +* `IMGPROXY_CACHE_REPORT_ERRORS`: when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` + +### Set up credentials + +#### Leverage Azure Managed Identity or Service Principal + +Microsoft recommends using a Managed Identity or Service Principal when accessing resources in an Azure Storage Account. +Both of these authentication pathways are supported out of the box. + +##### Managed Identity + +No additional configuration is required so long as the resource running imgproxy has a Managed Identity assigned. + +##### Service Principal + +Please refer to the [following documentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal) on creating a service principal before proceeding. + +Once that step is complete, the following environment variables must be configured based on the chosen option. + +For secret authentication: + +* `AZURE_CLIENT_ID`: the client ID for your application registration +* `AZURE_TENANT_ID`: the tenant ID for your application registration +* `AZURE_CLIENT_SECRET`: the client secret for your application registration + +For certificate authentication: + +* `AZURE_CLIENT_ID`: the client ID for your application registration +* `AZURE_TENANT_ID`: the tenant ID for your application registration +* `AZURE_CLIENT_CERTIFICATE_PATH`: the path to a PFX or PEM-encoded certificate including private key +* `AZURE_CLIENT_CERTIFICATE_PASSWORD`: _(optional)_ the password protecting the certificate file (PFX (PKCS12)) +* `AZURE_CLIENT_CERTIFICATE_CHAIN`: _(optional)_ send certificate chain in x5c header to support subject name / issuer-based authentication + +#### Using Storage Account Key + +Alternatively, you can set `IMGPROXY_CACHE_ABS_KEY` to your Azure Blob Storage account key. See the [Manage storage account access keys](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage) guide for more info. diff --git a/docs/cache/internal/google_cloud_storage.mdx b/docs/cache/internal/google_cloud_storage.mdx new file mode 100644 index 0000000..441f8a1 --- /dev/null +++ b/docs/cache/internal/google_cloud_storage.mdx @@ -0,0 +1,33 @@ +--- +description: Learn about how to configure Google Cloud Storage cache in imgproxy +--- + +# Cache storage: Google Cloud Storage + +imgproxy can store cached images in Google Cloud Storage buckets. To use the GCS cache, do the following: + +1. Set the `IMGPROXY_CACHE_USE` environment variable to `gcs`. +2. [Set up credentials](#setup-credentials) to grant access to your cache bucket. +3. _(optional)_ Specify the cache bucket name with `IMGPROXY_CACHE_BUCKET`. +4. _(optional)_ Specify the Google Cloud Storage endpoint with `IMGPROXY_CACHE_GCS_ENDPOINT`. + +### Configuration + +* `IMGPROXY_CACHE_USE`: set to `gcs` to enable Google Cloud Storage cache. +* `IMGPROXY_CACHE_BUCKET`: the GCS bucket name for cache storage. Default: blank +* `IMGPROXY_CACHE_GCS_KEY`: the Google Cloud JSON key for cache access. When running on Google Cloud infrastructure, imgproxy will use the default service account credentials if none are set. Default: blank +* `IMGPROXY_CACHE_GCS_ENDPOINT`: a custom Google Cloud Storage endpoint for cache. Default: blank +* `IMGPROXY_CACHE_PATH_PREFIX`: a path prefix for the cache files. Default: blank +* `IMGPROXY_CACHE_KEY_HEADERS`: a comma-separated list of HTTP request headers to include in the cache key. Default: blank +* `IMGPROXY_CACHE_KEY_COOKIES`: a comma-separated list of HTTP request cookies to include in the cache key. Default: blank +* `IMGPROXY_CACHE_REPORT_ERRORS`: when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` + +### Setup credentials + +If you run imgproxy inside Google Cloud infrastructure (Compute Engine, Kubernetes Engine, App Engine, Cloud Functions, etc), and you have granted access to your cache bucket to the service account, you probably don’t need to do anything here. imgproxy will try to use the credentials provided by Google. + +Otherwise, set the `IMGPROXY_CACHE_GCS_KEY` environment variable to the content of the Google Cloud JSON key. Get more info about JSON keys: [https://cloud.google.com/iam/docs/creating-managing-service-account-keys](https://cloud.google.com/iam/docs/creating-managing-service-account-keys). + +:::warning +For security reasons, imgproxy accepts only service account keys for Google Cloud Storage cache integration. +::: diff --git a/docs/cache/internal/local_filesystem.mdx b/docs/cache/internal/local_filesystem.mdx new file mode 100644 index 0000000..1ac3516 --- /dev/null +++ b/docs/cache/internal/local_filesystem.mdx @@ -0,0 +1,29 @@ +--- +description: Learn about how to configure the local filesystem cache in imgproxy +--- + +# Cache storage: Local filesystem + +imgproxy can store cached images on the local filesystem. To use filesystem cache, do the following: + +1. Set the `IMGPROXY_CACHE_USE` environment variable to the filesystem. +2. Set `IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT` to your cache directory path. +3. _(optional)_ Specify a path prefix for cache files with `IMGPROXY_CACHE_PATH_PREFIX`. + +### Configuration + +* `IMGPROXY_CACHE_USE`: set to `fs` to enable local filesystem cache. +* `IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT`: the root directory for filesystem cache. Default: blank +* `IMGPROXY_CACHE_PATH_PREFIX`: a path prefix for the cache files. This can be useful to organize cache files in a specific directory structure. Default: blank +* `IMGPROXY_CACHE_BUCKET`: When using the filesystem adapter, this can be used as an additional path component. Default: blank +* `IMGPROXY_CACHE_KEY_HEADERS`: a comma-separated list of HTTP request headers to include in the cache key. This allows caching different versions of the same image based on request headers. Default: blank +* `IMGPROXY_CACHE_KEY_COOKIES`: a comma-separated list of HTTP request cookies to include in the cache key. This allows caching different versions of the same image based on cookies. Default: blank +* `IMGPROXY_CACHE_REPORT_ERRORS`: when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` + +### Example + +Assume you want to cache processed images in `/var/cache/imgproxy`. Run imgproxy with `IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT` set to your cache directory: + +```bash +IMGPROXY_CACHE_USE=filesystem IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT=/var/cache/imgproxy imgproxy +``` diff --git a/docs/cache/internal/openstack_swift.mdx b/docs/cache/internal/openstack_swift.mdx new file mode 100644 index 0000000..cf6a0f7 --- /dev/null +++ b/docs/cache/internal/openstack_swift.mdx @@ -0,0 +1,35 @@ +--- +description: Learn about how to configure OpenStack Object Storage cache in imgproxy +--- + +# Cache storage: OpenStack Object Storage ("Swift") + +imgproxy can store cached images in OpenStack Object Storage, also known as Swift. To use Swift cache, do the following: + +1. Set the `IMGPROXY_CACHE_USE` environment variable to `swift`. +2. Configure Swift authentication with the following environment variables: + * `IMGPROXY_CACHE_SWIFT_USERNAME`: the username for Swift API access for cache. Default: blank + * `IMGPROXY_CACHE_SWIFT_API_KEY`: the API key for Swift API access for cache. Default: blank + * `IMGPROXY_CACHE_SWIFT_AUTH_URL`: the Swift Auth URL for cache. Default: blank + * `IMGPROXY_CACHE_SWIFT_AUTH_VERSION`: the Swift auth version for cache, set to 1, 2 or 3 or leave at 0 for autodetect. Default: 0 + * `IMGPROXY_CACHE_SWIFT_TENANT`: the tenant name for cache (optional, v2 auth only). Default: blank + * `IMGPROXY_CACHE_SWIFT_DOMAIN`: the Swift domain name for cache (optional, v3 auth only). Default: blank + +3. _(optional)_ Specify the cache container name with `IMGPROXY_CACHE_BUCKET`. + +### Configuration + +* `IMGPROXY_CACHE_USE`: set to `swift` to enable Swift cache. +* `IMGPROXY_CACHE_BUCKET`: the Swift container name for cache storage. Default: blank +* `IMGPROXY_CACHE_SWIFT_USERNAME`: the username for Swift API access for cache. Default: blank +* `IMGPROXY_CACHE_SWIFT_API_KEY`: the API key for Swift API access for cache. Default: blank +* `IMGPROXY_CACHE_SWIFT_AUTH_URL`: the Swift Auth URL for cache. Default: blank +* `IMGPROXY_CACHE_SWIFT_AUTH_VERSION`: the Swift auth version for cache. Set to 1, 2 or 3 or leave at 0 for autodetect. Default: 0 +* `IMGPROXY_CACHE_SWIFT_TENANT`: the tenant name for cache (optional, v2 auth only). Default: blank +* `IMGPROXY_CACHE_SWIFT_DOMAIN`: the Swift domain name for cache (optional, v3 auth only). Default: blank +* `IMGPROXY_CACHE_SWIFT_TIMEOUT_SECONDS`: the data channel timeout in seconds for cache operations. Default: 60 +* `IMGPROXY_CACHE_SWIFT_CONNECT_TIMEOUT_SECONDS`: the connect channel timeout in seconds for cache operations. Default: 10 +* `IMGPROXY_CACHE_PATH_PREFIX`: a path prefix for the cache files. Default: blank +* `IMGPROXY_CACHE_KEY_HEADERS`: a comma-separated list of HTTP request headers to include in the cache key. Default: blank +* `IMGPROXY_CACHE_KEY_COOKIES`: a comma-separated list of HTTP request cookies to include in the cache key. Default: blank +* `IMGPROXY_CACHE_REPORT_ERRORS`: when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` diff --git a/docs/configuration/options.mdx b/docs/configuration/options.mdx index 55933c0..cef34f4 100644 --- a/docs/configuration/options.mdx +++ b/docs/configuration/options.mdx @@ -48,8 +48,9 @@ echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n') * [`IMGPROXY_PATH_PREFIX`]: the URL path prefix. Example: when set to `/abc/def`, the imgproxy URL will be `/abc/def/%signature/%processing_options/%source_url`. Default: blank * [`IMGPROXY_USER_AGENT`]: the User-Agent header that will be sent with the source image request. You can use the `%current_version` variable to insert the current imgproxy version. Default: `imgproxy/%current_version` * [`IMGPROXY_USE_ETAG`]: when set to `true`, enables using the [ETag](https://en.wikipedia.org/wiki/HTTP_ETag) HTTP header for HTTP cache control. Default: `false` -* [`IMGPROXY_ETAG_BUSTER`]: change this to change ETags for all the images. Default: blank +* [`IMGPROXY_ETAG_BUSTER`]: a global ETag buster value. Change it to invalidate old ETags and prevent `304 Not Modified` responses for stale client/CDN validators. Default: blank * [`IMGPROXY_USE_LAST_MODIFIED`]: when set to `true`, enables using the [Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) HTTP header for HTTP cache control. Default: `false` +* [`IMGPROXY_LAST_MODIFIED_BUSTER`]: a global `Last-Modified` buster timestamp. If incoming `If-Modified-Since` is older than this value, imgproxy ignores it and forces revalidation; if origin `Last-Modified` is older, imgproxy replaces it with this timestamp. Use it to invalidate stale client/CDN `Last-Modified` validators after global processing changes. Default: `0` * [`IMGPROXY_CUSTOM_REQUEST_HEADERS`]: ((pro)) list of custom headers that imgproxy will send while requesting the source image, divided by `\;` (can be redefined by `IMGPROXY_CUSTOM_HEADERS_SEPARATOR`). Example: `X-MyHeader1=Lorem\;X-MyHeader2=Ipsum` * [`IMGPROXY_CUSTOM_RESPONSE_HEADERS`]: ((pro)) a list of custom response headers, separated by `\;` (can be redefined by `IMGPROXY_CUSTOM_HEADERS_SEPARATOR`). Example: `X-MyHeader1=Lorem\;X-MyHeader2=Ipsum` * [`IMGPROXY_CUSTOM_HEADERS_SEPARATOR`]: ((pro)) a string that will be used as a custom header separator. Default: `\;` @@ -346,7 +347,7 @@ Check out the [Best format](../features/best_format.mdx) guide to learn more. ## Colorspace and HDR -* [`IMGPROXY_PRESERVE_HDR`]: when `true`, imgproxy will preserve 16-bit images as 16-bit. When `false`, imgproxy will convert 16-bit images to 8-bit. Colorspace (color/grayscale) is always preserved regardless of this setting. See the [Colorspace and HDR preservation](../image_formats_support.mdx#colorspace-and-hdr-preservation) guide for more details. Default: `false` +* [`IMGPROXY_PRESERVE_HDR`]: when `true`, imgproxy will preserve high bit images. When `false`, imgproxy will convert high bit images to 8-bit. Colorspace (color/grayscale) is always preserved regardless of this setting. See the [Colorspace and HDR preservation](../image_formats_support.mdx#colorspace-and-hdr-preservation) guide for more details. Default: `false` ## Client Hints support @@ -445,22 +446,24 @@ Read the [Object Classification guide](../features/object_classification.mdx) fo imgproxy can cache processed images in various storage backends to improve performance and reduce processing overhead. -* [`IMGPROXY_CACHE_USE`]: ((pro)) the cache storage adapter to use. Can be `filesystem`, `s3`, `gcs`, `abs` (Azure Blob Storage), or `swift`. When blank, the cache is disabled. Default: blank +* [`IMGPROXY_CACHE_USE`]: ((pro)) the cache storage adapter to use. Can be `fs`, `s3`, `gcs`, `abs` (Azure Blob Storage), or `swift` (OpenStack Swift). When blank, the cache is disabled. Default: blank * [`IMGPROXY_CACHE_PATH_PREFIX`]: ((pro)) a path prefix for the cache files. This can be useful to organize cache files in a specific directory structure. Default: blank -* [`IMGPROXY_CACHE_BUCKET`]: ((pro)) the bucket name for cloud storage adapters (S3, GCS, ABS, Swift). When using filesystem adapter, this can be used as an additional path component. Default: blank +* [`IMGPROXY_CACHE_BUCKET`]: ((pro)) the bucket name for cloud storage adapters (S3, GCS, ABS, OpenStack Swift). When using filesystem adapter, this can be used as an additional path component. Default: blank * [`IMGPROXY_CACHE_KEY_HEADERS`]: ((pro)) a comma-separated list of HTTP request headers to include in the cache key. This allows caching different versions of the same image based on request headers. Default: blank * [`IMGPROXY_CACHE_KEY_COOKIES`]: ((pro)) a comma-separated list of HTTP request cookies to include in the cache key. This allows caching different versions of the same image based on cookies. Default: blank * [`IMGPROXY_CACHE_REPORT_ERRORS`]: ((pro)) when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` -### Cache storage: Local filesystem {#cache-storage-local-filesystem} +### Local filesystem {#cache-storage-local-filesystem} -imgproxy can store cached images on the local filesystem. To use filesystem cache, set `IMGPROXY_CACHE_USE` to `filesystem`: +imgproxy can store cached images on the local filesystem. To use [filesystem cache](../cache/internal/local_filesystem.mdx), set `IMGPROXY_CACHE_USE` to `filesystem`: * [`IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT`]: ((pro)) the root directory for filesystem cache. Default: blank -### Cache storage: Amazon S3 {#cache-storage-amazon-s3} +See full documentation in [Cache storage: Local filesystem](../cache/internal/local_filesystem.mdx). -imgproxy can store cached images in Amazon S3 buckets or S3-compatible storage. To use S3 cache, set `IMGPROXY_CACHE_USE` to `s3`: +### Amazon S3 {#cache-storage-amazon-s3} + +imgproxy can store cached images in Amazon S3 buckets or S3-compatible storage. To use [S3 cache](../cache/internal/amazon_s3.mdx), set `IMGPROXY_CACHE_USE` to `s3`: * [`IMGPROXY_CACHE_S3_REGION`]: ((pro)) the S3 region for the cache bucket * [`IMGPROXY_CACHE_S3_ENDPOINT`]: ((pro)) a custom S3 endpoint for the cache. Useful for S3-compatible services like MinIO, Cloudflare R2, DigitalOcean Spaces, etc. Default: blank @@ -473,16 +476,16 @@ imgproxy can store cached images in Amazon S3 buckets or S3-compatible storage. Credentials for S3 cache can be provided using the same methods as for S3 image sources: IAM roles, `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables, or a shared credentials file. ::: -### Cache storage: Google Cloud Storage {#cache-storage-google-cloud-storage} +### Google Cloud Storage {#cache-storage-google-cloud-storage} -imgproxy can store cached images in Google Cloud Storage buckets. To use GCS cache, set `IMGPROXY_CACHE_USE` to `gcs`: +imgproxy can store cached images in Google Cloud Storage buckets. To use [GCS cache](../cache/internal/google_cloud_storage.mdx), set `IMGPROXY_CACHE_USE` to `gcs`: * [`IMGPROXY_CACHE_GCS_KEY`]: ((pro)) the Google Cloud JSON key for cache access. When running inside Google Cloud infrastructure, imgproxy will try to use the default service account credentials if this is not set. Default: blank * [`IMGPROXY_CACHE_GCS_ENDPOINT`]: ((pro)) a custom Google Cloud Storage endpoint for cache. Default: blank -### Cache storage: Azure Blob Storage {#cache-storage-azure-blob-storage} +### Azure Blob Storage {#cache-storage-azure-blob-storage} -imgproxy can store cached images in Azure Blob Storage containers. To use Azure cache, set `IMGPROXY_CACHE_USE` to `abs`: +imgproxy can store cached images in Azure Blob Storage containers. To use [Azure cache](../cache/internal/azure_blob_storage.mdx), set `IMGPROXY_CACHE_USE` to `abs`: * [`IMGPROXY_CACHE_ABS_NAME`]: ((pro)) the Azure account name for cache storage. Default: blank * [`IMGPROXY_CACHE_ABS_KEY`]: ((pro)) the Azure account key for cache storage. Default: blank @@ -492,9 +495,9 @@ imgproxy can store cached images in Azure Blob Storage containers. To use Azure Azure cache also supports authentication via Managed Identity or Service Principal using the same `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, and related environment variables as Azure Blob Storage image sources. ::: -### Cache storage: OpenStack Swift {#cache-storage-openstack-swift} +### OpenStack Swift {#cache-storage-openstack-swift} -imgproxy can store cached images in OpenStack Object Storage (Swift). To use Swift cache, set `IMGPROXY_CACHE_USE` to `swift`: +imgproxy can store cached images in OpenStack Object Storage (Swift). To use [Swift cache](../cache/internal/openstack_swift.mdx), set `IMGPROXY_CACHE_USE` to `swift`: * [`IMGPROXY_CACHE_SWIFT_USERNAME`]: ((pro)) the username for Swift API access for cache. Default: blank * [`IMGPROXY_CACHE_SWIFT_API_KEY`]: ((pro)) the API key for Swift API access for cache. Default: blank @@ -505,7 +508,7 @@ imgproxy can store cached images in OpenStack Object Storage (Swift). To use Swi * [`IMGPROXY_CACHE_SWIFT_TIMEOUT_SECONDS`]: ((pro)) the data channel timeout in seconds for cache operations. Default: 60 * [`IMGPROXY_CACHE_SWIFT_CONNECT_TIMEOUT_SECONDS`]: ((pro)) the connect channel timeout in seconds for cache operations. Default: 10 -Read the [Cache guide](../features/cache.mdx) for more info. +Read the [Internal cache guide](../cache/internal.mdx) for more info. ## Fallback image diff --git a/docs/features/cache.mdx b/docs/features/cache.mdx index 2a2fa4e..02ef705 100644 --- a/docs/features/cache.mdx +++ b/docs/features/cache.mdx @@ -1,117 +1,4 @@ --- title: Cache -description: Learn about how to configure and use imgproxy's internal cache +description: Learn how to configure cache in imgproxy --- - -# Cache ((pro)) - -imgproxy Pro provides an internal cache that stores processed images on disk or in cloud storage. This cache can act as both a primary cache and a secondary cache that serves as a fallback when your CDN cache misses. - -:::tip -While putting a CDN in front of imgproxy is and will always be a best practice, the internal cache provides long-term storage for cases that require an additional caching layer. -::: - -## Why use internal cache? - -The internal cache provides long-term persistent storage for processed images, unlike CDNs that typically delete rarely accessed content. It stores images in a single location rather than across multiple edge stores, eliminating cache misses when requests hit different edges. The cache is designed specifically for imgproxy, working seamlessly with features like modern image format detection and client hints support that generic external caches don't understand. - -The cache is protected by the same security measures as imgproxy itself, including URL signatures and processing restrictions. Importantly, URL signatures are not part of the cache key, so you can rotate keys or use multiple key/salt pairs without invalidating cached images. You maintain full control over where the cache is stored and how it integrates with your infrastructure. - -## Configuration - -You need to define the following config variables to enable the internal cache: - -* [`IMGPROXY_CACHE_USE`]: the cache storage adapter to use. Can be `filesystem`, `s3`, `gcs`, `abs` (Azure Blob Storage), or `swift`. When blank, the cache is disabled. Default: blank -* [`IMGPROXY_CACHE_PATH_PREFIX`]: _(optional)_ a path prefix for the cache files. This can be useful to organize cache files in a specific directory structure. Default: blank -* [`IMGPROXY_CACHE_BUCKET`]: _(optional)_ the bucket name for cloud storage adapters (S3, GCS, ABS, Swift). When using filesystem adapter, this can be used as an additional path component. Default: blank -* [`IMGPROXY_CACHE_KEY_HEADERS`]: _(optional)_ a list of HTTP request headers (comma-separated) to include in the cache key. This allows caching different versions of the same image based on request headers. Default: blank -* [`IMGPROXY_CACHE_KEY_COOKIES`]: _(optional)_ a list of HTTP request cookies (comma-separated) to include in the cache key. This allows caching different versions of the same image based on cookies. Default: blank -* [`IMGPROXY_CACHE_REPORT_ERRORS`]: when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` - -### Storage configuration - -The internal cache supports all the storage backends that imgproxy can read source images from: local filesystem, Amazon S3 and compatible services (Cloudflare R2, DigitalOcean Spaces, MinIO, etc.), Google Cloud Storage, Microsoft Azure Blob Storage, and OpenStack Swift. - -Configure the storage backend using the same configuration options as for image sources, but with the `IMGPROXY_CACHE_` prefix instead: - -* For filesystem cache, use [`IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT`](../configuration/options.mdx#cache-storage-local-filesystem) -* For S3 cache, use `IMGPROXY_CACHE_S3_*` [variables](../configuration/options.mdx#cache-storage-amazon-s3) (e.g., `IMGPROXY_CACHE_S3_REGION`, `IMGPROXY_CACHE_S3_ENDPOINT`) -* For GCS cache, use `IMGPROXY_CACHE_GCS_*` [variables](../configuration/options.mdx#cache-storage-google-cloud-storage) -* For Azure Blob Storage cache, use `IMGPROXY_CACHE_ABS_*` [variables](../configuration/options.mdx#cache-storage-azure-blob-storage) -* For Swift cache, use `IMGPROXY_CACHE_SWIFT_*` [variables](../configuration/options.mdx#cache-storage-openstack-swift) - -See the [configuration options](../configuration/options.mdx#cache) documentation for the full list of available variables. - -## Examples - -### Filesystem cache - -```bash -IMGPROXY_CACHE_USE=filesystem -IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT=/var/cache/imgproxy -IMGPROXY_CACHE_PATH_PREFIX=images -``` - -### S3 cache - -```bash -IMGPROXY_CACHE_USE=s3 -IMGPROXY_CACHE_BUCKET=my-imgproxy-cache -IMGPROXY_CACHE_S3_REGION=us-east-1 -# AWS credentials are provided via IAM role or environment variables -``` - -### Google Cloud Storage cache - -```bash -IMGPROXY_CACHE_USE=gcs -IMGPROXY_CACHE_BUCKET=my-imgproxy-cache -IMGPROXY_CACHE_GCS_KEY=/path/to/credentials.json -``` - -### Azure Blob Storage cache - -```bash -IMGPROXY_CACHE_USE=abs -IMGPROXY_CACHE_BUCKET=imgproxy-cache -IMGPROXY_CACHE_ABS_NAME=mystorageaccount -IMGPROXY_CACHE_ABS_KEY=your_account_key -``` - -## Cache key - -The cache key is generated based on: - -* Source image URL -* Processing options -* Output format -* Optional: Request headers specified in `IMGPROXY_CACHE_KEY_HEADERS` -* Optional: Request cookies specified in `IMGPROXY_CACHE_KEY_COOKIES` - -URL signature is **not** a part of the cache key, which allows key rotation without invalidating the cache. - -## Limitations - -* **No manual cache invalidation**: Currently, imgproxy doesn't provide built-in means to invalidate the cache. However, imgproxy includes the [cachebuster](../usage/processing.mdx#cache-buster) in the cache key, so you can use it to force cache invalidation when needed. Most storage offerings also support object expiration, so you can set a reasonable expiration time for cached images. -* **No cache for info requests**: The internal cache is currently only used for image processing requests. Requests to the `/info` endpoint are not cached. - -## How it works - -When a request comes in: - -1. imgproxy checks the URL signature (if enabled) -2. imgproxy generates the cache key from the request parameters -3. imgproxy checks if a cached image exists in the configured storage -4. If the cached image exists and is valid, imgproxy serves it directly -5. If not, imgproxy processes the image and stores the result in the cache before serving it - -## Monitoring - -Monitor cache performance with metrics: - -* Cache hit rate -* Cache size -* Cache evictions -* Cache latency - -These metrics are available through [monitoring endpoints](../monitoring/prometheus.mdx). diff --git a/docs/features/object_classification.mdx b/docs/features/object_classification.mdx index 40a4566..9f8c482 100644 --- a/docs/features/object_classification.mdx +++ b/docs/features/object_classification.mdx @@ -5,13 +5,13 @@ description: Learn about how to classify objects in your images with imgproxy # Object classification ((pro)) -imgproxy Pro can classify objects detected in images, providing detailed information about what the objects are. This feature extends [object detection](object_detection.mdx) by not only detecting objects but also identifying their specific classes or categories. +imgproxy Pro can classify objects in images, providing detailed information about each object. This feature extends [object detection](object_detection.mdx) by not only detecting objects but also identifying their specific classes or categories. :::info Object classification requires [object detection](object_detection.mdx) to be configured and enabled. Classification is performed on the objects detected by the object detection model. ::: -You can use object classification for content moderation, image organization, and automatic tagging. You can [fetch the classified objects info](../usage/getting_info.mdx#classify-objects) via the info handler. +You can use object classification for content moderation, image organization, and automatic tagging. You can fetch information about the classified objects via the info handler. ## Configuration @@ -40,9 +40,9 @@ You need to define the following config variables to enable object classificatio ### Class names file -The class names file is used to map the class indexes from the neural network output to human-readable class names. The path to the class names file should be defined in the `IMGPROXY_OBJECT_CLASSIFY_CLASSES` config variable. +The class names file maps the neural network's class indexes to human-readable class names. The path to the class names file should be defined in the `IMGPROXY_OBJECT_CLASSIFY_CLASSES` config variable. -The class names file should contain one class name per line. The class names should be in the same order as the classes in the neural network output. Example: +The class names file should contain one class name per line. The class names should match the order of the classes in the neural network output. Example: ```text person @@ -66,4 +66,4 @@ The response is an array of objects, each containing: * `name`: The class name from the class names file * `confidence`: The confidence score for this classification -See [getting info documentation](../usage/getting_info.mdx#classify-objects) for more details. +See the [getting info documentation](../usage/getting_info.mdx#classify-objects) for more details. diff --git a/docs/image_formats_support.mdx b/docs/image_formats_support.mdx index 9baf00d..b7bf00b 100644 --- a/docs/image_formats_support.mdx +++ b/docs/image_formats_support.mdx @@ -92,17 +92,17 @@ Since this still requires more data to be downloaded, video thumbnail generation imgproxy always preserves the source image's colorspace: -* Color images remain color images -* Grayscale images remain grayscale images -* Colorspace types are maintained +* Color images remain color images. +* Grayscale images remain grayscale images. +* Colorspace types are maintained. The bit depth handling depends on the [IMGPROXY_PRESERVE_HDR](configuration/options.mdx#IMGPROXY_PRESERVE_HDR) configuration setting: **When `IMGPROXY_PRESERVE_HDR` is enabled:** -* 16-bit images remain 16-bit in the output (eg. GRAYSCALE16 remains GRAYSCALE16, scRGB remains scRGB) +* High bit images remain high bit in the output (eg, GRAYSCALE16 remains GRAYSCALE16, scRGB remains scRGB) **When `IMGPROXY_PRESERVE_HDR` is disabled (default):** -* 16-bit images are converted to 8-bit (eg. GRAYSCALE16 becomes GRAYSCALE8, RGB and scRGB become sRGB) +* High bit images are converted to 8-bit (eg, GRAYSCALE16 becomes GRAYSCALE8, RGB and scRGB become sRGB) * 8-bit images remain 8-bit diff --git a/docs/image_sources/amazon_s3.mdx b/docs/image_sources/amazon_s3.mdx index 8d60917..8ca72fa 100644 --- a/docs/image_sources/amazon_s3.mdx +++ b/docs/image_sources/amazon_s3.mdx @@ -80,13 +80,13 @@ This allows imgproxy to access buckets in any region. However, the initial reque ## Restricting bucket access -For security purposes, you can restrict which S3 buckets imgproxy is allowed to access: +Restrict which S3 buckets imgproxy can access for security: * `IMGPROXY_S3_ALLOWED_BUCKETS`: a comma-separated list of bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed) * `IMGPROXY_S3_DENIED_BUCKETS`: a comma-separated list of bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank :::tip -Use `IMGPROXY_S3_ALLOWED_BUCKETS` to create an allowlist of trusted buckets, or use `IMGPROXY_S3_DENIED_BUCKETS` to block specific buckets. If both are set, allowed buckets take precedence. +Use `IMGPROXY_S3_ALLOWED_BUCKETS` to allow trusted buckets. Use `IMGPROXY_S3_DENIED_BUCKETS` to block specific ones. If both are set, allowed buckets override denied ones. ::: ## MinIO diff --git a/docs/image_sources/azure_blob_storage.mdx b/docs/image_sources/azure_blob_storage.mdx index e555368..8d01eb9 100644 --- a/docs/image_sources/azure_blob_storage.mdx +++ b/docs/image_sources/azure_blob_storage.mdx @@ -53,11 +53,11 @@ Alternatively, you can set `IMGPROXY_ABS_KEY` to your Azure Blob Storage account ## Restricting container access -For security purposes, you can restrict which Azure Blob Storage containers imgproxy is allowed to access: +Restrict which Azure Blob Storage containers imgproxy can access for security: * `IMGPROXY_ABS_ALLOWED_BUCKETS`: a comma-separated list of container names that imgproxy is allowed to access. When set, imgproxy will only process images from these containers. Default: blank (all containers allowed) * `IMGPROXY_ABS_DENIED_BUCKETS`: a comma-separated list of container names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these containers. Default: blank :::tip -Use `IMGPROXY_ABS_ALLOWED_BUCKETS` to create an allowlist of trusted containers, or use `IMGPROXY_ABS_DENIED_BUCKETS` to block specific containers. If both are set, allowed containers take precedence. +Use `IMGPROXY_ABS_ALLOWED_BUCKETS` to allow trusted containers. Use `IMGPROXY_ABS_DENIED_BUCKETS` to block specific ones. If both are set, allowed containers override denied ones. ::: diff --git a/docs/image_sources/google_cloud_storage.mdx b/docs/image_sources/google_cloud_storage.mdx index 2d21fe6..856a9b5 100644 --- a/docs/image_sources/google_cloud_storage.mdx +++ b/docs/image_sources/google_cloud_storage.mdx @@ -39,11 +39,11 @@ For security reasons, imgproxy accepts only service account keys for Google Clou ## Restricting bucket access -For security purposes, you can restrict which GCS buckets imgproxy is allowed to access: +Restrict which GCS buckets imgproxy can access for security: * `IMGPROXY_GCS_ALLOWED_BUCKETS`: a comma-separated list of bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed) * `IMGPROXY_GCS_DENIED_BUCKETS`: a comma-separated list of bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank :::tip -Use `IMGPROXY_GCS_ALLOWED_BUCKETS` to create an allowlist of trusted buckets, or use `IMGPROXY_GCS_DENIED_BUCKETS` to block specific buckets. If both are set, allowed buckets take precedence. +Use `IMGPROXY_GCS_ALLOWED_BUCKETS` to allow trusted buckets. Use `IMGPROXY_GCS_DENIED_BUCKETS` to block specific ones. If both are set, allowed buckets override denied ones. ::: diff --git a/docs/image_sources/openstack_swift.mdx b/docs/image_sources/openstack_swift.mdx index 8e8c98a..016fb14 100644 --- a/docs/image_sources/openstack_swift.mdx +++ b/docs/image_sources/openstack_swift.mdx @@ -23,11 +23,11 @@ If filenames in your OpenStack Object Storage may contain `?`, you may want to s ## Restricting container access -For security purposes, you can restrict which Swift containers imgproxy is allowed to access: +Restrict which Swift containers imgproxy can access for security: * `IMGPROXY_SWIFT_ALLOWED_BUCKETS`: a comma-separated list of container names that imgproxy is allowed to access. When set, imgproxy will only process images from these containers. Default: blank (all containers allowed) * `IMGPROXY_SWIFT_DENIED_BUCKETS`: a comma-separated list of container names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these containers. Default: blank :::tip -Use `IMGPROXY_SWIFT_ALLOWED_BUCKETS` to create an allowlist of trusted containers, or use `IMGPROXY_SWIFT_DENIED_BUCKETS` to block specific containers. If both are set, allowed containers take precedence. +Use `IMGPROXY_SWIFT_ALLOWED_BUCKETS` to allow trusted containers. Use `IMGPROXY_SWIFT_DENIED_BUCKETS` to block specific ones. If both are set, allowed containers override denied ones. ::: diff --git a/docs/usage/processing.mdx b/docs/usage/processing.mdx index 6d11333..b8796f7 100644 --- a/docs/usage/processing.mdx +++ b/docs/usage/processing.mdx @@ -594,7 +594,7 @@ imgproxy [detects objects](../features/object_detection.mdx) of the provided cla * `scale_factor`: a float value that defines how much the crop area should be scaled relative to the detected objects. For example, `1.0` crops exactly to the detected objects, while `1.2` adds 20% padding around them. * `class_name1`, `class_name2`, ..., `class_nameN`: _(optional)_ names of the object classes to detect. If class names are omitted, imgproxy crops to all detected objects. -This option is useful when you want to automatically extract the area containing specific objects from an image, such as extracting all faces from a group photo or isolating products from a catalog image. +This option is useful when you want to automatically extract the area containing specific objects from an image, such as all faces in a group photo or products in a catalog image. :::info When no objects are detected, imgproxy will not crop the image and will process it as usual. diff --git a/sidebars.ts b/sidebars.ts index a3e5ff2..b15cb61 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -80,11 +80,6 @@ const sidebars: SidebarsConfig = { id: "features/chained_pipelines", className: "menu__list-item--badge badge--pro", }, - { - type: "doc", - id: "features/cache", - className: "menu__list-item--badge badge--pro", - }, ], }, { @@ -103,6 +98,37 @@ const sidebars: SidebarsConfig = { "image_sources/openstack_swift", ], }, + { + type: "category", + label: "Cache", + link: { + type: "doc", + id: "features/cache", + }, + items: [ + { + type: "doc", + id: "cache/external", + label: "External cache", + }, + { + type: "category", + label: "Internal cache", + link: { + type: "doc", + id: "cache/internal", + }, + className: "menu__list-item--badge badge--pro", + items: [ + "cache/internal/local_filesystem", + "cache/internal/amazon_s3", + "cache/internal/google_cloud_storage", + "cache/internal/azure_blob_storage", + "cache/internal/openstack_swift", + ], + }, + ], + }, { type: "category", label: "Monitoring", diff --git a/src/css/badge.css b/src/css/badge.css index ba21c5f..d5277bf 100644 --- a/src/css/badge.css +++ b/src/css/badge.css @@ -1,5 +1,5 @@ .badge, -.menu__list-item--badge a::after { +.menu__list-item--badge .menu__link::after { --ifm-badge-background-color: transparent; --ifm-badge-border-width: 1px; --ifm-badge-border-radius: 0.4em; From 839b1768916568d4e766224b418ed9ae2a652ad3 Mon Sep 17 00:00:00 2001 From: Viktor Sokolov Date: Tue, 7 Apr 2026 13:56:13 +0200 Subject: [PATCH 3/7] Grammarly, fixed classification, addressed PR comments --- docs/cache/external.mdx | 32 +- docs/cache/internal.mdx | 11 - docs/cache/internal/amazon_s3.mdx | 4 +- docs/cache/internal/azure_blob_storage.mdx | 2 +- docs/cache/internal/google_cloud_storage.mdx | 2 +- docs/cache/internal/local_filesystem.mdx | 4 +- docs/cache/internal/openstack_swift.mdx | 2 +- docs/configuration/options.mdx | 36 +- docs/features/cache.mdx | 4 - docs/features/classification.mdx | 632 +++++++++++++++++++ docs/features/object_classification.mdx | 69 -- docs/image_formats_support.mdx | 2 +- docs/monitoring/new_relic.mdx | 22 +- docs/monitoring/open_telemetry.mdx | 1 - docs/usage/getting_info.mdx | 12 +- docs/usage/processing.mdx | 6 +- sidebars.ts | 6 +- src/css/badge.css | 4 +- 18 files changed, 707 insertions(+), 144 deletions(-) delete mode 100644 docs/features/cache.mdx create mode 100644 docs/features/classification.mdx delete mode 100644 docs/features/object_classification.mdx diff --git a/docs/cache/external.mdx b/docs/cache/external.mdx index ec4905b..5baaaf0 100644 --- a/docs/cache/external.mdx +++ b/docs/cache/external.mdx @@ -12,10 +12,10 @@ Most major CDNs (Cloudflare, Fastly, AWS CloudFront, Akamai, etc.) can cache img ### Recommended CDN settings -* **Origin shield** - Add a secondary cache layer between your CDN and imgproxy origin * **Image optimization** - Disable CDN image optimization to avoid double-processing -* **Compression** - Enable gzip/Brotli compression for bandwidth savings -* **HTTP/2 Server Push** - Push critical images to reduce latency +* **Compression** - In case your CDN supports conditional compression of SVG images, enable gzip/Brotli compression for bandwidth savings +* **Include essential headers*** - It's strongly recommended to include `Accept` header in the cache key. If you have client hints enabled, include also `DPR`, `Sec-CH-Dpr`, and `Sec-CH-Width` headers. +* **Origin shield** - Add a secondary cache layer between your CDN and imgproxy origin if your CDN supports it. ## nginx caching @@ -32,16 +32,24 @@ server { listen 80; server_name images.example.com; - # Include request and feature signals that can change imgproxy output - proxy_cache_key "$scheme$request_method$host$request_uri:accept=$http_accept:dpr=$http_dpr:width=$http_width:chdpr=$http_sec_ch_dpr:chwidth=$http_sec_ch_width"; + # Uncomment if you do not use format negotiation and client hints + # proxy_cache_key "$scheme$proxy_host$request_uri"; + + # Uncomment if you use format negotiation + # proxy_cache_key "$scheme$proxy_host$request_uri$http_accept"; + + # Uncomment if you use client hints + # proxy_cache_key "$scheme$request_method$host$request_uri:dpr=$http_dpr:width=$http_width:chdpr=$http_sec_ch_dpr:chwidth=$http_sec_ch_width"; + + # Uncomment if you use format negotiation and client hints + # proxy_cache_key "$scheme$request_method$host$request_uri:accept=$http_accept:dpr=$http_dpr:width=$http_width:chdpr=$http_sec_ch_dpr:chwidth=$http_sec_ch_width"; location / { proxy_pass http://imgproxy; # Cache configuration proxy_cache imgproxy_cache; - proxy_cache_valid 200 24h; - proxy_cache_valid 304 24h; + proxy_cache_valid 200 30d; proxy_cache_valid 404 1m; proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; proxy_cache_background_update on; @@ -65,7 +73,7 @@ The exact key depends on which imgproxy features can change output for the same proxy_cache_key "$scheme$proxy_host$request_uri"; ``` -2. Include format negotiation signal when WebP/AVIF/JXL preference can vary by client: +2. Include [format negotiation](../configuration/options.mdx#avifwebpjpeg-xl-support-detection) signal when WebP/AVIF/JXL preference can vary by client: ```nginx proxy_cache_key "$scheme$proxy_host$request_uri$http_accept"; @@ -82,7 +90,7 @@ Use the smallest key that still prevents collisions for your traffic profile. ### Key recommendations * Include `Accept` in the cache key if format negotiation is used. -* Include DPR/width-related hints in the cache key if Client Hints are used to vary output. +* Include DPR/width-related hints in the cache key if [Client Hints](../configuration/options.mdx#client-hints-support) are used to vary output. * Set long `inactive` timeout (30d) to keep popular images in cache. * Configure `proxy_cache_use_stale` for graceful degradation during origin issues. * Monitor `/proc/sys/fs/file-max` and increase if needed for large caches. @@ -163,10 +171,10 @@ sub vcl_hash { } sub vcl_backend_response { - # Cache successful responses for 24 hours + # Cache successful responses for 30 days if (beresp.status == 200) { - set beresp.ttl = 24h; - set beresp.keep = 24h; + set beresp.ttl = 30d; + set beresp.keep = 30d; } # Cache 404s for a short period diff --git a/docs/cache/internal.mdx b/docs/cache/internal.mdx index 64face6..cb2a8b7 100644 --- a/docs/cache/internal.mdx +++ b/docs/cache/internal.mdx @@ -66,14 +66,3 @@ When a request comes in: 3. imgproxy checks if a cached image exists in the configured storage. 4. If the cached image exists and is valid, imgproxy serves it directly. 5. If not, imgproxy processes the image and stores the result in the cache before serving it. - -## Monitoring - -Monitor cache performance with metrics: - -* Cache hit rate -* Cache size -* Cache evictions -* Cache latency - -These metrics are available through [monitoring endpoints](../monitoring/prometheus.mdx). diff --git a/docs/cache/internal/amazon_s3.mdx b/docs/cache/internal/amazon_s3.mdx index 7d1a865..427ed73 100644 --- a/docs/cache/internal/amazon_s3.mdx +++ b/docs/cache/internal/amazon_s3.mdx @@ -8,8 +8,8 @@ imgproxy can store cached images in Amazon S3 buckets or S3-compatible storage. 1. Set the `IMGPROXY_CACHE_USE` environment variable to `s3`. 2. [Set up the necessary credentials](#set-up-credentials) to grant access to your cache bucket. -3. _(optional)_ Specify the AWS region with `IMGPROXY_CACHE_S3_REGION`. Default: `us-west-1` -4. _(optional)_ Specify the cache bucket name with `IMGPROXY_CACHE_BUCKET`. +3. Specify the cache bucket name with `IMGPROXY_CACHE_BUCKET`. +4. _(optional)_ Specify the AWS region with `IMGPROXY_CACHE_S3_REGION` or `AWS_REGION`. Default: `us-west-1` 5. _(optional)_ Specify the S3 endpoint with `IMGPROXY_CACHE_S3_ENDPOINT`. You can also set `IMGPROXY_CACHE_S3_ENDPOINT_USE_PATH_STYLE=false` to use the virtual host style for the endpoint. 6. _(optional)_ Specify the AWS IAM Role to Assume with `IMGPROXY_CACHE_S3_ASSUME_ROLE_ARN`. 7. _(optional)_ Specify the External ID to pass to the AWS IAM Role when assuming it using `IMGPROXY_CACHE_S3_ASSUME_ROLE_EXTERNAL_ID`. This will have no effect if the assume role ARN is not specified. diff --git a/docs/cache/internal/azure_blob_storage.mdx b/docs/cache/internal/azure_blob_storage.mdx index 890f514..15b75ab 100644 --- a/docs/cache/internal/azure_blob_storage.mdx +++ b/docs/cache/internal/azure_blob_storage.mdx @@ -9,7 +9,7 @@ imgproxy can store cached images in Azure Blob Storage containers. To use Azure 1. Set the `IMGPROXY_CACHE_USE` environment variable to `abs`. 2. Set `IMGPROXY_CACHE_ABS_NAME` to your Azure account name. 3. [Set up the necessary credentials](#set-up-credentials). -4. _(optional)_ Specify the cache container name with `IMGPROXY_CACHE_BUCKET`. +4. Specify the cache container name with `IMGPROXY_CACHE_BUCKET`. 5. _(optional)_ Specify the Azure Blob Storage endpoint with `IMGPROXY_CACHE_ABS_ENDPOINT`. ### Configuration diff --git a/docs/cache/internal/google_cloud_storage.mdx b/docs/cache/internal/google_cloud_storage.mdx index 441f8a1..e985d8a 100644 --- a/docs/cache/internal/google_cloud_storage.mdx +++ b/docs/cache/internal/google_cloud_storage.mdx @@ -8,7 +8,7 @@ imgproxy can store cached images in Google Cloud Storage buckets. To use the GCS 1. Set the `IMGPROXY_CACHE_USE` environment variable to `gcs`. 2. [Set up credentials](#setup-credentials) to grant access to your cache bucket. -3. _(optional)_ Specify the cache bucket name with `IMGPROXY_CACHE_BUCKET`. +3. Specify the cache bucket name with `IMGPROXY_CACHE_BUCKET`. 4. _(optional)_ Specify the Google Cloud Storage endpoint with `IMGPROXY_CACHE_GCS_ENDPOINT`. ### Configuration diff --git a/docs/cache/internal/local_filesystem.mdx b/docs/cache/internal/local_filesystem.mdx index 1ac3516..b7e808b 100644 --- a/docs/cache/internal/local_filesystem.mdx +++ b/docs/cache/internal/local_filesystem.mdx @@ -6,7 +6,7 @@ description: Learn about how to configure the local filesystem cache in imgproxy imgproxy can store cached images on the local filesystem. To use filesystem cache, do the following: -1. Set the `IMGPROXY_CACHE_USE` environment variable to the filesystem. +1. Set the `IMGPROXY_CACHE_USE` environment variable to `fs`. 2. Set `IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT` to your cache directory path. 3. _(optional)_ Specify a path prefix for cache files with `IMGPROXY_CACHE_PATH_PREFIX`. @@ -25,5 +25,5 @@ imgproxy can store cached images on the local filesystem. To use filesystem cach Assume you want to cache processed images in `/var/cache/imgproxy`. Run imgproxy with `IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT` set to your cache directory: ```bash -IMGPROXY_CACHE_USE=filesystem IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT=/var/cache/imgproxy imgproxy +IMGPROXY_CACHE_USE=fs IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT=/var/cache/imgproxy imgproxy ``` diff --git a/docs/cache/internal/openstack_swift.mdx b/docs/cache/internal/openstack_swift.mdx index cf6a0f7..049fa89 100644 --- a/docs/cache/internal/openstack_swift.mdx +++ b/docs/cache/internal/openstack_swift.mdx @@ -15,7 +15,7 @@ imgproxy can store cached images in OpenStack Object Storage, also known as Swif * `IMGPROXY_CACHE_SWIFT_TENANT`: the tenant name for cache (optional, v2 auth only). Default: blank * `IMGPROXY_CACHE_SWIFT_DOMAIN`: the Swift domain name for cache (optional, v3 auth only). Default: blank -3. _(optional)_ Specify the cache container name with `IMGPROXY_CACHE_BUCKET`. +3. Specify the cache container name with `IMGPROXY_CACHE_BUCKET`. ### Configuration diff --git a/docs/configuration/options.mdx b/docs/configuration/options.mdx index cef34f4..12f8533 100644 --- a/docs/configuration/options.mdx +++ b/docs/configuration/options.mdx @@ -48,9 +48,9 @@ echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n') * [`IMGPROXY_PATH_PREFIX`]: the URL path prefix. Example: when set to `/abc/def`, the imgproxy URL will be `/abc/def/%signature/%processing_options/%source_url`. Default: blank * [`IMGPROXY_USER_AGENT`]: the User-Agent header that will be sent with the source image request. You can use the `%current_version` variable to insert the current imgproxy version. Default: `imgproxy/%current_version` * [`IMGPROXY_USE_ETAG`]: when set to `true`, enables using the [ETag](https://en.wikipedia.org/wiki/HTTP_ETag) HTTP header for HTTP cache control. Default: `false` -* [`IMGPROXY_ETAG_BUSTER`]: a global ETag buster value. Change it to invalidate old ETags and prevent `304 Not Modified` responses for stale client/CDN validators. Default: blank +* [`IMGPROXY_ETAG_BUSTER`]: a global ETag buster value. Change this value if you update configuration that affects image processing, to invalidate old ETags and avoid `304 Not Modified` responses from stale client/CDN validators. Default: blank * [`IMGPROXY_USE_LAST_MODIFIED`]: when set to `true`, enables using the [Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) HTTP header for HTTP cache control. Default: `false` -* [`IMGPROXY_LAST_MODIFIED_BUSTER`]: a global `Last-Modified` buster timestamp. If incoming `If-Modified-Since` is older than this value, imgproxy ignores it and forces revalidation; if origin `Last-Modified` is older, imgproxy replaces it with this timestamp. Use it to invalidate stale client/CDN `Last-Modified` validators after global processing changes. Default: `0` +* [`IMGPROXY_LAST_MODIFIED_BUSTER`]: a global `Last-Modified` buster timestamp in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html) format. By setting it to a specific datetime, you can make imgproxy treat all the images as if they were modified at least at that datetime. Default: blank * [`IMGPROXY_CUSTOM_REQUEST_HEADERS`]: ((pro)) list of custom headers that imgproxy will send while requesting the source image, divided by `\;` (can be redefined by `IMGPROXY_CUSTOM_HEADERS_SEPARATOR`). Example: `X-MyHeader1=Lorem\;X-MyHeader2=Ipsum` * [`IMGPROXY_CUSTOM_RESPONSE_HEADERS`]: ((pro)) a list of custom response headers, separated by `\;` (can be redefined by `IMGPROXY_CUSTOM_HEADERS_SEPARATOR`). Example: `X-MyHeader1=Lorem\;X-MyHeader2=Ipsum` * [`IMGPROXY_CUSTOM_HEADERS_SEPARATOR`]: ((pro)) a string that will be used as a custom header separator. Default: `\;` @@ -167,8 +167,6 @@ When using imgproxy in a development environment, it can be useful to ignore SSL Also you may want imgproxy to respond with the same error message that it writes to the log: -* [`IMGPROXY_DEVELOPMENT_ERRORS_MODE`]: when `true`, imgproxy will respond with detailed error messages. Not recommended for production because some errors may contain stack traces. - * [`IMGPROXY_ALLOW_SECURITY_OPTIONS`]: when `true`, allows usage of security-related processing options such as `max_src_resolution`, `max_src_file_size`, `max_animation_frames`, `max_animation_frame_resolution`, and `max_result_dimension`. Default: `false`. :::warning @@ -423,24 +421,24 @@ imgproxy can detect objects on the image and use them to perform smart cropping, Read the [Object Detection guide](../features/object_detection.mdx) for more info. -## Object classification +## Classification -imgproxy can classify detected objects on the image and provide detailed information about what the objects are. +imgproxy can classify images by assigning them to predefined categories based on their overall content, similar to object detection but without identifying or locating individual objects. -* [`IMGPROXY_OBJECT_CLASSIFY_NET`]: ((pro)) a path to the classification neural network model in ONNX format. Default: blank -* [`IMGPROXY_OBJECT_CLASSIFY_CLASSES`]: ((pro)) the path to the text file with the class names, one per line. Default: blank -* [`IMGPROXY_OBJECT_CLASSIFY_NET_SIZE`]: ((pro)) the size of the neural network input. The width and the heights of the inputs should be the same, so this config value should be a single number. Default: 224 -* [`IMGPROXY_OBJECT_CLASSIFY_THRESHOLD`]: ((pro)) classifications with confidence below this value will be discarded. Default: 0.5 -* [`IMGPROXY_OBJECT_CLASSIFY_NORMALIZATION`]: ((pro)) the normalization type to apply to the input image. Possible values are: +* [`IMGPROXY_CLASSIFICATION_NET`]: ((pro)) a path to the classification neural network model in ONNX format. Default: blank +* [`IMGPROXY_CLASSIFICATION_CLASSES`]: ((pro)) the path to the text file with the class names, one per line. Default: blank +* [`IMGPROXY_CLASSIFICATION_NET_SIZE`]: ((pro)) the size of the neural network input. The width and the heights of the inputs should be the same, so this config value should be a single number. Default: 224 +* [`IMGPROXY_CLASSIFICATION_THRESHOLD`]: ((pro)) classifications with confidence below this value will be discarded. Default: 0.5 +* [`IMGPROXY_CLASSIFICATION_NORMALIZATION`]: ((pro)) the normalization type to apply to the input image. Possible values are: * `none`: _(default)_ no normalization - * `half`: normalize to [-0.5, 0.5] range + * `half`: normalize to [0, 1] range * `full`: normalize to [-1, 1] range * `imagenet`: normalize using ImageNet mean and standard deviation -* [`IMGPROXY_OBJECT_CLASSIFY_LAYOUT`]: ((pro)) the data layout of the neural network input. Possible values are: - * `nchw`: _(default)_ channels first - * `nhwc`: channels last +* [`IMGPROXY_CLASSIFICATION_LAYOUT`]: ((pro)) the data layout of the neural network input. Possible values are: + * `nchw`: channels first (PyTorch default) + * `nhwc`: _(default)_ channels last (TensorFlow default) -Read the [Object Classification guide](../features/object_classification.mdx) for more info. +Read the [Classification guide](../features/classification.mdx) for more info. ## Cache @@ -453,9 +451,11 @@ imgproxy can cache processed images in various storage backends to improve perfo * [`IMGPROXY_CACHE_KEY_COOKIES`]: ((pro)) a comma-separated list of HTTP request cookies to include in the cache key. This allows caching different versions of the same image based on cookies. Default: blank * [`IMGPROXY_CACHE_REPORT_ERRORS`]: ((pro)) when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` +Read the [Internal cache guide](../cache/internal.mdx) for more info. + ### Local filesystem {#cache-storage-local-filesystem} -imgproxy can store cached images on the local filesystem. To use [filesystem cache](../cache/internal/local_filesystem.mdx), set `IMGPROXY_CACHE_USE` to `filesystem`: +imgproxy can store cached images on the local filesystem. To use [filesystem cache](../cache/internal/local_filesystem.mdx), set `IMGPROXY_CACHE_USE` to `fs`: * [`IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT`]: ((pro)) the root directory for filesystem cache. Default: blank @@ -508,8 +508,6 @@ imgproxy can store cached images in OpenStack Object Storage (Swift). To use [Sw * [`IMGPROXY_CACHE_SWIFT_TIMEOUT_SECONDS`]: ((pro)) the data channel timeout in seconds for cache operations. Default: 60 * [`IMGPROXY_CACHE_SWIFT_CONNECT_TIMEOUT_SECONDS`]: ((pro)) the connect channel timeout in seconds for cache operations. Default: 10 -Read the [Internal cache guide](../cache/internal.mdx) for more info. - ## Fallback image You can set up a fallback image that will be used in case imgproxy is unable to fetch the requested one. Use one of the following variables: diff --git a/docs/features/cache.mdx b/docs/features/cache.mdx deleted file mode 100644 index 02ef705..0000000 --- a/docs/features/cache.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Cache -description: Learn how to configure cache in imgproxy ---- diff --git a/docs/features/classification.mdx b/docs/features/classification.mdx new file mode 100644 index 0000000..14277d7 --- /dev/null +++ b/docs/features/classification.mdx @@ -0,0 +1,632 @@ +--- +title: Classification +description: Learn about how to classify objects in your images with imgproxy +--- + +# Classification ((pro)) + +imgproxy can classify images by assigning them to predefined categories based on the overall content of the image. Unlike object detection, which answers “Where is a cat in this image?”, image classification answers “Is there a cat in this image?” by labeling the entire image as a whole. + +Specialized image classification models are typically faster and simpler than object detection because they do not need to locate objects within the image. They can also classify images based on broader concepts such as scenes, activities, or safety categories (e.g., NSFW vs. SFW), and require only labeled images for training instead of annotated bounding boxes. + +## Configuration + +:::tip +If you're using an imgproxy Pro Docker image with a tag suffixed with `-ml`, a basic classification model is included. For advanced classification, you may want to configure your own model. + +
+The list of classes available in the bundled model +``` +Accordion +Adhesive tape +Aircraft +Alarm clock +Alpaca +Ambulance +Ant +Antelope +Apple +Armadillo +Artichoke +Axe +Backpack +Bagel +Baked goods +Balance beam +Ball (Object) +Balloon +Banana +Band-aid +Banjo +Barge +Barrel +Baseball bat +Baseball glove +Bat (Animal) +Bathroom accessory +Bathroom cabinet +Bathtub +Beaker +Bear +Bed +Bee +Beehive +Beer +Beetle +Bell pepper +Belt +Bench +Bicycle +Bicycle helmet +Bidet +Billboard +Billiard table +Binoculars +Bird +Blender +Blue jay +Boat +Bomb +Book +Bookcase +Boot +Bottle +Bottle opener +Bow and arrow +Bowl +Bowling equipment +Box +Boy +Brassiere +Bread +Briefcase +Broccoli +Bronze sculpture +Brown bear +Bull +Burrito +Bus +Bust +Butterfly +Cabbage +Cabinetry +Cake +Cake stand +Calculator +Camel +Camera +Can opener +Canary +Candle +Candy +Cannon +Canoe +Cantaloupe +Car +Carrot +Cart +Cassette deck +Castle +Cat +Cat furniture +Caterpillar +Cattle +Ceiling fan +Cello +Centipede +Chainsaw +Chair +Cheese +Cheetah +Chest of drawers +Chicken +Chime +Chisel +Chopsticks +Christmas tree +Clock +Closet +Coat +Cocktail +Cocktail shaker +Coconut +Coffee (drink) +Coffee cup +Coffee table +Coffeemaker +Coin +Common fig +Common sunflower +Computer keyboard +Computer monitor +Computer mouse +Container +Convenience store +Cookie +Cooking spray +Corded phone +Cosmetics +Couch +Countertop +Cowboy hat +Crab +Cream +Cricket ball +Crocodile +Croissant +Crown +Crutch +Cucumber +Cupboard +Curtain +Cutting board +Dagger +Dairy Product +Deer +Desk +Dessert +Diaper +Dice +Digital clock +Dinosaur +Dishwasher +Dog +Dog bed +Doll +Dolphin +Door +Door handle +Doughnut +Dragonfly +Drawer +Dress +Drill (Tool) +Drink +Drinking straw +Drum +Duck +Dumbbell +Eagle +Earring +Egg +Elephant +Envelope +Eraser +Face powder +Facial tissue holder +Falcon +Fast food +Fax +Fedora +Filing cabinet +Fire hydrant +Fireplace +Fish +Fixed-wing aircraft +Flag +Flashlight +Flower +Flowerpot +Flute +Flying disc +Food processor +Football +Football helmet +Footwear +Fork +Fountain +Fox +French fries +French horn +Frog +Fruit +Frying pan +Garden Asparagus +Gas stove +Giraffe +Girl +Glasses +Glove +Goat +Goggles +Goldfish +Golf ball +Golf cart +Gondola +Goose +Grape +Grapefruit +Grinder +Guacamole +Guitar +Hair dryer +Hair spray +Hamburger +Hammer +Hamster +Hand dryer +Handbag +Handgun +Harbor seal +Harmonica +Harp +Harpsichord +Hat +Headphones +Heater +Hedgehog +Helicopter +Helmet +High heels +Hiking equipment +Hippopotamus +Honeycomb +Horizontal bar +Horse +Hot dog +House +Houseplant +Humidifier +Ice cream +Indoor rower +Infant bed +Insect +Ipod +Isopod +Jacket +Jacuzzi +Jaguar (Animal) +Jeans +Jellyfish +Jet ski +Jug +Juice +Kangaroo +Kettle +Kitchen & dining room table +Kitchen appliance +Kitchen knife +Kitchen utensil +Kite +Knife +Koala +Ladder +Ladle +Ladybug +Lamp +Lantern +Laptop +Lavender (Plant) +Lemon (plant) +Leopard +Light bulb +Light switch +Lighthouse +Lily +Limousine +Lion +Lipstick +Lizard +Lobster +Loveseat +Luggage and bags +Lynx +Magpie +Man +Mango +Maple +Maraca +Measuring cup +Mechanical fan +Medical equipment +Microphone +Microwave oven +Milk +Miniskirt +Mirror +Missile +Mixer +Mixing bowl +Mobile phone +Monkey +Moths and butterflies +Motorcycle +Mouse +Muffin +Mug +Mule +Mushroom +Musical instrument +Musical keyboard +Nail (Construction) +Necklace +Nightstand +Oboe +Office building +Orange (fruit) +Organ (Musical Instrument) +Ostrich +Otter +Oven +Owl +Oyster +Paddle +Palm tree +Pancake +Panda +Paper cutter +Paper towel +Parachute +Parking meter +Parrot +Pasta +Pastry +Peach +Pear +Pen +Pencil case +Pencil sharpener +Penguin +Perfume +Person +Personal flotation device +Piano +Picnic basket +Picture frame +Pig +Pillow +Pineapple +Pitcher (Container) +Pizza +Pizza cutter +Plastic bag +Plate +Platter +Polar bear +Pomegranate +Popcorn +Porch +Porcupine +Poster +Potato +Power plugs and sockets +Pressure cooker +Pretzel +Printer +Pumpkin +Punching bag +Rabbit +Raccoon +Racket +Radish +Ratchet (Device) +Raven +Rays and skates +Red panda +Refrigerator +Remote control +Reptile +Rhinoceros +Rifle +Ring binder +Rocket +Roller skates +Rose +Rugby ball +Ruler +Salad +Salt and pepper shakers +Sandal +Sandwich +Saucer +Saxophone +Scale +Scarf +Scissors +Scoreboard +Scorpion +Screwdriver +Sculpture +Sea lion +Sea turtle +Seafood +Seahorse +Segway +Serving tray +Sewing machine +Shark +Sheep +Shelf +Shellfish +Shirt +Shorts +Shotgun +Shower +Shrimp +Sink +Skateboard +Ski +Skirt +Skull +Skunk +Skyscraper +Slow cooker +Snack +Snail +Snake +Snowboard +Snowman +Snowmobile +Snowplow +Soap dispenser +Sock +Sofa bed +Sombrero +Sparrow +Spatula +Spice rack +Spider +Spoon +Sports uniform +Squash (Plant) +Squid +Squirrel +Stairs +Stapler +Starfish +Stationary bicycle +Stethoscope +Stool +Stop sign +Strawberry +Street light +Stretcher +Studio couch +Submarine +Submarine sandwich +Suit +Suitcase +Sun hat +Sunglasses +Surfboard +Sushi +Swan +Swim cap +Swimming pool +Swimwear +Sword +Syringe +Table +Table tennis racket +Tablet computer +Tableware +Taco +Tank +Tap +Tart +Taxi +Tea +Teapot +Teddy bear +Telephone +Television +Tennis ball +Tennis racket +Tent +Tiara +Tick +Tie +Tiger +Tin can +Toaster +Toilet +Toilet paper +Tomato +Toothbrush +Torch +Tortoise +Towel +Tower +Toy +Traffic light +Traffic sign +Train +Training bench +Treadmill +Tree +Tree house +Tripod +Trombone +Trousers +Truck +Trumpet +Turkey +Turtle +Umbrella +Unicycle +Van +Vase +Vegetable +Violin +Volleyball (Ball) +Waffle +Waffle iron +Wall clock +Wardrobe +Washing machine +Waste container +Watch +Watermelon +Weapon +Whale +Wheelchair +Whisk +Whiteboard +Willow +Window +Window blind +Wine +Wine glass +Wine rack +Winter melon +Wok +Woman +Wood-burning stove +Woodpecker +Worm +Wrench +Zebra +Zucchini +``` +
+::: + +You need to define the following config variables to enable object classification: + +* [`IMGPROXY_CLASSIFICATION_NET`]: a path to the classification neural network model in ONNX format +* [`IMGPROXY_CLASSIFICATION_CLASSES`]: a path to the [class names file](#class-names-file) +* [`IMGPROXY_CLASSIFICATION_NET_SIZE`]: the size of the neural network input. The width and the heights of the inputs should be the same, so this config value should be a single number. Default: 224 +* [`IMGPROXY_CLASSIFICATION_THRESHOLD`]: classifications with confidence below this value will be discarded. Default: 0.5 +* [`IMGPROXY_CLASSIFICATION_NORMALIZATION`]: the normalization type to apply to the input image. Possible values: + * `none`: no normalization + * `half`: normalize to [0, 1] range + * `full`: normalize to [-1, 1] range + * `imagenet`: normalize using ImageNet mean and standard deviation + + Default: `none` + +* [`IMGPROXY_CLASSIFICATION_LAYOUT`]: the data layout of the neural network input. Possible values: + * `nchw`: channels first (PyTorch default) + * `nhwc`: channels last (TensorFlow default) + + Default: `nhwc` + +### Class names file + +The class names file maps the neural network's class indexes to human-readable class names. The path to the class names file should be defined in the `IMGPROXY_CLASSIFICATION_CLASSES` config variable. + +The class names file should contain one class name per line. The class names should match the order of the classes in the neural network output. Example: + +```text +person +bicycle +car +``` + +## Getting classification info + +Object classification is available via the info handler using the `co` (classify objects) endpoint. Fetch classification results by specifying the number of top classes to return: + +```imgproxy_url +.../info/cl:5/... +``` + +Where `5` is the number of top classes to return. + +The response is an array of objects, each containing: + +* `class_id`: The numeric ID of the class +* `name`: The class name from the class names file +* `confidence`: The confidence score for this classification + +See the [getting info documentation](../usage/getting_info.mdx#classify-objects) for more details. diff --git a/docs/features/object_classification.mdx b/docs/features/object_classification.mdx deleted file mode 100644 index 9f8c482..0000000 --- a/docs/features/object_classification.mdx +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Object classification -description: Learn about how to classify objects in your images with imgproxy ---- - -# Object classification ((pro)) - -imgproxy Pro can classify objects in images, providing detailed information about each object. This feature extends [object detection](object_detection.mdx) by not only detecting objects but also identifying their specific classes or categories. - -:::info -Object classification requires [object detection](object_detection.mdx) to be configured and enabled. Classification is performed on the objects detected by the object detection model. -::: - -You can use object classification for content moderation, image organization, and automatic tagging. You can fetch information about the classified objects via the info handler. - -## Configuration - -:::tip -If you're using an imgproxy Pro Docker image with a tag suffixed with `-ml`, a basic classification model is included. For advanced classification, you may want to configure your own model. -::: - -You need to define the following config variables to enable object classification: - -* [`IMGPROXY_OBJECT_CLASSIFY_NET`]: a path to the classification neural network model in ONNX format -* [`IMGPROXY_OBJECT_CLASSIFY_CLASSES`]: a path to the [class names file](#class-names-file) -* [`IMGPROXY_OBJECT_CLASSIFY_NET_SIZE`]: the size of the neural network input. The width and the heights of the inputs should be the same, so this config value should be a single number. Default: 224 -* [`IMGPROXY_OBJECT_CLASSIFY_THRESHOLD`]: classifications with confidence below this value will be discarded. Default: 0.5 -* [`IMGPROXY_OBJECT_CLASSIFY_NORMALIZATION`]: the normalization type to apply to the input image. Possible values: - * `none`: no normalization - * `half`: normalize to [-0.5, 0.5] range - * `full`: normalize to [-1, 1] range - * `imagenet`: normalize using ImageNet mean and standard deviation - - Default: `none` -* [`IMGPROXY_OBJECT_CLASSIFY_LAYOUT`]: the data layout of the neural network input. Possible values: - * `nchw`: channels first (default) - * `nhwc`: channels last - - Default: `nchw` - -### Class names file - -The class names file maps the neural network's class indexes to human-readable class names. The path to the class names file should be defined in the `IMGPROXY_OBJECT_CLASSIFY_CLASSES` config variable. - -The class names file should contain one class name per line. The class names should match the order of the classes in the neural network output. Example: - -```text -person -bicycle -car -``` - -## Getting classification info - -Object classification is available via the info handler using the `co` (classify objects) endpoint. Fetch classification results by specifying the number of top classes to return: - -```imgproxy_url -.../info/co:5/... -``` - -Where `5` is the number of top classes to return. - -The response is an array of objects, each containing: - -* `class_id`: The numeric ID of the class -* `name`: The class name from the class names file -* `confidence`: The confidence score for this classification - -See the [getting info documentation](../usage/getting_info.mdx#classify-objects) for more details. diff --git a/docs/image_formats_support.mdx b/docs/image_formats_support.mdx index b7bf00b..23b2351 100644 --- a/docs/image_formats_support.mdx +++ b/docs/image_formats_support.mdx @@ -100,7 +100,7 @@ The bit depth handling depends on the [IMGPROXY_PRESERVE_HDR](configuration/opti **When `IMGPROXY_PRESERVE_HDR` is enabled:** -* High bit images remain high bit in the output (eg, GRAYSCALE16 remains GRAYSCALE16, scRGB remains scRGB) +* High bit images remain high bit in the output (eg, GRAYSCALE16 remains GRAYSCALE16, RGB16 stays RGB16, scRGB becomes RGB16) **When `IMGPROXY_PRESERVE_HDR` is disabled (default):** diff --git a/docs/monitoring/new_relic.mdx b/docs/monitoring/new_relic.mdx index a8f3eb7..f406fc8 100644 --- a/docs/monitoring/new_relic.mdx +++ b/docs/monitoring/new_relic.mdx @@ -23,13 +23,15 @@ imgproxy will send the following info to New Relic: Additionally, imgproxy sends the following metrics over [Metrics API](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/) as timescales: -* `Custom/imgproxy/workers`: the configured number of imgproxy workers -* `Custom/imgproxy/requests_in_progress`: the number of requests currently in progress -* `Custom/imgproxy/images_in_progress`: the number of images currently in progress -* `Custom/imgproxy/workers_utilization`: the percentage of imgproxy's workers utilization. Calculated as `Custom/imgproxy/requests_in_progress / Custom/imgproxy/workers * 100` -* `Custom/imgproxy/buffer/size`: a summary of the download buffers sizes (in bytes) -* `Custom/imgproxy/buffer/default_size`: calibrated default buffer size (in bytes) -* `Custom/imgproxy/buffer/max_size`: calibrated maximum buffer size (in bytes) -* `Custom/imgproxy/vips/memory`: libvips memory usage (in bytes) -* `Custom/imgproxy/vips/max_memory`: libvips maximum memory usage (in bytes) -* `Custom/imgproxy/vips/allocs`: the number of active vips allocations +* `workers`: the configured number of imgproxy workers +* `requests_in_progress`: the number of requests currently in progress +* `images_in_progress`: the number of images currently in progress +* `workers_utilization`: the percentage of imgproxy's workers utilization. Calculated as `Custom/imgproxy/requests_in_progress / Custom/imgproxy/workers * 100` +* `buffer/size`: a summary of the download buffers sizes (in bytes) +* `buffer/default_size`: calibrated default buffer size (in bytes) +* `buffer/max_size`: calibrated maximum buffer size (in bytes) +* `vips/memory`: libvips memory usage (in bytes) +* `vips/max_memory`: libvips maximum memory usage (in bytes) +* `vips/allocs`: the number of active vips allocations + +All metrics names are prefixed with `Custom/imgproxy/`. diff --git a/docs/monitoring/open_telemetry.mdx b/docs/monitoring/open_telemetry.mdx index b91281d..ab349d4 100644 --- a/docs/monitoring/open_telemetry.mdx +++ b/docs/monitoring/open_telemetry.mdx @@ -72,7 +72,6 @@ imgproxy supports the standard [general](https://opentelemetry.io/docs/languages Also, imgproxy supports the following environment variables: -* `IMGPROXY_OPEN_TELEMETRY_ENABLE_LOGS`: when `true`, imgproxy will send logs to OpenTelemetry collector. Default: `false` * `IMGPROXY_OPEN_TELEMETRY_PROPAGATE_EXTERNAL`: when `true`, imgproxy will propagate OpenTelemetry tracing headers to external requests such as image downloads. Default: `false` * `IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR`: the desired trace ID generator. Supported values are: * `xray`: _(default)_ Amazon X-Ray compatible trace ID generator diff --git a/docs/usage/getting_info.mdx b/docs/usage/getting_info.mdx index df54ee8..2541915 100644 --- a/docs/usage/getting_info.mdx +++ b/docs/usage/getting_info.mdx @@ -303,18 +303,20 @@ Default: `false`. } ``` -### Classify objects {#classify-objects} +### Classification {#classification} :::slow[Slow] This option requires the image to be fully downloaded and processed. ::: ```imgproxy_url_option -classify_objects:%top_k -co:%top_k +classify:%top_k:%class_name1:%class_name2..%class_nameN +cl:%top_k:%class_name1:%class_name2..%class_nameN ``` -When `top_k` is greater than zero, imgproxy will classify the image and return the top K classes with the highest confidence scores. Read the [object classification](../features/object_classification.mdx) manual to learn how to configure object classification. +When `top_k` is greater than zero, imgproxy will classify the image and return the top K classes with the highest confidence scores. Read the [classification](../features/classification.mdx) manual to learn how to configure classification. + +Providing class names is optional. If specified, imgproxy will classify only those classes. Default: `0`. @@ -652,6 +654,8 @@ When set, imgproxy will calculate and return the perceptual hash of the image. P } ``` +Use [Hamming Distance](https://en.wikipedia.org/wiki/Hamming_distance) to calculate the distance between two perceptual hashes. In a nutshell, the Hamming distance is the number of positions at which the corresponding bits of the two hashes differ. + ### Calc hashsums :::slow[Slow] diff --git a/docs/usage/processing.mdx b/docs/usage/processing.mdx index b8796f7..e179817 100644 --- a/docs/usage/processing.mdx +++ b/docs/usage/processing.mdx @@ -596,8 +596,12 @@ imgproxy [detects objects](../features/object_detection.mdx) of the provided cla This option is useful when you want to automatically extract the area containing specific objects from an image, such as all faces in a group photo or products in a catalog image. +It respects the [`resizing_type`](#resizing-type) option, so if you set it to `fill` or `fill-down`, imgproxy will expand the cropping area to match the output dimensions’ aspect ratio. + +It also respects [`IMGPROXY_OBJECT_DETECTION_GRAVITY_MODE`](../configuration/options.mdx#IMGPROXY_OBJECT_DETECTION_GRAVITY_MODE) config option when selecting objects to crop around, and the [`objects_position`](#objects-position) option when deciding where to place the objects in the output image. + :::info -When no objects are detected, imgproxy will not crop the image and will process it as usual. +When no objects are detected, imgproxy will not crop the image and will process it as usual. `crop_objects` option takes precedence over `crop`. ::: ### Colorize ((pro)) {#colorize} diff --git a/sidebars.ts b/sidebars.ts index b15cb61..e370de1 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -62,7 +62,7 @@ const sidebars: SidebarsConfig = { }, { type: "doc", - id: "features/object_classification", + id: "features/classification", className: "menu__list-item--badge badge--pro", }, { @@ -102,8 +102,8 @@ const sidebars: SidebarsConfig = { type: "category", label: "Cache", link: { - type: "doc", - id: "features/cache", + type: "generated-index", + description: "Learn about how to configure cache in imgproxy", }, items: [ { diff --git a/src/css/badge.css b/src/css/badge.css index d5277bf..79df86d 100644 --- a/src/css/badge.css +++ b/src/css/badge.css @@ -69,12 +69,12 @@ a.badge--pro:hover { text-decoration: none; } -.menu__list-item--badge a::after { +.menu__list-item--badge .menu__link::after { top: 0; margin-left: auto; } -.menu__list-item.badge--pro a::after { +.menu__list-item.badge--pro .menu__link::after { content: "pro"; } From 3d65af03758258fb9ab4ad333a141eb47d26e9b7 Mon Sep 17 00:00:00 2001 From: Viktor Sokolov Date: Tue, 7 Apr 2026 15:38:07 +0200 Subject: [PATCH 4/7] Various fixes, addressed PR comments --- docs/cache/external.mdx | 10 +++++----- docs/cache/internal.mdx | 2 +- docs/cache/internal/amazon_s3.mdx | 2 +- docs/cache/internal/azure_blob_storage.mdx | 2 +- docs/cache/internal/google_cloud_storage.mdx | 2 +- docs/cache/internal/local_filesystem.mdx | 2 +- docs/cache/internal/openstack_swift.mdx | 2 +- docs/configuration/options.mdx | 6 +++--- docs/features/classification.mdx | 6 +++--- docs/image_formats_support.mdx | 2 +- docs/monitoring/new_relic.mdx | 6 ++---- 11 files changed, 20 insertions(+), 22 deletions(-) diff --git a/docs/cache/external.mdx b/docs/cache/external.mdx index 5baaaf0..4bd3f72 100644 --- a/docs/cache/external.mdx +++ b/docs/cache/external.mdx @@ -14,7 +14,7 @@ Most major CDNs (Cloudflare, Fastly, AWS CloudFront, Akamai, etc.) can cache img * **Image optimization** - Disable CDN image optimization to avoid double-processing * **Compression** - In case your CDN supports conditional compression of SVG images, enable gzip/Brotli compression for bandwidth savings -* **Include essential headers*** - It's strongly recommended to include `Accept` header in the cache key. If you have client hints enabled, include also `DPR`, `Sec-CH-Dpr`, and `Sec-CH-Width` headers. +* **Include essential headers*** - Include `Accept` header in the cache key if you're using [format negotiation](../configuration/options.mdx#avifwebpjpeg-xl-support-detection). If you have client hints enabled, include also `DPR`, `Sec-CH-Dpr`, and `Sec-CH-Width` headers. * **Origin shield** - Add a secondary cache layer between your CDN and imgproxy origin if your CDN supports it. ## nginx caching @@ -79,7 +79,7 @@ proxy_cache_key "$scheme$proxy_host$request_uri"; proxy_cache_key "$scheme$proxy_host$request_uri$http_accept"; ``` -3. Include Client Hints dimensions when width/DPR affects output: +3. Include [Client Hints](../configuration/options.mdx#client-hints-support) dimensions when width/DPR affects output: ```nginx proxy_cache_key "$scheme$request_method$host$request_uri:accept=$http_accept:dpr=$http_dpr:width=$http_width:chdpr=$http_sec_ch_dpr:chwidth=$http_sec_ch_width"; @@ -89,7 +89,7 @@ Use the smallest key that still prevents collisions for your traffic profile. ### Key recommendations -* Include `Accept` in the cache key if format negotiation is used. +* Include `Accept` in the cache key if [format negotiation](../configuration/options.mdx#avifwebpjpeg-xl-support-detection) is used. * Include DPR/width-related hints in the cache key if [Client Hints](../configuration/options.mdx#client-hints-support) are used to vary output. * Set long `inactive` timeout (30d) to keep popular images in cache. * Configure `proxy_cache_use_stale` for graceful degradation during origin issues. @@ -200,8 +200,8 @@ sub vcl_deliver { ### Key recommendations * Use `sub vcl_hash` to customize cache key behavior. -* Include `Accept` for format negotiation. -* Include DPR/width-related headers when they can affect output (`DPR`, `Width`, `Sec-CH-DPR`, `Sec-CH-Width`). +* Include `Accept` for [format negotiation](../configuration/options.mdx#avifwebpjpeg-xl-support-detection). +* Include DPR/width-related headers when [Client Hints](../configuration/options.mdx#client-hints-support) support is enabled (`DPR`, `Width`, `Sec-CH-DPR`, `Sec-CH-Width`). * Set grace period (`beresp.grace`) for graceful error handling. * Monitor Varnish statistics with `varnishstat`. * Use tags for efficient cache purging: add `set beresp.http.Surrogate-Key = "images:product:123"` in `vcl_backend_response`. diff --git a/docs/cache/internal.mdx b/docs/cache/internal.mdx index cb2a8b7..2c9ab15 100644 --- a/docs/cache/internal.mdx +++ b/docs/cache/internal.mdx @@ -13,7 +13,7 @@ While putting a CDN in front of imgproxy is and will always be a best practice, ## Why use internal cache? -The internal cache provides long-term persistent storage for processed images, unlike CDNs which typically delete rarely accessed content. It stores images in a single location rather than across multiple edge stores, eliminating cache misses when requests hit different edges. The cache is designed specifically for imgproxy, working seamlessly with features like modern image format detection and client hints support that generic external caches don't understand. +The internal cache provides long-term persistent storage for processed images, unlike CDNs, which typically delete rarely accessed content. It stores images in a single location rather than across multiple edge stores, eliminating cache misses when requests hit different edges. The cache is designed specifically for imgproxy, working seamlessly with features like modern image format detection and client hints support that generic external caches don't understand by default. The cache is protected by the same security measures as imgproxy itself, including URL signatures and processing restrictions. Importantly, URL signatures are not part of the cache key, so you can rotate keys or use multiple key/salt pairs without invalidating cached images. You maintain full control over where the cache is stored and how it integrates with your infrastructure. diff --git a/docs/cache/internal/amazon_s3.mdx b/docs/cache/internal/amazon_s3.mdx index 427ed73..ab64af7 100644 --- a/docs/cache/internal/amazon_s3.mdx +++ b/docs/cache/internal/amazon_s3.mdx @@ -2,7 +2,7 @@ description: Learn about how to configure Amazon S3 cache in imgproxy --- -# Cache storage: Amazon S3 +# Internal cache: Amazon S3 imgproxy can store cached images in Amazon S3 buckets or S3-compatible storage. To use S3 cache, do the following: diff --git a/docs/cache/internal/azure_blob_storage.mdx b/docs/cache/internal/azure_blob_storage.mdx index 15b75ab..dd40c08 100644 --- a/docs/cache/internal/azure_blob_storage.mdx +++ b/docs/cache/internal/azure_blob_storage.mdx @@ -2,7 +2,7 @@ description: Learn about how to configure Azure Blob Storage cache in imgproxy --- -# Cache storage: Azure Blob Storage +# Internal cache: Azure Blob Storage imgproxy can store cached images in Azure Blob Storage containers. To use Azure cache, do the following: diff --git a/docs/cache/internal/google_cloud_storage.mdx b/docs/cache/internal/google_cloud_storage.mdx index e985d8a..12215ee 100644 --- a/docs/cache/internal/google_cloud_storage.mdx +++ b/docs/cache/internal/google_cloud_storage.mdx @@ -2,7 +2,7 @@ description: Learn about how to configure Google Cloud Storage cache in imgproxy --- -# Cache storage: Google Cloud Storage +# Internal cache: Google Cloud Storage imgproxy can store cached images in Google Cloud Storage buckets. To use the GCS cache, do the following: diff --git a/docs/cache/internal/local_filesystem.mdx b/docs/cache/internal/local_filesystem.mdx index b7e808b..b044e99 100644 --- a/docs/cache/internal/local_filesystem.mdx +++ b/docs/cache/internal/local_filesystem.mdx @@ -2,7 +2,7 @@ description: Learn about how to configure the local filesystem cache in imgproxy --- -# Cache storage: Local filesystem +# Internal cache: Local filesystem imgproxy can store cached images on the local filesystem. To use filesystem cache, do the following: diff --git a/docs/cache/internal/openstack_swift.mdx b/docs/cache/internal/openstack_swift.mdx index 049fa89..7b2001b 100644 --- a/docs/cache/internal/openstack_swift.mdx +++ b/docs/cache/internal/openstack_swift.mdx @@ -2,7 +2,7 @@ description: Learn about how to configure OpenStack Object Storage cache in imgproxy --- -# Cache storage: OpenStack Object Storage ("Swift") +# Internal cache: OpenStack Object Storage ("Swift") imgproxy can store cached images in OpenStack Object Storage, also known as Swift. To use Swift cache, do the following: diff --git a/docs/configuration/options.mdx b/docs/configuration/options.mdx index 12f8533..bae8600 100644 --- a/docs/configuration/options.mdx +++ b/docs/configuration/options.mdx @@ -48,7 +48,7 @@ echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n') * [`IMGPROXY_PATH_PREFIX`]: the URL path prefix. Example: when set to `/abc/def`, the imgproxy URL will be `/abc/def/%signature/%processing_options/%source_url`. Default: blank * [`IMGPROXY_USER_AGENT`]: the User-Agent header that will be sent with the source image request. You can use the `%current_version` variable to insert the current imgproxy version. Default: `imgproxy/%current_version` * [`IMGPROXY_USE_ETAG`]: when set to `true`, enables using the [ETag](https://en.wikipedia.org/wiki/HTTP_ETag) HTTP header for HTTP cache control. Default: `false` -* [`IMGPROXY_ETAG_BUSTER`]: a global ETag buster value. Change this value if you update configuration that affects image processing, to invalidate old ETags and avoid `304 Not Modified` responses from stale client/CDN validators. Default: blank +* [`IMGPROXY_ETAG_BUSTER`]: a global ETag buster value. Change this value if you update the configuration that affects image processing, to invalidate old ETags and avoid `304 Not Modified` responses from stale client/CDN validators. Default: blank * [`IMGPROXY_USE_LAST_MODIFIED`]: when set to `true`, enables using the [Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) HTTP header for HTTP cache control. Default: `false` * [`IMGPROXY_LAST_MODIFIED_BUSTER`]: a global `Last-Modified` buster timestamp in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html) format. By setting it to a specific datetime, you can make imgproxy treat all the images as if they were modified at least at that datetime. Default: blank * [`IMGPROXY_CUSTOM_REQUEST_HEADERS`]: ((pro)) list of custom headers that imgproxy will send while requesting the source image, divided by `\;` (can be redefined by `IMGPROXY_CUSTOM_HEADERS_SEPARATOR`). Example: `X-MyHeader1=Lorem\;X-MyHeader2=Ipsum` @@ -435,8 +435,8 @@ imgproxy can classify images by assigning them to predefined categories based on * `full`: normalize to [-1, 1] range * `imagenet`: normalize using ImageNet mean and standard deviation * [`IMGPROXY_CLASSIFICATION_LAYOUT`]: ((pro)) the data layout of the neural network input. Possible values are: - * `nchw`: channels first (PyTorch default) * `nhwc`: _(default)_ channels last (TensorFlow default) + * `nchw`: channels first (PyTorch default) Read the [Classification guide](../features/classification.mdx) for more info. @@ -726,7 +726,7 @@ Check out the [CloudWatch](../monitoring/cloud_watch.mdx) guide to learn more. imgproxy can report occurred errors to Bugsnag, Honeybadger and Sentry: * [`IMGPROXY_REPORT_DOWNLOADING_ERRORS`]: when `true`, imgproxy will report downloading errors. Default: `true` -* [`IMGPROXY_DEVELOPMENT_ERRORS_MODE`]: when `true`, imgproxy will respond with detailed error messages and stack traces in a pretty HTML format. Useful for development and debugging. Default: `false` +* [`IMGPROXY_DEVELOPMENT_ERRORS_MODE`]: when `true`, imgproxy will respond with detailed error messages and stack traces in a pretty HTML format. Useful for development and debugging. If the client does not `Accept: text/html`, imgproxy reponds with plain text error. Default: `false` ### Bugsnag diff --git a/docs/features/classification.mdx b/docs/features/classification.mdx index 14277d7..3d7c36c 100644 --- a/docs/features/classification.mdx +++ b/docs/features/classification.mdx @@ -5,7 +5,7 @@ description: Learn about how to classify objects in your images with imgproxy # Classification ((pro)) -imgproxy can classify images by assigning them to predefined categories based on the overall content of the image. Unlike object detection, which answers “Where is a cat in this image?”, image classification answers “Is there a cat in this image?” by labeling the entire image as a whole. +imgproxy can classify images by assigning them to predefined categories based on the overall content of the image. Unlike [object detection](object_detection.mdx), which answers “Where is a cat in this image?”, image classification answers “Is there a cat in this image?” by labeling the entire image as a whole. Specialized image classification models are typically faster and simpler than object detection because they do not need to locate objects within the image. They can also classify images based on broader concepts such as scenes, activities, or safety categories (e.g., NSFW vs. SFW), and require only labeled images for training instead of annotated bounding boxes. @@ -596,8 +596,8 @@ You need to define the following config variables to enable object classificatio Default: `none` * [`IMGPROXY_CLASSIFICATION_LAYOUT`]: the data layout of the neural network input. Possible values: - * `nchw`: channels first (PyTorch default) * `nhwc`: channels last (TensorFlow default) + * `nchw`: channels first (PyTorch default) Default: `nhwc` @@ -615,7 +615,7 @@ car ## Getting classification info -Object classification is available via the info handler using the `co` (classify objects) endpoint. Fetch classification results by specifying the number of top classes to return: +Object classification is available via the info handler using the `cl` (classify) endpoint. Fetch classification results by specifying the number of top classes to return: ```imgproxy_url .../info/cl:5/... diff --git a/docs/image_formats_support.mdx b/docs/image_formats_support.mdx index 23b2351..85279e6 100644 --- a/docs/image_formats_support.mdx +++ b/docs/image_formats_support.mdx @@ -104,5 +104,5 @@ The bit depth handling depends on the [IMGPROXY_PRESERVE_HDR](configuration/opti **When `IMGPROXY_PRESERVE_HDR` is disabled (default):** -* High bit images are converted to 8-bit (eg, GRAYSCALE16 becomes GRAYSCALE8, RGB and scRGB become sRGB) +* High bit images are converted to 8-bit (eg, GRAYSCALE16 becomes GRAYSCALE8, RGB, RGB16 and scRGB become sRGB) * 8-bit images remain 8-bit diff --git a/docs/monitoring/new_relic.mdx b/docs/monitoring/new_relic.mdx index f406fc8..b06126d 100644 --- a/docs/monitoring/new_relic.mdx +++ b/docs/monitoring/new_relic.mdx @@ -21,17 +21,15 @@ imgproxy will send the following info to New Relic: * Image processing time * Errors that occurred while downloading and processing an image -Additionally, imgproxy sends the following metrics over [Metrics API](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/) as timescales: +Additionally, imgproxy sends the following metrics over [Metrics API](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/) as timescales (all metric names are prefixed with Custom/imgproxy/): * `workers`: the configured number of imgproxy workers * `requests_in_progress`: the number of requests currently in progress * `images_in_progress`: the number of images currently in progress -* `workers_utilization`: the percentage of imgproxy's workers utilization. Calculated as `Custom/imgproxy/requests_in_progress / Custom/imgproxy/workers * 100` +* `workers_utilization`: the percentage of imgproxy's workers utilization. Calculated as `requests_in_progress / workers * 100` * `buffer/size`: a summary of the download buffers sizes (in bytes) * `buffer/default_size`: calibrated default buffer size (in bytes) * `buffer/max_size`: calibrated maximum buffer size (in bytes) * `vips/memory`: libvips memory usage (in bytes) * `vips/max_memory`: libvips maximum memory usage (in bytes) * `vips/allocs`: the number of active vips allocations - -All metrics names are prefixed with `Custom/imgproxy/`. From 69d06661017d54d852f7eee789cf16b8a6cd96b8 Mon Sep 17 00:00:00 2001 From: Viktor Sokolov Date: Tue, 7 Apr 2026 15:51:52 +0200 Subject: [PATCH 5/7] Minor updates by the comments --- docs/cache/external.mdx | 2 +- docs/cache/internal/amazon_s3.mdx | 2 -- docs/configuration/options.mdx | 2 +- docs/features/classification.mdx | 2 +- docs/image_sources/amazon_s3.mdx | 4 +--- docs/monitoring/new_relic.mdx | 2 +- 6 files changed, 5 insertions(+), 9 deletions(-) diff --git a/docs/cache/external.mdx b/docs/cache/external.mdx index 4bd3f72..ce320ff 100644 --- a/docs/cache/external.mdx +++ b/docs/cache/external.mdx @@ -14,7 +14,7 @@ Most major CDNs (Cloudflare, Fastly, AWS CloudFront, Akamai, etc.) can cache img * **Image optimization** - Disable CDN image optimization to avoid double-processing * **Compression** - In case your CDN supports conditional compression of SVG images, enable gzip/Brotli compression for bandwidth savings -* **Include essential headers*** - Include `Accept` header in the cache key if you're using [format negotiation](../configuration/options.mdx#avifwebpjpeg-xl-support-detection). If you have client hints enabled, include also `DPR`, `Sec-CH-Dpr`, and `Sec-CH-Width` headers. +* **Include essential headers*** - Include `Accept` header in the cache key if you're using [format negotiation](../configuration/options.mdx#avifwebpjpeg-xl-support-detection). If you have [client hints](../configuration/options.mdx#client-hints-support) enabled, include also `DPR`, `Sec-CH-Dpr`, and `Sec-CH-Width` headers. * **Origin shield** - Add a secondary cache layer between your CDN and imgproxy origin if your CDN supports it. ## nginx caching diff --git a/docs/cache/internal/amazon_s3.mdx b/docs/cache/internal/amazon_s3.mdx index ab64af7..ef7ae59 100644 --- a/docs/cache/internal/amazon_s3.mdx +++ b/docs/cache/internal/amazon_s3.mdx @@ -11,8 +11,6 @@ imgproxy can store cached images in Amazon S3 buckets or S3-compatible storage. 3. Specify the cache bucket name with `IMGPROXY_CACHE_BUCKET`. 4. _(optional)_ Specify the AWS region with `IMGPROXY_CACHE_S3_REGION` or `AWS_REGION`. Default: `us-west-1` 5. _(optional)_ Specify the S3 endpoint with `IMGPROXY_CACHE_S3_ENDPOINT`. You can also set `IMGPROXY_CACHE_S3_ENDPOINT_USE_PATH_STYLE=false` to use the virtual host style for the endpoint. -6. _(optional)_ Specify the AWS IAM Role to Assume with `IMGPROXY_CACHE_S3_ASSUME_ROLE_ARN`. -7. _(optional)_ Specify the External ID to pass to the AWS IAM Role when assuming it using `IMGPROXY_CACHE_S3_ASSUME_ROLE_EXTERNAL_ID`. This will have no effect if the assume role ARN is not specified. ### Configuration diff --git a/docs/configuration/options.mdx b/docs/configuration/options.mdx index bae8600..c6c85c6 100644 --- a/docs/configuration/options.mdx +++ b/docs/configuration/options.mdx @@ -50,7 +50,7 @@ echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n') * [`IMGPROXY_USE_ETAG`]: when set to `true`, enables using the [ETag](https://en.wikipedia.org/wiki/HTTP_ETag) HTTP header for HTTP cache control. Default: `false` * [`IMGPROXY_ETAG_BUSTER`]: a global ETag buster value. Change this value if you update the configuration that affects image processing, to invalidate old ETags and avoid `304 Not Modified` responses from stale client/CDN validators. Default: blank * [`IMGPROXY_USE_LAST_MODIFIED`]: when set to `true`, enables using the [Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) HTTP header for HTTP cache control. Default: `false` -* [`IMGPROXY_LAST_MODIFIED_BUSTER`]: a global `Last-Modified` buster timestamp in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html) format. By setting it to a specific datetime, you can make imgproxy treat all the images as if they were modified at least at that datetime. Default: blank +* [`IMGPROXY_LAST_MODIFIED_BUSTER`]: a global `Last-Modified` buster timestamp in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html) format. Change this value if you update the configuration that affects image processing. It will make imgproxy treat all images as if they were modified at least at the specified datetime. Default: blank * [`IMGPROXY_CUSTOM_REQUEST_HEADERS`]: ((pro)) list of custom headers that imgproxy will send while requesting the source image, divided by `\;` (can be redefined by `IMGPROXY_CUSTOM_HEADERS_SEPARATOR`). Example: `X-MyHeader1=Lorem\;X-MyHeader2=Ipsum` * [`IMGPROXY_CUSTOM_RESPONSE_HEADERS`]: ((pro)) a list of custom response headers, separated by `\;` (can be redefined by `IMGPROXY_CUSTOM_HEADERS_SEPARATOR`). Example: `X-MyHeader1=Lorem\;X-MyHeader2=Ipsum` * [`IMGPROXY_CUSTOM_HEADERS_SEPARATOR`]: ((pro)) a string that will be used as a custom header separator. Default: `\;` diff --git a/docs/features/classification.mdx b/docs/features/classification.mdx index 3d7c36c..c776213 100644 --- a/docs/features/classification.mdx +++ b/docs/features/classification.mdx @@ -618,7 +618,7 @@ car Object classification is available via the info handler using the `cl` (classify) endpoint. Fetch classification results by specifying the number of top classes to return: ```imgproxy_url -.../info/cl:5/... +/info/.../cl:5/... ``` Where `5` is the number of top classes to return. diff --git a/docs/image_sources/amazon_s3.mdx b/docs/image_sources/amazon_s3.mdx index 8ca72fa..dad4d3e 100644 --- a/docs/image_sources/amazon_s3.mdx +++ b/docs/image_sources/amazon_s3.mdx @@ -11,9 +11,7 @@ imgproxy can process images from S3 buckets. To use this feature, do the followi 3. _(optional)_ Specify the [AWS region](#choosing-the-aws-region) with `IMGPROXY_S3_REGION` or `AWS_REGION`. Default: `us-west-1` 4. _(optional)_ Specify the S3 endpoint with `IMGPROXY_S3_ENDPOINT`. You can also set `IMGPROXY_S3_ENDPOINT_USE_PATH_STYLE=false` to use the virtual host style for the endpoint. 5. _(optional)_ Set the `IMGPROXY_S3_USE_DECRYPTION_CLIENT` environment variable to `true` if your objects are client-side encrypted. -6. _(optional)_ Specify the AWS IAM Role to Assume with `IMGPROXY_S3_ASSUME_ROLE_ARN`. -7. _(optional)_ Specify the External ID that needs to be passed in along with the AWS IAM Role to Assume with `IMGPROXY_S3_ASSUME_ROLE_EXTERNAL_ID`. This will have no effect if the assume role ARN is not specified. -8. Use `s3://%bucket_name/%file_key` as the source image URL. +6. Use `s3://%bucket_name/%file_key` as the source image URL. If you need to specify the version of the source object, you can use the query string of the source URL: diff --git a/docs/monitoring/new_relic.mdx b/docs/monitoring/new_relic.mdx index b06126d..e9934c4 100644 --- a/docs/monitoring/new_relic.mdx +++ b/docs/monitoring/new_relic.mdx @@ -21,7 +21,7 @@ imgproxy will send the following info to New Relic: * Image processing time * Errors that occurred while downloading and processing an image -Additionally, imgproxy sends the following metrics over [Metrics API](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/) as timescales (all metric names are prefixed with Custom/imgproxy/): +Additionally, imgproxy sends the following metrics over [Metrics API](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/) as timescales (all metric names are prefixed with `Custom/imgproxy/`): * `workers`: the configured number of imgproxy workers * `requests_in_progress`: the number of requests currently in progress From 2c66198146b68ca9f7ca5feb3b919fb5ff8aca30 Mon Sep 17 00:00:00 2001 From: Viktor Sokolov Date: Tue, 7 Apr 2026 16:06:49 +0200 Subject: [PATCH 6/7] Version 4-preview --- docs/configuration/options.mdx | 155 +- docs/features/object_detection.mdx | 36 +- docs/image_formats_support.mdx | 30 +- docs/image_sources/amazon_s3.mdx | 15 +- docs/image_sources/azure_blob_storage.mdx | 11 - docs/image_sources/google_cloud_storage.mdx | 11 - docs/image_sources/openstack_swift.mdx | 11 - docs/monitoring/datadog.mdx | 1 - docs/monitoring/new_relic.mdx | 23 +- docs/monitoring/open_telemetry.mdx | 38 +- docs/monitoring/prometheus.mdx | 8 + docs/usage/getting_info.mdx | 79 - docs/usage/processing.mdx | 22 - docusaurus.config.ts | 7 +- sidebars.ts | 36 - .../about_processing_pipeline.mdx | 20 + .../version-4-preview}/cache/external.mdx | 0 .../version-4-preview}/cache/internal.mdx | 0 .../cache/internal/amazon_s3.mdx | 0 .../cache/internal/azure_blob_storage.mdx | 0 .../cache/internal/google_cloud_storage.mdx | 0 .../cache/internal/local_filesystem.mdx | 0 .../cache/internal/openstack_swift.mdx | 0 .../loading_environment_variables.mdx | 171 +++ .../configuration/options.mdx | 813 ++++++++++ .../features/autoquality.mdx | 139 ++ .../features/best_format.mdx | 29 + .../features/chained_pipelines.mdx | 63 + .../features/classification.mdx | 0 .../features/object_detection.mdx | 341 +++++ .../version-4-preview/features/watermark.mdx | 79 + .../version-4-preview/getting_started.mdx | 34 + .../version-4-preview/healthcheck.mdx | 23 + .../image_formats_support.mdx | 108 ++ .../image_sources/amazon_s3.mdx | 97 ++ .../image_sources/azure_blob_storage.mdx | 63 + .../image_sources/google_cloud_storage.mdx | 49 + .../image_sources/local_files.mdx | 34 + .../image_sources/openstack_swift.mdx | 33 + .../version-4-preview/installation.mdx | 239 +++ versioned_docs/version-4-preview/intro.mdx | 123 ++ .../version-4-preview/memory_usage_tweaks.mdx | 68 + .../monitoring/cloud_watch.mdx | 58 + .../version-4-preview/monitoring/datadog.mdx | 49 + .../monitoring/new_relic.mdx | 35 + .../monitoring/open_telemetry.mdx | 94 ++ .../monitoring/prometheus.mdx | 30 + .../usage/encrypting_source_url.mdx | 109 ++ .../version-4-preview/usage/getting_info.mdx | 841 +++++++++++ .../version-4-preview/usage/presets.mdx | 37 + .../version-4-preview/usage/processing.mdx | 1320 +++++++++++++++++ .../version-4-preview/usage/signing_url.mdx | 76 + .../version-4-preview-sidebars.json | 148 ++ versions.json | 1 + 54 files changed, 5447 insertions(+), 360 deletions(-) create mode 100644 versioned_docs/version-4-preview/about_processing_pipeline.mdx rename {docs => versioned_docs/version-4-preview}/cache/external.mdx (100%) rename {docs => versioned_docs/version-4-preview}/cache/internal.mdx (100%) rename {docs => versioned_docs/version-4-preview}/cache/internal/amazon_s3.mdx (100%) rename {docs => versioned_docs/version-4-preview}/cache/internal/azure_blob_storage.mdx (100%) rename {docs => versioned_docs/version-4-preview}/cache/internal/google_cloud_storage.mdx (100%) rename {docs => versioned_docs/version-4-preview}/cache/internal/local_filesystem.mdx (100%) rename {docs => versioned_docs/version-4-preview}/cache/internal/openstack_swift.mdx (100%) create mode 100644 versioned_docs/version-4-preview/configuration/loading_environment_variables.mdx create mode 100644 versioned_docs/version-4-preview/configuration/options.mdx create mode 100644 versioned_docs/version-4-preview/features/autoquality.mdx create mode 100644 versioned_docs/version-4-preview/features/best_format.mdx create mode 100644 versioned_docs/version-4-preview/features/chained_pipelines.mdx rename {docs => versioned_docs/version-4-preview}/features/classification.mdx (100%) create mode 100644 versioned_docs/version-4-preview/features/object_detection.mdx create mode 100644 versioned_docs/version-4-preview/features/watermark.mdx create mode 100644 versioned_docs/version-4-preview/getting_started.mdx create mode 100644 versioned_docs/version-4-preview/healthcheck.mdx create mode 100644 versioned_docs/version-4-preview/image_formats_support.mdx create mode 100644 versioned_docs/version-4-preview/image_sources/amazon_s3.mdx create mode 100644 versioned_docs/version-4-preview/image_sources/azure_blob_storage.mdx create mode 100644 versioned_docs/version-4-preview/image_sources/google_cloud_storage.mdx create mode 100644 versioned_docs/version-4-preview/image_sources/local_files.mdx create mode 100644 versioned_docs/version-4-preview/image_sources/openstack_swift.mdx create mode 100644 versioned_docs/version-4-preview/installation.mdx create mode 100644 versioned_docs/version-4-preview/intro.mdx create mode 100644 versioned_docs/version-4-preview/memory_usage_tweaks.mdx create mode 100644 versioned_docs/version-4-preview/monitoring/cloud_watch.mdx create mode 100644 versioned_docs/version-4-preview/monitoring/datadog.mdx create mode 100644 versioned_docs/version-4-preview/monitoring/new_relic.mdx create mode 100644 versioned_docs/version-4-preview/monitoring/open_telemetry.mdx create mode 100644 versioned_docs/version-4-preview/monitoring/prometheus.mdx create mode 100644 versioned_docs/version-4-preview/usage/encrypting_source_url.mdx create mode 100644 versioned_docs/version-4-preview/usage/getting_info.mdx create mode 100644 versioned_docs/version-4-preview/usage/presets.mdx create mode 100644 versioned_docs/version-4-preview/usage/processing.mdx create mode 100644 versioned_docs/version-4-preview/usage/signing_url.mdx create mode 100644 versioned_sidebars/version-4-preview-sidebars.json diff --git a/docs/configuration/options.mdx b/docs/configuration/options.mdx index c6c85c6..b67b41d 100644 --- a/docs/configuration/options.mdx +++ b/docs/configuration/options.mdx @@ -16,6 +16,16 @@ imgproxy allows URLs to be signed with a key and a salt. This feature is disable You can specify multiple key/salt pairs by dividing the keys and salts with a comma (`,`). imgproxy will check URL signatures with each pair. This is useful when you need to change key/salt pairs in your application while incurring zero downtime. +You can also specify file paths using the command line by referencing a separate file containing hex-coded keys and salts line by line: + +```bash +imgproxy -keypath /path/to/file/with/key -saltpath /path/to/file/with/salt +``` + +:::warning +`-keypath` and `-saltpath` command line arguments are deprecated and will be removed in imgproxy v4. Please use `IMGPROXY_KEY` and `IMGPROXY_SALT` environment variables instead. +::: + If you need a random key/salt pair really fast, as an example, you can quickly generate one using the following snippet: ```bash @@ -28,14 +38,14 @@ echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n') * [`IMGPROXY_BIND`]: the address and port or Unix socket to listen to. Default: `:8080` * [`IMGPROXY_NETWORK`]: the network to use. Known networks are `tcp`, `tcp4`, `tcp6`, `unix`, and `unixpacket`. Default: `tcp` -* [`IMGPROXY_TIMEOUT`]: the maximum duration (in seconds) for processing the response. Default: `10` +* [`IMGPROXY_TIMEOUT`]: _(deprecated alias: [`IMGPROXY_WRITE_TIMEOUT`])_ the maximum duration (in seconds) for processing the response. Default: `10` * [`IMGPROXY_GRACEFUL_STOP_TIMEOUT`]: the maximum duration (in seconds) to wait for ongoing requests to finish before shutting down the server. Default: twice the `IMGPROXY_TIMEOUT` value -* [`IMGPROXY_READ_REQUEST_TIMEOUT`]: the maximum duration (in seconds) for reading the entire incoming HTTP request, including the body. Default: `10` +* [`IMGPROXY_READ_REQUEST_TIMEOUT`]: _(deprecated alias: [`IMGPROXY_READ_TIMEOUT`])_ the maximum duration (in seconds) for reading the entire incoming HTTP request, including the body. Default: `10` * [`IMGPROXY_WRITE_RESPONSE_TIMEOUT`]: the maximum duration (in seconds) for writing the HTTP response body. Default: `10` * [`IMGPROXY_KEEP_ALIVE_TIMEOUT`]: the maximum duration (in seconds) to wait for the next request before closing the connection. When set to `0`, keep-alive is disabled. Default: `10` * [`IMGPROXY_CLIENT_KEEP_ALIVE_TIMEOUT`]: the maximum duration (in seconds) to wait for the next request before closing the HTTP client connection. The HTTP client is used to download source images. When set to `0`, keep-alive is disabled. Default: `90` * [`IMGPROXY_DOWNLOAD_TIMEOUT`]: the maximum duration (in seconds) for downloading the source image. Default: `5` -* [`IMGPROXY_WORKERS`]: the maximum number of images an imgproxy instance can process simultaneously without creating a queue. Default: the number of CPU cores multiplied by two +* [`IMGPROXY_WORKERS`]: _(alias: `IMGPROXY_CONCURRENCY`)_ the maximum number of images an imgproxy instance can process simultaneously without creating a queue. Default: the number of CPU cores multiplied by two :::info When running in AWS Lambda, imgproxy automatically sets `IMGPROXY_WORKERS` to `1` since each Lambda instance processes only one request at a time. ::: @@ -48,9 +58,8 @@ echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n') * [`IMGPROXY_PATH_PREFIX`]: the URL path prefix. Example: when set to `/abc/def`, the imgproxy URL will be `/abc/def/%signature/%processing_options/%source_url`. Default: blank * [`IMGPROXY_USER_AGENT`]: the User-Agent header that will be sent with the source image request. You can use the `%current_version` variable to insert the current imgproxy version. Default: `imgproxy/%current_version` * [`IMGPROXY_USE_ETAG`]: when set to `true`, enables using the [ETag](https://en.wikipedia.org/wiki/HTTP_ETag) HTTP header for HTTP cache control. Default: `false` -* [`IMGPROXY_ETAG_BUSTER`]: a global ETag buster value. Change this value if you update the configuration that affects image processing, to invalidate old ETags and avoid `304 Not Modified` responses from stale client/CDN validators. Default: blank +* [`IMGPROXY_ETAG_BUSTER`]: change this to change ETags for all the images. Default: blank * [`IMGPROXY_USE_LAST_MODIFIED`]: when set to `true`, enables using the [Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) HTTP header for HTTP cache control. Default: `false` -* [`IMGPROXY_LAST_MODIFIED_BUSTER`]: a global `Last-Modified` buster timestamp in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html) format. Change this value if you update the configuration that affects image processing. It will make imgproxy treat all images as if they were modified at least at the specified datetime. Default: blank * [`IMGPROXY_CUSTOM_REQUEST_HEADERS`]: ((pro)) list of custom headers that imgproxy will send while requesting the source image, divided by `\;` (can be redefined by `IMGPROXY_CUSTOM_HEADERS_SEPARATOR`). Example: `X-MyHeader1=Lorem\;X-MyHeader2=Ipsum` * [`IMGPROXY_CUSTOM_RESPONSE_HEADERS`]: ((pro)) a list of custom response headers, separated by `\;` (can be redefined by `IMGPROXY_CUSTOM_HEADERS_SEPARATOR`). Example: `X-MyHeader1=Lorem\;X-MyHeader2=Ipsum` * [`IMGPROXY_CUSTOM_HEADERS_SEPARATOR`]: ((pro)) a string that will be used as a custom header separator. Default: `\;` @@ -109,6 +118,10 @@ imgproxy can process animated images (GIF, WebP), but since this operation is pr imgproxy doesn't check the number of chained pipelines used in presets ::: +To check if the source image is SVG, imgproxy reads some amount of bytes; by default it reads a maximum of 32KB. However, you can change this value using the following variable: + +* [`IMGPROXY_MAX_SVG_CHECK_BYTES`]: the maximum number of bytes imgproxy will read to recognize SVG files. If imgproxy is unable to recognize your SVG, try increasing this number. Default: `32768` (32KB) + Requests to some image sources may go through too many redirects or enter an infinite loop. You can limit the number of allowed redirects: * [`IMGPROXY_MAX_REDIRECTS`]: the max number of redirects imgproxy can follow while requesting the source image. When set to `0`, no redirects are allowed. Default: `10` @@ -167,6 +180,8 @@ When using imgproxy in a development environment, it can be useful to ignore SSL Also you may want imgproxy to respond with the same error message that it writes to the log: +* [`IMGPROXY_DEVELOPMENT_ERRORS_MODE`]: when `true`, imgproxy will respond with detailed error messages. Not recommended for production because some errors may contain stack traces. + * [`IMGPROXY_ALLOW_SECURITY_OPTIONS`]: when `true`, allows usage of security-related processing options such as `max_src_resolution`, `max_src_file_size`, `max_animation_frames`, `max_animation_frame_resolution`, and `max_result_dimension`. Default: `false`. :::warning @@ -343,10 +358,6 @@ You can use the `best` value for the [format](../usage/processing.mdx#format) op Check out the [Best format](../features/best_format.mdx) guide to learn more. -## Colorspace and HDR - -* [`IMGPROXY_PRESERVE_HDR`]: when `true`, imgproxy will preserve high bit images. When `false`, imgproxy will convert high bit images to 8-bit. Colorspace (color/grayscale) is always preserved regardless of this setting. See the [Colorspace and HDR preservation](../image_formats_support.mdx#colorspace-and-hdr-preservation) guide for more details. Default: `false` - ## Client Hints support imgproxy can use the `Width` and `DPR` HTTP headers to determine default width and DPR options using Client Hints. This feature is disabled by default and can be enabled by the following option: @@ -406,6 +417,8 @@ imgproxy Pro can apply unsharp masking to your images. imgproxy can detect objects on the image and use them to perform smart cropping, to blur the detections, or to draw the detections. +* [`IMGPROXY_OBJECT_DETECTION_CONFIG`]: ((pro)) the path to the neural network config in DarkNet format. Default: blank +* [`IMGPROXY_OBJECT_DETECTION_WEIGHTS`]: ((pro)) the path to the neural network weights in DarkNet format. Default: blank * [`IMGPROXY_OBJECT_DETECTION_NET`]: ((pro)) a path to the neural network model in ONNX format. Default: blank * [`IMGPROXY_OBJECT_DETECTION_NET_TYPE`]: ((pro)) the type of the neural network model. Default: `yolox` * [`IMGPROXY_OBJECT_DETECTION_CLASSES`]: ((pro)) the path to the text file with the classes names, one per line. Default: blank @@ -421,93 +434,6 @@ imgproxy can detect objects on the image and use them to perform smart cropping, Read the [Object Detection guide](../features/object_detection.mdx) for more info. -## Classification - -imgproxy can classify images by assigning them to predefined categories based on their overall content, similar to object detection but without identifying or locating individual objects. - -* [`IMGPROXY_CLASSIFICATION_NET`]: ((pro)) a path to the classification neural network model in ONNX format. Default: blank -* [`IMGPROXY_CLASSIFICATION_CLASSES`]: ((pro)) the path to the text file with the class names, one per line. Default: blank -* [`IMGPROXY_CLASSIFICATION_NET_SIZE`]: ((pro)) the size of the neural network input. The width and the heights of the inputs should be the same, so this config value should be a single number. Default: 224 -* [`IMGPROXY_CLASSIFICATION_THRESHOLD`]: ((pro)) classifications with confidence below this value will be discarded. Default: 0.5 -* [`IMGPROXY_CLASSIFICATION_NORMALIZATION`]: ((pro)) the normalization type to apply to the input image. Possible values are: - * `none`: _(default)_ no normalization - * `half`: normalize to [0, 1] range - * `full`: normalize to [-1, 1] range - * `imagenet`: normalize using ImageNet mean and standard deviation -* [`IMGPROXY_CLASSIFICATION_LAYOUT`]: ((pro)) the data layout of the neural network input. Possible values are: - * `nhwc`: _(default)_ channels last (TensorFlow default) - * `nchw`: channels first (PyTorch default) - -Read the [Classification guide](../features/classification.mdx) for more info. - -## Cache - -imgproxy can cache processed images in various storage backends to improve performance and reduce processing overhead. - -* [`IMGPROXY_CACHE_USE`]: ((pro)) the cache storage adapter to use. Can be `fs`, `s3`, `gcs`, `abs` (Azure Blob Storage), or `swift` (OpenStack Swift). When blank, the cache is disabled. Default: blank -* [`IMGPROXY_CACHE_PATH_PREFIX`]: ((pro)) a path prefix for the cache files. This can be useful to organize cache files in a specific directory structure. Default: blank -* [`IMGPROXY_CACHE_BUCKET`]: ((pro)) the bucket name for cloud storage adapters (S3, GCS, ABS, OpenStack Swift). When using filesystem adapter, this can be used as an additional path component. Default: blank -* [`IMGPROXY_CACHE_KEY_HEADERS`]: ((pro)) a comma-separated list of HTTP request headers to include in the cache key. This allows caching different versions of the same image based on request headers. Default: blank -* [`IMGPROXY_CACHE_KEY_COOKIES`]: ((pro)) a comma-separated list of HTTP request cookies to include in the cache key. This allows caching different versions of the same image based on cookies. Default: blank -* [`IMGPROXY_CACHE_REPORT_ERRORS`]: ((pro)) when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` - -Read the [Internal cache guide](../cache/internal.mdx) for more info. - -### Local filesystem {#cache-storage-local-filesystem} - -imgproxy can store cached images on the local filesystem. To use [filesystem cache](../cache/internal/local_filesystem.mdx), set `IMGPROXY_CACHE_USE` to `fs`: - -* [`IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT`]: ((pro)) the root directory for filesystem cache. Default: blank - -See full documentation in [Cache storage: Local filesystem](../cache/internal/local_filesystem.mdx). - -### Amazon S3 {#cache-storage-amazon-s3} - -imgproxy can store cached images in Amazon S3 buckets or S3-compatible storage. To use [S3 cache](../cache/internal/amazon_s3.mdx), set `IMGPROXY_CACHE_USE` to `s3`: - -* [`IMGPROXY_CACHE_S3_REGION`]: ((pro)) the S3 region for the cache bucket -* [`IMGPROXY_CACHE_S3_ENDPOINT`]: ((pro)) a custom S3 endpoint for the cache. Useful for S3-compatible services like MinIO, Cloudflare R2, DigitalOcean Spaces, etc. Default: blank -* [`IMGPROXY_CACHE_S3_ENDPOINT_USE_PATH_STYLE`]: ((pro)) controls how the S3 bucket endpoint is constructed. When `true`, the endpoint will be constructed using the path style (`https://your-endpoint.com/%bucket`). When `false`, the endpoint will be constructed using the virtual host style (`https://%bucket.your-endpoint.com`). Default: `true` -* [`IMGPROXY_CACHE_S3_USE_DECRYPTION_CLIENT`]: ((pro)) when `true`, enables client-side decryption for cached objects. Default: `false` -* [`IMGPROXY_CACHE_S3_ASSUME_ROLE_ARN`]: ((pro)) the ARN of an IAM role to assume for cache access -* [`IMGPROXY_CACHE_S3_ASSUME_ROLE_EXTERNAL_ID`]: ((pro)) the external ID required to assume the IAM role for cache access - -:::info -Credentials for S3 cache can be provided using the same methods as for S3 image sources: IAM roles, `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables, or a shared credentials file. -::: - -### Google Cloud Storage {#cache-storage-google-cloud-storage} - -imgproxy can store cached images in Google Cloud Storage buckets. To use [GCS cache](../cache/internal/google_cloud_storage.mdx), set `IMGPROXY_CACHE_USE` to `gcs`: - -* [`IMGPROXY_CACHE_GCS_KEY`]: ((pro)) the Google Cloud JSON key for cache access. When running inside Google Cloud infrastructure, imgproxy will try to use the default service account credentials if this is not set. Default: blank -* [`IMGPROXY_CACHE_GCS_ENDPOINT`]: ((pro)) a custom Google Cloud Storage endpoint for cache. Default: blank - -### Azure Blob Storage {#cache-storage-azure-blob-storage} - -imgproxy can store cached images in Azure Blob Storage containers. To use [Azure cache](../cache/internal/azure_blob_storage.mdx), set `IMGPROXY_CACHE_USE` to `abs`: - -* [`IMGPROXY_CACHE_ABS_NAME`]: ((pro)) the Azure account name for cache storage. Default: blank -* [`IMGPROXY_CACHE_ABS_KEY`]: ((pro)) the Azure account key for cache storage. Default: blank -* [`IMGPROXY_CACHE_ABS_ENDPOINT`]: ((pro)) a custom Azure Blob Storage endpoint for cache. Default: blank - -:::info -Azure cache also supports authentication via Managed Identity or Service Principal using the same `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, and related environment variables as Azure Blob Storage image sources. -::: - -### OpenStack Swift {#cache-storage-openstack-swift} - -imgproxy can store cached images in OpenStack Object Storage (Swift). To use [Swift cache](../cache/internal/openstack_swift.mdx), set `IMGPROXY_CACHE_USE` to `swift`: - -* [`IMGPROXY_CACHE_SWIFT_USERNAME`]: ((pro)) the username for Swift API access for cache. Default: blank -* [`IMGPROXY_CACHE_SWIFT_API_KEY`]: ((pro)) the API key for Swift API access for cache. Default: blank -* [`IMGPROXY_CACHE_SWIFT_AUTH_URL`]: ((pro)) the Swift Auth URL for cache. Default: blank -* [`IMGPROXY_CACHE_SWIFT_AUTH_VERSION`]: ((pro)) the Swift auth version for cache. Set to 1, 2 or 3 or leave at 0 for autodetect. Default: 0 -* [`IMGPROXY_CACHE_SWIFT_TENANT`]: ((pro)) the tenant name for cache (optional, v2 auth only). Default: blank -* [`IMGPROXY_CACHE_SWIFT_DOMAIN`]: ((pro)) the Swift domain name for cache (optional, v3 auth only). Default: blank -* [`IMGPROXY_CACHE_SWIFT_TIMEOUT_SECONDS`]: ((pro)) the data channel timeout in seconds for cache operations. Default: 60 -* [`IMGPROXY_CACHE_SWIFT_CONNECT_TIMEOUT_SECONDS`]: ((pro)) the connect channel timeout in seconds for cache operations. Default: 10 - ## Fallback image You can set up a fallback image that will be used in case imgproxy is unable to fetch the requested one. Use one of the following variables: @@ -555,6 +481,28 @@ There are two ways to define presets: with_objects=detect_objects:1 ``` +#### Using a command line argument + +:::warning +`-presets` and `-info-presets` command line arguments are deprecated and will be removed in imgproxy v4. Please use `IMGPROXY_PRESETS_PATH` and `IMGPROXY_INFO_PRESETS_PATH` environment variables instead. +::: + +```bash +imgproxy -presets /path/to/file/with/presets -info-presets /path/to/file/with/info-presets +``` + +This file should contain preset definitions, one per line. Lines starting with `#` are treated as comments. Example: + +```imgproxy_presets +default=resizing_type:fill/enlarge:1 + +# Sharpen the image to make it look better +sharp=sharpen:0.7 + +# Blur the image to hide details +blurry=blur:2 +``` + ### Using only presets imgproxy can be switched into "presets-only mode". In this mode, imgproxy accepts only `preset` option arguments as processing options. Example: `http://imgproxy.example.com/unsafe/thumbnail:blurry:watermarked/plain/http://example.com/images/curiosity.jpg@png` @@ -589,8 +537,6 @@ imgproxy can process files from Amazon S3 buckets, but this feature is disabled * [`IMGPROXY_S3_USE_DECRYPTION_CLIENT`]: when `true`, enables client-side decryption. Default: `false` * [`IMGPROXY_S3_ASSUME_ROLE_ARN`]: a custom role to assume * [`IMGPROXY_S3_ASSUME_ROLE_EXTERNAL_ID`]: the external ID required to assume a custom role -* [`IMGPROXY_S3_ALLOWED_BUCKETS`]: a comma-separated list of S3 bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed) -* [`IMGPROXY_S3_DENIED_BUCKETS`]: a comma-separated list of S3 bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank Check out the [Serving files from S3](../image_sources/amazon_s3.mdx) guide to learn more. @@ -599,10 +545,8 @@ Check out the [Serving files from S3](../image_sources/amazon_s3.mdx) guide to l imgproxy can process files from Google Cloud Storage buckets, but this feature is disabled by default. To enable it, set the value of `IMGPROXY_USE_GCS` to `true`: * [`IMGPROXY_USE_GCS`]: when `true`, enables image fetching from Google Cloud Storage buckets. Default: `false` -* [`IMGPROXY_GCS_KEY`]: the Google Cloud JSON key. Default: blank +* [`IMGPROXY_GCS_KEY`]: the Google Cloud JSON key. When set, enables image fetching from Google Cloud Storage buckets. Default: blank * [`IMGPROXY_GCS_ENDPOINT`]: a custom Google Cloud Storage endpoint to being used by imgproxy -* [`IMGPROXY_GCS_ALLOWED_BUCKETS`]: a comma-separated list of GCS bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed) -* [`IMGPROXY_GCS_DENIED_BUCKETS`]: a comma-separated list of GCS bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank Check out the [Serving files from Google Cloud Storage](../image_sources/google_cloud_storage.mdx) guide to learn more. @@ -614,8 +558,6 @@ imgproxy can process files from Azure Blob Storage containers, but this feature * [`IMGPROXY_ABS_NAME`]: the Azure account name. Default: blank * [`IMGPROXY_ABS_KEY`]: the Azure account key. Default: blank * [`IMGPROXY_ABS_ENDPOINT`]: the custom Azure Blob Storage endpoint to be used by imgproxy. Default: blank -* [`IMGPROXY_ABS_ALLOWED_BUCKETS`]: a comma-separated list of Azure Blob Storage container names that imgproxy is allowed to access. When set, imgproxy will only process images from these containers. Default: blank (all containers allowed) -* [`IMGPROXY_ABS_DENIED_BUCKETS`]: a comma-separated list of Azure Blob Storage container names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these containers. Default: blank Check out the [Serving files from Azure Blob Storage](../image_sources/azure_blob_storage.mdx) guide to learn more. @@ -631,8 +573,6 @@ imgproxy can process files from OpenStack Object Storage, but this feature is di * [`IMGPROXY_SWIFT_DOMAIN`]: the Swift domain name (optional, v3 auth only): Default: blank * [`IMGRPOXY_SWIFT_TIMEOUT_SECONDS`]: the data channel timeout in seconds. Default: 60 * [`IMGRPOXY_SWIFT_CONNECT_TIMEOUT_SECONDS`]: the connect channel timeout in seconds. Default: 10 -* [`IMGPROXY_SWIFT_ALLOWED_BUCKETS`]: a comma-separated list of Swift container names that imgproxy is allowed to access. When set, imgproxy will only process images from these containers. Default: blank (all containers allowed) -* [`IMGPROXY_SWIFT_DENIED_BUCKETS`]: a comma-separated list of Swift container names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these containers. Default: blank Check out the [Serving files from OpenStack Object Storage](../image_sources/openstack_swift.mdx) guide to learn more. @@ -669,7 +609,6 @@ imgproxy can send its metrics to New Relic. Specify your New Relic license key t * [`IMGPROXY_NEW_RELIC_KEY`]: the New Relic license key * [`IMGPROXY_NEW_RELIC_APP_NAME`]: a New Relic application name. Default: `imgproxy` * [`IMGPROXY_NEW_RELIC_LABELS`]: the list of New Relic labels, semicolon divided. Example: `label1=value1;label2=value2`. Default: blank -* [`IMGPROXY_NEW_RELIC_PROPAGATE_EXTERNAL`]: when `true`, imgproxy will propagate New Relic tracing headers to external requests such as image downloads. Default: `false` Check out the [New Relic](../monitoring/new_relic.mdx) guide to learn more. @@ -688,7 +627,6 @@ imgproxy can send its metrics to Datadog: * [`IMGPROXY_DATADOG_ENABLE`]: when `true`, enables sending metrics to Datadog. Default: false * [`IMGPROXY_DATADOG_ENABLE_ADDITIONAL_METRICS`]: when `true`, enables sending the additional metrics to Datadog. Default: false -* [`IMGPROXY_DATADOG_PROPAGATE_EXTERNAL`]: when `true`, imgproxy will propagate Datadog tracing headers to external requests such as image downloads. Default: `false` :::warning Since the additional metrics are treated by Datadog as custom, Datadog can additionally bill you for their usage. Please, check out Datadog's [Custom Metrics Billing](https://docs.datadoghq.com/account_management/billing/custom_metrics/) page for additional details. @@ -702,12 +640,10 @@ imgproxy can send request traces to an OpenTelemetry collector: * [`IMGPROXY_OPEN_TELEMETRY_ENABLE`]: when `true`, enables sending request traces to OpenTelemetry collector. Default: false * [`IMGPROXY_OPEN_TELEMETRY_ENABLE_METRICS`]: when `true`, imgproxy will send metrics over OpenTelemetry Metrics API. Default: `false` -* [`IMGPROXY_OPEN_TELEMETRY_ENABLE_LOGS`]: when `true`, imgproxy will send logs to OpenTelemetry collector. Default: `false` * [`IMGPROXY_OPEN_TELEMETRY_SERVER_CERT`]: OpenTelemetry collector TLS certificate, PEM-encoded (you can replace line breaks with `\n`). Default: blank * [`IMGPROXY_OPEN_TELEMETRY_CLIENT_CERT`]: OpenTelemetry client TLS certificate, PEM-encoded (you can replace line breaks with `\n`). Default: blank * [`IMGPROXY_OPEN_TELEMETRY_CLIENT_KEY`]: OpenTelemetry client TLS key, PEM-encoded (you can replace line breaks with `\n`). Default: blank * [`IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR`]: OpenTelemetry trace ID generator. Supported generators are `xray` and `random`. Default: `xray` -* [`IMGPROXY_OPEN_TELEMETRY_PROPAGATE_EXTERNAL`]: when `true`, imgproxy will propagate OpenTelemetry tracing headers to external requests such as image downloads. Default: `false` Check out the [OpenTelemetry](../monitoring/open_telemetry.mdx) guide to learn more. @@ -726,7 +662,6 @@ Check out the [CloudWatch](../monitoring/cloud_watch.mdx) guide to learn more. imgproxy can report occurred errors to Bugsnag, Honeybadger and Sentry: * [`IMGPROXY_REPORT_DOWNLOADING_ERRORS`]: when `true`, imgproxy will report downloading errors. Default: `true` -* [`IMGPROXY_DEVELOPMENT_ERRORS_MODE`]: when `true`, imgproxy will respond with detailed error messages and stack traces in a pretty HTML format. Useful for development and debugging. If the client does not `Accept: text/html`, imgproxy reponds with plain text error. Default: `false` ### Bugsnag diff --git a/docs/features/object_detection.mdx b/docs/features/object_detection.mdx index 22818c4..5d10841 100644 --- a/docs/features/object_detection.mdx +++ b/docs/features/object_detection.mdx @@ -5,9 +5,9 @@ description: Learn about how to detect objects in your images and use them with # Object detection ((pro)) -imgproxy can detect objects in the image and use them for smart cropping, blurring the detections, drawing the detections, or cropping to detected objects. You can also [fetch the detected objects info](../usage/getting_info.mdx#detect-objects). +imgproxy can detect objects in the image and use them for smart cropping, blurring the detections, or drawing the detections. You can also [fetch the detected objects info](../usage/getting_info.mdx#detect-objects). -For object purposes, imgproxy uses the YOLO (You Only Look Once) model family. imgproxy supports models in ONNX format. We provide Docker images with a model trained for face detection, but you can use any YOLO model found on the internet or train your own model. +For object purposes, imgproxy uses the YOLO (You Only Look Once) model family. imgproxy supports models in DarkNet or ONNX format. We provide Docker images with a model trained for face detection, but you can use any YOLO model found on the internet or train your own model. ## Configuration @@ -15,6 +15,24 @@ For object purposes, imgproxy uses the YOLO (You Only Look Once) model family. i You don't need to configure object detection if you're using an imgproxy Pro Docker image with a tag suffixed with `-ml` and you want to use the face detection model. The model is already included in the image and the configuration is already set up. ::: +:::info +DarkNet model format has priority over ONNX model format. If you define both, imgproxy will use the DarkNet model. +::: + +### DarkNet model format + +:::warning +DarkNet models support is deprecated and will be removed in imgproxy v4. Please use ONNX models instead. +::: + +You need to define the following config variables to enable object detection with a [DarkNet](https://github.com/AlexeyAB/darknet) model: + +* [`IMGPROXY_OBJECT_DETECTION_CONFIG`]: a path to the neural network config in DarkNet format +* [`IMGPROXY_OBJECT_DETECTION_WEIGHTS`]: a path to the neural network weights in DarkNet format +* [`IMGPROXY_OBJECT_DETECTION_CLASSES`]: a path to the [class names file](#class-names-file) + +### ONNX model format + You need to define the following config variables to enable object detection with an ONNX model: * [`IMGPROXY_OBJECT_DETECTION_NET`]: a path to the neural network model in ONNX format @@ -318,20 +336,6 @@ You can make imgproxy [draw bounding boxes](../usage/processing.mdx#draw-detecti .../draw_detections:1:face/... ``` -### Crop to detected objects - -You can make imgproxy [crop the image](../usage/processing.mdx#crop-objects) to fit all detected objects of the desired classes: - -```imgproxy_url -.../crop_objects:1.2:face:person/... -``` - -This will automatically crop the image to include all detected faces and persons with 20% padding around them. You can omit class names to crop to all detected objects: - -```imgproxy_url -.../co:1.0/... -``` - ### Fetch the detected objects' info You can [fetch the detected objects info](../usage/getting_info.mdx#detect-objects) using the `/info` endpoint: diff --git a/docs/image_formats_support.mdx b/docs/image_formats_support.mdx index 85279e6..7d92ae9 100644 --- a/docs/image_formats_support.mdx +++ b/docs/image_formats_support.mdx @@ -21,7 +21,6 @@ At the moment, imgproxy supports only the most popular image formats: | TIFF | `tiff` | :white_check_mark: | :white_check_mark: | | PDF ((pro)) | `pdf` | :white_check_mark: | [See notes](#pdf-support) | | PSD ((pro)) | `psd` | [See notes](#psd-support) | :x: | -| RAW ((pro)) | | [See notes](#raw-support) | :x: | | MP4 (h264) ((pro)) | `mp4` | [See notes](#video-thumbnails) | :white_check_mark: | | Other video formats ((pro)) | | [See notes](#video-thumbnails) | :x: | @@ -37,6 +36,10 @@ imgproxy supports SVG sources without limitations, but SVG results are not suppo When the source image is SVG and an SVG result is requested, imgproxy returns the source image without modifications. +imgproxy reads some amount of bytes to check if the source image is SVG. By default it reads a maximum of 32KB, but you can change this: + +* `IMGPROXY_MAX_SVG_CHECK_BYTES`: the maximum number of bytes imgproxy will read to recognize SVG. If imgproxy can't recognize your SVG, try to increase this number. Default: `32768` (32KB) + ## Animated images support Since the processing of animated images is a pretty heavy process, only one frame is processed by default. You can increase the maximum of animation frames to process with the following variable: @@ -67,12 +70,6 @@ We tested imgproxy with all variants of PSD/PSB files that we could find or prod We couldn't find any PSD/PSB files with their image data compressed with ZIP, so imgproxy renders them as solid white images. If you had such files, we would very much appreciate it if you could share them with us. ::: -## RAW support ((pro)) {#raw-support} - -RAW image formats from digital cameras are supported as source images only (read-only). RAW files are decoded and converted to standard image formats during processing. - -imgproxy uses [libraw](https://www.libraw.org/) to process RAW files. For a complete list of supported camera models and RAW formats, see the [libraw supported cameras list](https://www.libraw.org/supported-cameras). - ## Converting animated images to MP4 ((pro)) {#converting-animated-images-to-mp4} Animated image results can be converted to MP4 by specifying the `mp4` extension. @@ -87,22 +84,3 @@ Since this still requires more data to be downloaded, video thumbnail generation * `IMGPROXY_ENABLE_VIDEO_THUMBNAILS`: when true, enables video thumbnail generation. Default: `false` * `IMGPROXY_VIDEO_THUMBNAIL_SECOND`: the timestamp of the frame (in seconds) that will be used for the thumbnail. Default: `1`. - -## Colorspace and HDR preservation - -imgproxy always preserves the source image's colorspace: - -* Color images remain color images. -* Grayscale images remain grayscale images. -* Colorspace types are maintained. - -The bit depth handling depends on the [IMGPROXY_PRESERVE_HDR](configuration/options.mdx#IMGPROXY_PRESERVE_HDR) configuration setting: - -**When `IMGPROXY_PRESERVE_HDR` is enabled:** - -* High bit images remain high bit in the output (eg, GRAYSCALE16 remains GRAYSCALE16, RGB16 stays RGB16, scRGB becomes RGB16) - -**When `IMGPROXY_PRESERVE_HDR` is disabled (default):** - -* High bit images are converted to 8-bit (eg, GRAYSCALE16 becomes GRAYSCALE8, RGB, RGB16 and scRGB become sRGB) -* 8-bit images remain 8-bit diff --git a/docs/image_sources/amazon_s3.mdx b/docs/image_sources/amazon_s3.mdx index dad4d3e..6024dbd 100644 --- a/docs/image_sources/amazon_s3.mdx +++ b/docs/image_sources/amazon_s3.mdx @@ -11,7 +11,9 @@ imgproxy can process images from S3 buckets. To use this feature, do the followi 3. _(optional)_ Specify the [AWS region](#choosing-the-aws-region) with `IMGPROXY_S3_REGION` or `AWS_REGION`. Default: `us-west-1` 4. _(optional)_ Specify the S3 endpoint with `IMGPROXY_S3_ENDPOINT`. You can also set `IMGPROXY_S3_ENDPOINT_USE_PATH_STYLE=false` to use the virtual host style for the endpoint. 5. _(optional)_ Set the `IMGPROXY_S3_USE_DECRYPTION_CLIENT` environment variable to `true` if your objects are client-side encrypted. -6. Use `s3://%bucket_name/%file_key` as the source image URL. +6. _(optional)_ Specify the AWS IAM Role to Assume with `IMGPROXY_S3_ASSUME_ROLE_ARN`. +7. _(optional)_ Specify the External ID that needs to be passed in along with the AWS IAM Role to Assume with `IMGPROXY_S3_ASSUME_ROLE_EXTERNAL_ID`. This will have no effect if the assume role ARN is not specified. +8. Use `s3://%bucket_name/%file_key` as the source image URL. If you need to specify the version of the source object, you can use the query string of the source URL: @@ -76,17 +78,6 @@ This allows imgproxy to access buckets in any region. However, the initial reque * If your most frequently used buckets are in the same region, set the region to that one. * If your buckets are spread across multiple regions, set the region to the closest one to your imgproxy instance. -## Restricting bucket access - -Restrict which S3 buckets imgproxy can access for security: - -* `IMGPROXY_S3_ALLOWED_BUCKETS`: a comma-separated list of bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed) -* `IMGPROXY_S3_DENIED_BUCKETS`: a comma-separated list of bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank - -:::tip -Use `IMGPROXY_S3_ALLOWED_BUCKETS` to allow trusted buckets. Use `IMGPROXY_S3_DENIED_BUCKETS` to block specific ones. If both are set, allowed buckets override denied ones. -::: - ## MinIO [MinIO](https://github.com/minio/minio) is an object storage server released under Apache License v2.0. It is compatible with Amazon S3, so it can be used with imgproxy. diff --git a/docs/image_sources/azure_blob_storage.mdx b/docs/image_sources/azure_blob_storage.mdx index 8d01eb9..80ee513 100644 --- a/docs/image_sources/azure_blob_storage.mdx +++ b/docs/image_sources/azure_blob_storage.mdx @@ -50,14 +50,3 @@ For certificate authentication: ### Using Storage Account Key Alternatively, you can set `IMGPROXY_ABS_KEY` to your Azure Blob Storage account key. See the [Manage storage account access keys](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage) guide for more info. - -## Restricting container access - -Restrict which Azure Blob Storage containers imgproxy can access for security: - -* `IMGPROXY_ABS_ALLOWED_BUCKETS`: a comma-separated list of container names that imgproxy is allowed to access. When set, imgproxy will only process images from these containers. Default: blank (all containers allowed) -* `IMGPROXY_ABS_DENIED_BUCKETS`: a comma-separated list of container names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these containers. Default: blank - -:::tip -Use `IMGPROXY_ABS_ALLOWED_BUCKETS` to allow trusted containers. Use `IMGPROXY_ABS_DENIED_BUCKETS` to block specific ones. If both are set, allowed containers override denied ones. -::: diff --git a/docs/image_sources/google_cloud_storage.mdx b/docs/image_sources/google_cloud_storage.mdx index 856a9b5..76cbb62 100644 --- a/docs/image_sources/google_cloud_storage.mdx +++ b/docs/image_sources/google_cloud_storage.mdx @@ -36,14 +36,3 @@ Otherwise, set `IMGPROXY_GCS_KEY` environment variable to the content of Google :::warning For security reasons, imgproxy accepts only service account keys for Google Cloud Storage integration. ::: - -## Restricting bucket access - -Restrict which GCS buckets imgproxy can access for security: - -* `IMGPROXY_GCS_ALLOWED_BUCKETS`: a comma-separated list of bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed) -* `IMGPROXY_GCS_DENIED_BUCKETS`: a comma-separated list of bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank - -:::tip -Use `IMGPROXY_GCS_ALLOWED_BUCKETS` to allow trusted buckets. Use `IMGPROXY_GCS_DENIED_BUCKETS` to block specific ones. If both are set, allowed buckets override denied ones. -::: diff --git a/docs/image_sources/openstack_swift.mdx b/docs/image_sources/openstack_swift.mdx index 016fb14..7900b03 100644 --- a/docs/image_sources/openstack_swift.mdx +++ b/docs/image_sources/openstack_swift.mdx @@ -20,14 +20,3 @@ imgproxy can process images from OpenStack Object Storage, also known as Swift. :::tip If filenames in your OpenStack Object Storage may contain `?`, you may want to set [IMGPROXY_SOURCE_URL_QUERY_SEPARATOR](../configuration/options.mdx#IMGPROXY_SOURCE_URL_QUERY_SEPARATOR) to another string that is not used in filenames or set it to blank to disable query string extraction. ::: - -## Restricting container access - -Restrict which Swift containers imgproxy can access for security: - -* `IMGPROXY_SWIFT_ALLOWED_BUCKETS`: a comma-separated list of container names that imgproxy is allowed to access. When set, imgproxy will only process images from these containers. Default: blank (all containers allowed) -* `IMGPROXY_SWIFT_DENIED_BUCKETS`: a comma-separated list of container names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these containers. Default: blank - -:::tip -Use `IMGPROXY_SWIFT_ALLOWED_BUCKETS` to allow trusted containers. Use `IMGPROXY_SWIFT_DENIED_BUCKETS` to block specific ones. If both are set, allowed containers override denied ones. -::: diff --git a/docs/monitoring/datadog.mdx b/docs/monitoring/datadog.mdx index 48beedd..319672e 100644 --- a/docs/monitoring/datadog.mdx +++ b/docs/monitoring/datadog.mdx @@ -23,7 +23,6 @@ imgproxy can send its metrics to Datadog. To use this feature, do the following: * `DD_TRACE_STARTUP_LOGS`: causes various startup info to be written when the tracer starts. Default: `true` * `DD_TRACE_DEBUG`: enables detailed logs. Default: `false` 4. _(optional)_ Set the `IMGPROXY_DATADOG_ENABLE_ADDITIONAL_METRICS` environment variable to `true` to collect the [additional metrics](#additional-metrics). -5. _(optional)_ Set the `IMGPROXY_DATADOG_PROPAGATE_EXTERNAL` environment variable to `true` to propagate Datadog tracing headers to external requests such as image downloads. Default: `false`. imgproxy will send the following info to Datadog: diff --git a/docs/monitoring/new_relic.mdx b/docs/monitoring/new_relic.mdx index e9934c4..44a9f98 100644 --- a/docs/monitoring/new_relic.mdx +++ b/docs/monitoring/new_relic.mdx @@ -10,7 +10,6 @@ imgproxy can send its metrics to New Relic. To use this feature, do the followin 2. Set the `IMGPROXY_NEW_RELIC_KEY` environment variable to the license key. 3. _(optional)_ Set the `IMGPROXY_NEW_RELIC_APP_NAME` environment variable to be the desired application name. 4. _(optional)_ Set the `IMGPROXY_NEW_RELIC_LABELS` environment variable to be the desired list of labels. Example: `label1=value1;label2=value2`. -5. _(optional)_ Set the `IMGPROXY_NEW_RELIC_PROPAGATE_EXTERNAL` environment variable to `true` to propagate New Relic tracing headers to external requests such as image downloads. Default: `false`. imgproxy will send the following info to New Relic: @@ -21,15 +20,15 @@ imgproxy will send the following info to New Relic: * Image processing time * Errors that occurred while downloading and processing an image -Additionally, imgproxy sends the following metrics over [Metrics API](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/) as timescales (all metric names are prefixed with `Custom/imgproxy/`): +Additionally, imgproxy sends the following metrics over [Metrics API](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/): -* `workers`: the configured number of imgproxy workers -* `requests_in_progress`: the number of requests currently in progress -* `images_in_progress`: the number of images currently in progress -* `workers_utilization`: the percentage of imgproxy's workers utilization. Calculated as `requests_in_progress / workers * 100` -* `buffer/size`: a summary of the download buffers sizes (in bytes) -* `buffer/default_size`: calibrated default buffer size (in bytes) -* `buffer/max_size`: calibrated maximum buffer size (in bytes) -* `vips/memory`: libvips memory usage (in bytes) -* `vips/max_memory`: libvips maximum memory usage (in bytes) -* `vips/allocs`: the number of active vips allocations +* `imgproxy.workers`: the configured number of imgproxy workers +* `imgproxy.requests_in_progress`: the number of requests currently in progress +* `imgproxy.images_in_progress`: the number of images currently in progress +* `imgproxy.workers_utilization`: the percentage of imgproxy's workers utilization. Calculated as `imgproxy.requests_in_progress / imgproxy.workers * 100` +* `imgproxy.buffer.size`: a summary of the download buffers sizes (in bytes) +* `imgproxy.buffer.default_size`: calibrated default buffer size (in bytes) +* `imgproxy.buffer.max_size`: calibrated maximum buffer size (in bytes) +* `imgproxy.vips.memory`: libvips memory usage (in bytes) +* `imgproxy.vips.max_memory`: libvips maximum memory usage (in bytes) +* `imgproxy.vips.allocs`: the number of active vips allocations diff --git a/docs/monitoring/open_telemetry.mdx b/docs/monitoring/open_telemetry.mdx index ab349d4..e2c5542 100644 --- a/docs/monitoring/open_telemetry.mdx +++ b/docs/monitoring/open_telemetry.mdx @@ -9,16 +9,15 @@ imgproxy can send request traces to an OpenTelemetry collector. To use this feat 1. Install & configure the [OpenTelemetry collector](https://opentelemetry.io/docs/collector/). 2. Set the `IMGPROXY_OPEN_TELEMETRY_ENABLE` environment variable to `true` to enable sending request traces to the collector. Default: `false`. 3. _(optional)_ Set the `IMGPROXY_OPEN_TELEMETRY_ENABLE_METRICS` environment variable to `true` to enable sending metrics to the collector. Default: `false`. -4. _(optional)_ Set the `IMGPROXY_OPEN_TELEMETRY_ENABLE_LOGS` environment variable to `true` to enable sending logs to the collector. Default: `false`. -5. _(optional)_ Specify the collector protocol with `OTEL_EXPORTER_OTLP_PROTOCOL` environment variable. +4. _(optional)_ Specify the collector protocol with `OTEL_EXPORTER_OTLP_PROTOCOL` environment variable. :::tip - You can specify different protocols for traces, metrics, and logs by using the `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`, `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL`, and `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` environment variables. + You can specify different protocols for traces and metrics by using the `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` and `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` environment variables. ::: Supported protocols are: * `grpc` _(default)_ * `http/protobuf` (aliases: `http`, `https`) -6. _(optional)_ Specify the collector endpoint with `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable. +5. _(optional)_ Specify the collector endpoint with `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable. :::tip Use `https://` scheme for secure connections (you may need to configure [TLS certificates](#tls-configuration)) and `http://` for insecure connections. ::: @@ -28,18 +27,18 @@ imgproxy can send request traces to an OpenTelemetry collector. To use this feat ::: :::tip - You can specify different endpoints for traces, metrics, and logs by using the `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, and `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` environment variables. If the `http/protobuf` protocol is used, these signal-specific endpoints should include the signal-specific paths like `/v1/traces`, `/v1/metrics`, or `/v1/logs`. + You can specify different endpoints for traces and metrics by using the `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` and `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` environment variables. If the `http/protobuf` protocol is used, these signal-specific endpoints should include the signal-specific paths like `/v1/traces` or `/v1/metrics`. ::: Defaults are: * For the `grpc` protocol: `https://localhost:4317` * For the `http/protobuf` protocol: `https://localhost:4318` -7. _(optional)_ Set the `OTEL_SERVICE_NAME` environment variable to be the desired service name. Default: `imgproxy`. -8. _(optional)_ [Set up TLS certificates](#tls-configuration). -9. _(optional)_ Set the `IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR` environment variable to be the desired trace ID generator. Supported values are: +6. _(optional)_ Set the `OTEL_SERVICE_NAME` environment variable to be the desired service name. Default: `imgproxy`. +7. _(optional)_ [Set up TLS certificates](#tls-configuration). +8. _(optional)_ Set the `IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR` environment variable to be the desired trace ID generator. Supported values are: * `xray`: _(default)_ Amazon X-Ray compatible trace ID generator * `random`: random trace ID generator -10. _(optional)_ Use [OpenTelemetry configuration environment variables](#configuration) to further customize the behavior. +9. _(optional)_ Use [OpenTelemetry configuration environment variables](#configuration) to further customize the behavior. imgproxy will send the following info to the collector: @@ -68,11 +67,11 @@ If `IMGPROXY_OPEN_TELEMETRY_ENABLE_METRICS` is set to `true`, imgproxy will also imgproxy supports the standard [general](https://opentelemetry.io/docs/languages/sdk-configuration/general/) and [OTLP exporter-specific](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/) environment variables with the following specifics: * `http/json` protocol` is not supported. -* `OTEL_TRACES_EXPORTER`, `OTEL_METRICS_EXPORTER`, and `OTEL_LOGS_EXPORTER` environment variables are ignored as imgproxy always uses the OTLP exporter. +* `OTEL_TRACES_EXPORTER` and `OTEL_METRICS_EXPORTER` environment variables are ignored as imgproxy always uses the OTLP exporter. +* Logs-related environment variables are ignored as imgproxy does not support sending logs to OpenTelemetry. Also, imgproxy supports the following environment variables: -* `IMGPROXY_OPEN_TELEMETRY_PROPAGATE_EXTERNAL`: when `true`, imgproxy will propagate OpenTelemetry tracing headers to external requests such as image downloads. Default: `false` * `IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR`: the desired trace ID generator. Supported values are: * `xray`: _(default)_ Amazon X-Ray compatible trace ID generator * `random`: random trace ID generator @@ -92,3 +91,20 @@ If your collector uses mTLS for mutual authentication, you'll also need to speci :::warning If `IMGPROXY_OPEN_TELEMETRY_SERVER_CERT` is set and the `grpc` protocol is used, imgproxy will try to establish a secure connection to the collector even if the collector's endpoint scheme is `http://`. ::: + +## Deprecated Environment Variables + +The following environment variables are deprecated and will be removed in the future: + +* `IMGPROXY_OPEN_TELEMETRY_ENDPOINT`: use `OTEL_EXPORTER_OTLP_ENDPOINT` instead and explicitly enable OpenTelemetry support with `IMGPROXY_OPEN_TELEMETRY_ENABLE` environment variable. + :::warning + Unlike `IMGPROXY_OPEN_TELEMETRY_ENDPOINT`, `OTEL_EXPORTER_OTLP_ENDPOINT` should contain a URL scheme (`http://` or `https://`). + ::: +* `IMGPROXY_OPEN_TELEMETRY_PROTOCOL`: use `OTEL_EXPORTER_OTLP_PROTOCOL` instead. +* `IMGPROXY_OPEN_TELEMETRY_GRPC_INSECURE`: use `OTEL_EXPORTER_OTLP_ENDPOINT` with `http://` scheme instead. +* `IMGPROXY_OPEN_TELEMETRY_SERVICE_NAME`: use `OTEL_SERVICE_NAME` instead. +* `IMGPROXY_OPEN_TELEMETRY_PROPAGATORS`: use `OTEL_PROPAGATORS` instead. +* `IMGPROXY_OPEN_TELEMETRY_CONNECTION_TIMEOUT`: use `OTEL_EXPORTER_OTLP_TIMEOUT` instead. + :::warning + Unlike `IMGPROXY_OPEN_TELEMETRY_CONNECTION_TIMEOUT`, `OTEL_EXPORTER_OTLP_TIMEOUT` should be specified in milliseconds instead of seconds. + ::: diff --git a/docs/monitoring/prometheus.mdx b/docs/monitoring/prometheus.mdx index 103d38c..688dfa5 100644 --- a/docs/monitoring/prometheus.mdx +++ b/docs/monitoring/prometheus.mdx @@ -28,3 +28,11 @@ imgproxy will collect the following metrics: * `vips_max_memory_bytes`: libvips maximum memory usage * `vips_allocs`: the number of active vips allocations * Some useful Go metrics like memstats and goroutines count + +### Deprecated metrics + +The following metrics are deprecated and can be removed in future versions. Use `request_span_duration_seconds` instead. + +* `download_duration_seconds`: a histogram of the source image downloading latency (in seconds) +* `processing_duration_seconds`: a histogram of the image processing latency (in seconds) + diff --git a/docs/usage/getting_info.mdx b/docs/usage/getting_info.mdx index 2541915..3c2c177 100644 --- a/docs/usage/getting_info.mdx +++ b/docs/usage/getting_info.mdx @@ -303,40 +303,6 @@ Default: `false`. } ``` -### Classification {#classification} - -:::slow[Slow] -This option requires the image to be fully downloaded and processed. -::: - -```imgproxy_url_option -classify:%top_k:%class_name1:%class_name2..%class_nameN -cl:%top_k:%class_name1:%class_name2..%class_nameN -``` - -When `top_k` is greater than zero, imgproxy will classify the image and return the top K classes with the highest confidence scores. Read the [classification](../features/classification.mdx) manual to learn how to configure classification. - -Providing class names is optional. If specified, imgproxy will classify only those classes. - -Default: `0`. - -**Response example:** - -```json -[ - { - "class_id": 68, - "name": "Bus", - "confidence": 0.8745117 - }, - { - "class_id": 351, - "name": "Person", - "confidence": 0.7734375 - } -] -``` - ### Colorspace :::slow[Slow] @@ -611,51 +577,6 @@ Default: `0:0` } ``` -### ThumbHash {#thumb-hash} - -:::slow[Slow] -This option requires the image to be fully downloaded and processed. -::: - -```imgproxy_url_option -thumb_hash:1 -th:1 -``` - -When set, imgproxy will calculate and return the image's [ThumbHash](https://evanw.github.io/thumbhash/). ThumbHash is a compact representation of an image that can be used to generate a placeholder while the actual image is loading. - -**Response example:** - -```json -{ - "thumb_hash": "0BE7810C80365AF29266578A660CB7A6707A80867738A87804" -} -``` - -### Perceptual hash {#perceptual-hash} - -:::slow[Slow] -This option requires the image to be fully downloaded and processed. -::: - -```imgproxy_url_option -perceptual_hash:1 -phash:1 -ph:1 -``` - -When set, imgproxy will calculate and return the perceptual hash of the image. Perceptual hashes can be used to find similar or duplicate images. - -**Response example:** - -```json -{ - "perceptual_hash": "9797306d694b4e94" -} -``` - -Use [Hamming Distance](https://en.wikipedia.org/wiki/Hamming_distance) to calculate the distance between two perceptual hashes. In a nutshell, the Hamming distance is the number of positions at which the corresponding bits of the two hashes differ. - ### Calc hashsums :::slow[Slow] diff --git a/docs/usage/processing.mdx b/docs/usage/processing.mdx index e179817..4ef5667 100644 --- a/docs/usage/processing.mdx +++ b/docs/usage/processing.mdx @@ -582,28 +582,6 @@ dd:%draw:%class_name1:%class_name2:...:%class_nameN When `draw` is set to `1`, `t` or `true`, imgproxy [detects objects](../features/object_detection.mdx) of the provided classes and draws their bounding boxes, classes, and confidences. If class names are omitted, imgproxy draws the bounding boxes of all the detected objects. -### Crop objects ((pro)) {#crop-objects} - -```imgproxy_url_option -crop_objects:%scale_factor:%class_name1:%class_name2:...:%class_nameN -co:%scale_factor:%class_name1:%class_name2:...:%class_nameN -``` - -imgproxy [detects objects](../features/object_detection.mdx) of the provided classes and crops the image to fit all detected objects. - -* `scale_factor`: a float value that defines how much the crop area should be scaled relative to the detected objects. For example, `1.0` crops exactly to the detected objects, while `1.2` adds 20% padding around them. -* `class_name1`, `class_name2`, ..., `class_nameN`: _(optional)_ names of the object classes to detect. If class names are omitted, imgproxy crops to all detected objects. - -This option is useful when you want to automatically extract the area containing specific objects from an image, such as all faces in a group photo or products in a catalog image. - -It respects the [`resizing_type`](#resizing-type) option, so if you set it to `fill` or `fill-down`, imgproxy will expand the cropping area to match the output dimensions’ aspect ratio. - -It also respects [`IMGPROXY_OBJECT_DETECTION_GRAVITY_MODE`](../configuration/options.mdx#IMGPROXY_OBJECT_DETECTION_GRAVITY_MODE) config option when selecting objects to crop around, and the [`objects_position`](#objects-position) option when deciding where to place the objects in the output image. - -:::info -When no objects are detected, imgproxy will not crop the image and will process it as usual. `crop_objects` option takes precedence over `crop`. -::: - ### Colorize ((pro)) {#colorize} ```imgproxy_url_option diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 650b321..ec3c14f 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -100,11 +100,14 @@ const config: Config = { routeBasePath: "/", sidebarPath: require.resolve("./sidebars.js"), // sidebarCollapsed: false, - + lastVersion: "3.31.x", versions: { current: { label: "latest", - path: "latest", + path: "3.31.x", + banner: "none", + }, + "4-preview": { banner: "unreleased", }, }, diff --git a/sidebars.ts b/sidebars.ts index e370de1..472d736 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -60,11 +60,6 @@ const sidebars: SidebarsConfig = { id: "features/object_detection", className: "menu__list-item--badge badge--pro", }, - { - type: "doc", - id: "features/classification", - className: "menu__list-item--badge badge--pro", - }, { type: "doc", id: "features/autoquality", @@ -98,37 +93,6 @@ const sidebars: SidebarsConfig = { "image_sources/openstack_swift", ], }, - { - type: "category", - label: "Cache", - link: { - type: "generated-index", - description: "Learn about how to configure cache in imgproxy", - }, - items: [ - { - type: "doc", - id: "cache/external", - label: "External cache", - }, - { - type: "category", - label: "Internal cache", - link: { - type: "doc", - id: "cache/internal", - }, - className: "menu__list-item--badge badge--pro", - items: [ - "cache/internal/local_filesystem", - "cache/internal/amazon_s3", - "cache/internal/google_cloud_storage", - "cache/internal/azure_blob_storage", - "cache/internal/openstack_swift", - ], - }, - ], - }, { type: "category", label: "Monitoring", diff --git a/versioned_docs/version-4-preview/about_processing_pipeline.mdx b/versioned_docs/version-4-preview/about_processing_pipeline.mdx new file mode 100644 index 0000000..cce626f --- /dev/null +++ b/versioned_docs/version-4-preview/about_processing_pipeline.mdx @@ -0,0 +1,20 @@ +--- +description: Learn about imgproxy's processing pipeline +--- + +# About the processing pipeline + +imgproxy has a specific processing pipeline tuned for maximum performance. When you process an image with imgproxy, it does the following: + +* If the source image format allows shrink-on-load, imgproxy uses it to quickly resize the image to the size that is closest to desired. +* If it is needed to resize an image with an alpha-channel, imgproxy premultiplies one to handle alpha correctly. +* imgproxy resizes the image to the desired size. +* If the image colorspace need to be fixed, imgproxy fixes it. +* imgproxy rotates/flip the image according to EXIF metadata. +* imgproxy crops the image using the specified gravity. +* imgproxy fills the image background if the background color was specified. +* imgproxy applies filters. +* imgproxy adds a watermark if one was specified. +* And finally, imgproxy saves the image to the desired format. + +This pipeline, using sequential access to source image data, allows for significantly reduced memory and CPU usage — one of the reasons imgproxy is so performant. diff --git a/docs/cache/external.mdx b/versioned_docs/version-4-preview/cache/external.mdx similarity index 100% rename from docs/cache/external.mdx rename to versioned_docs/version-4-preview/cache/external.mdx diff --git a/docs/cache/internal.mdx b/versioned_docs/version-4-preview/cache/internal.mdx similarity index 100% rename from docs/cache/internal.mdx rename to versioned_docs/version-4-preview/cache/internal.mdx diff --git a/docs/cache/internal/amazon_s3.mdx b/versioned_docs/version-4-preview/cache/internal/amazon_s3.mdx similarity index 100% rename from docs/cache/internal/amazon_s3.mdx rename to versioned_docs/version-4-preview/cache/internal/amazon_s3.mdx diff --git a/docs/cache/internal/azure_blob_storage.mdx b/versioned_docs/version-4-preview/cache/internal/azure_blob_storage.mdx similarity index 100% rename from docs/cache/internal/azure_blob_storage.mdx rename to versioned_docs/version-4-preview/cache/internal/azure_blob_storage.mdx diff --git a/docs/cache/internal/google_cloud_storage.mdx b/versioned_docs/version-4-preview/cache/internal/google_cloud_storage.mdx similarity index 100% rename from docs/cache/internal/google_cloud_storage.mdx rename to versioned_docs/version-4-preview/cache/internal/google_cloud_storage.mdx diff --git a/docs/cache/internal/local_filesystem.mdx b/versioned_docs/version-4-preview/cache/internal/local_filesystem.mdx similarity index 100% rename from docs/cache/internal/local_filesystem.mdx rename to versioned_docs/version-4-preview/cache/internal/local_filesystem.mdx diff --git a/docs/cache/internal/openstack_swift.mdx b/versioned_docs/version-4-preview/cache/internal/openstack_swift.mdx similarity index 100% rename from docs/cache/internal/openstack_swift.mdx rename to versioned_docs/version-4-preview/cache/internal/openstack_swift.mdx diff --git a/versioned_docs/version-4-preview/configuration/loading_environment_variables.mdx b/versioned_docs/version-4-preview/configuration/loading_environment_variables.mdx new file mode 100644 index 0000000..622d8b6 --- /dev/null +++ b/versioned_docs/version-4-preview/configuration/loading_environment_variables.mdx @@ -0,0 +1,171 @@ +--- +description: Learn about how you can load environment variables from various sources with imgproxy +--- + +# Loading environment variables + +imgproxy can load environment variables from various sources such as: + +* [Local file](#local-file) +* [AWS Secrets Manager](#aws-secrets-manager) +* [AWS Systems Manager Parameter Store](#aws-systems-manager-parameter-store) +* [Google Cloud Secret Manager](#google-cloud-secret-manager) + +## Local file + +You can create an [environment file](#environment-file-syntax) and configure imgproxy to read environment variables from it. + +* `IMGPROXY_ENV_LOCAL_FILE_PATH`: the path of the environment file to load + +## AWS Secrets Manager + +You can store the content of an [environment file](#environment-file-syntax) as an AWS Secrets Manager secret and configure imgproxy to read environment variables from it. + +* `IMGPROXY_ENV_AWS_SECRET_ID`: the ARN or name of the secret to load +* `IMGPROXY_ENV_AWS_SECRET_VERSION_ID`: _(optional)_ the unique identifier of the version of the secret to load +* `IMGPROXY_ENV_AWS_SECRET_VERSION_STAGE`: _(optional)_ the staging label of the version of the secret to load +* `IMGPROXY_ENV_AWS_SECRET_REGION`: _(optional)_ the region of the secret to load + +:::info +If both `IMGPROXY_ENV_AWS_SECRET_VERSION_ID` and `IMGPROXY_ENV_AWS_SECRET_VERSION_STAGE` are set, `IMGPROXY_ENV_AWS_SECRET_VERSION_STAGE` will be ignored +::: + +### Set up AWS Secrets Manager credentials + +There are three ways to specify your AWS credentials. The credentials policy should allow performing the `secretsmanager:GetSecretValue` and `secretsmanager:ListSecretVersionIds` actions with the specified secret: + +#### IAM Roles + +If you're running imgproxy on an Amazon Web Services platform, you can use IAM roles to to get the security credentials to retrieve the secret. + +* **Elastic Container Service (ECS):** Assign an [IAM role to a task](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html). +* **Elastic Kubernetes Service (EKS):** Assign a [service account to a pod](https://docs.aws.amazon.com/eks/latest/userguide/pod-configuration.html). +* **Elastic Beanstalk:** Assign an [IAM role to an instance](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/iam-instanceprofile.html). + +#### Environment variables + +You can specify an AWS Access Key ID and a Secret Access Key by setting the standard `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables. + +``` bash +AWS_ACCESS_KEY_ID=my_access_key AWS_SECRET_ACCESS_KEY=my_secret_key imgproxy + +# same for Docker +docker run -e AWS_ACCESS_KEY_ID=my_access_key -e AWS_SECRET_ACCESS_KEY=my_secret_key -it ghcr.io/imgproxy/imgproxy +``` + +#### Shared credentials file + +Alternatively, you can create the `.aws/credentials` file in your home directory with the following content: + +```ini +[default] +aws_access_key_id = %access_key_id +aws_secret_access_key = %secret_access_key +``` + +## AWS Systems Manager Parameter Store + +You can store multiple AWS Systems Manager Parameter Store entries and configure imgproxy to load their values to separate environment variables. + +* `IMGPROXY_ENV_AWS_SSM_PARAMETERS_PATH`: the [path](#aws-systems-manager-path) of the parameters to load +* `IMGPROXY_ENV_AWS_SSM_PARAMETERS_REGION`: _(optional)_ the region of the parameters to load + +### AWS Systems Manager path + +Let's assume that you created the following AWS Systems Manager parameters: + +* `/imgproxy/prod/IMGPROXY_KEY` +* `/imgproxy/prod/IMGPROXY_SALT` +* `/imgproxy/prod/IMGPROXY_CLOUD_WATCH/SERVICE_NAME` +* `/imgproxy/prod/IMGPROXY_CLOUD_WATCH/NAMESPACE` +* `/imgproxy/staging/IMGPROXY_KEY` + +If you set `IMGPROXY_ENV_AWS_SSM_PARAMETERS_PATH` to `/imgproxy/prod`, imgproxy will load these parameters the following way: + +* `/imgproxy/prod/IMGPROXY_KEY` value will be loaded to `IMGPROXY_KEY` +* `/imgproxy/prod/IMGPROXY_SALT` value will be loaded to `IMGPROXY_SALT` +* `/imgproxy/prod/IMGPROXY_CLOUD_WATCH/SERVICE_NAME` value will be loaded to `IMGPROXY_CLOUD_WATCH_SERVICE_NAME` +* `/imgproxy/prod/IMGPROXY_CLOUD_WATCH/NAMESPACE` value will be loaded to `IMGPROXY_CLOUD_WATCH_NAMESPACE` +* `/imgproxy/staging/IMGPROXY_KEY` will be ignored since its path is not `/imgproxy/prod` + +### Set up AWS Systems Manager credentials + +There are three ways to specify your AWS credentials. The credentials policy should allow performing the `ssm:GetParametersByPath` action with the specified parameters: + +#### IAM Roles + +If you're running imgproxy on an Amazon Web Services platform, you can use IAM roles to to get the security credentials to retrieve the secret. + +* **Elastic Container Service (ECS):** Assign an [IAM role to a task](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html). +* **Elastic Kubernetes Service (EKS):** Assign a [service account to a pod](https://docs.aws.amazon.com/eks/latest/userguide/pod-configuration.html). +* **Elastic Beanstalk:** Assign an [IAM role to an instance](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/iam-instanceprofile.html). + +#### Environment variables + +You can specify an AWS Access Key ID and a Secret Access Key by setting the standard `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables. + +``` bash +AWS_ACCESS_KEY_ID=my_access_key AWS_SECRET_ACCESS_KEY=my_secret_key imgproxy + +# same for Docker +docker run -e AWS_ACCESS_KEY_ID=my_access_key -e AWS_SECRET_ACCESS_KEY=my_secret_key -it ghcr.io/imgproxy/imgproxy +``` + +#### Shared credentials file + +Alternatively, you can create the `.aws/credentials` file in your home directory with the following content: + +```ini +[default] +aws_access_key_id = %access_key_id +aws_secret_access_key = %secret_access_key +``` + +## Google Cloud Secret Manager + +You can store the content of an [environment file](#environment-file-syntax) in Google Cloud Secret Manager secret and configure imgproxy to read environment variables from it. + +* `IMGPROXY_ENV_GCP_SECRET_ID`: the name of the secret to load +* `IMGPROXY_ENV_GCP_SECRET_VERSION_ID`: _(optional)_ the unique identifier of the version of the secret to load +* `IMGPROXY_ENV_GCP_SECRET_PROJECT_ID`: the name or ID of the Google Cloud project that contains the secret + +### Setup credentials + +If you run imgproxy inside Google Cloud infrastructure (Compute Engine, Kubernetes Engine, App Engine, Cloud Functions, etc), and you have granted access to the specified secret to the service account, you probably don't need to do anything here. imgproxy will try to use the credentials provided by Google. + +Otherwise, set `IMGPROXY_ENV_GCP_KEY` environment variable to the content of Google Cloud JSON key. Get more info about JSON keys: [https://cloud.google.com/iam/docs/creating-managing-service-account-keys](https://cloud.google.com/iam/docs/creating-managing-service-account-keys). + +:::warning +For security reasons, imgproxy accepts only service account keys for Google Cloud Secret Manager integration. +::: + +## Environment file syntax + +The following syntax rules apply to environment files: + +* Blank lines are ignored +* Lines beginning with `#` are processed as comments and ignored +* Each line represents a key-value pair. Values can optionally be quoted: + * `VAR=VAL` -> `VAL` + * `VAR="VAL"` -> `VAL` + * `VAR='VAL'` -> `VAL` +* Unquoted and double-quoted (`"`) values have variable substitution applied: + * `VAR=${OTHER_VAR}` -> value of `OTHER_VAR` + * `VAR=$OTHER_VAR` -> value of `OTHER_VAR` + * `VAR="$OTHER_VAR"` -> value of `OTHER_VAR` + * `VAR="${OTHER_VAR}"` -> value of `OTHER_VAR` +* Single-quoted (`'`) values are used literally: + * `VAR='$OTHER_VAR'` -> `$OTHER_VAR` + * `VAR='${OTHER_VAR}'` -> `${OTHER_VAR}` +* Double quotes in double-quoted (`"`) values can be escaped with `\`: + * `VAR="{\"hello\": \"json\"}"` -> `{"hello": "json"}` +* Slash (`\`) in double-quoted values can be escaped with another slash: + * `VAR="some\\value"` -> `some\value` +* A new line can be added to double-quoted values using `\n`: + * `VAR="some\nvalue"` -> + + ``` + some + value + ``` + diff --git a/versioned_docs/version-4-preview/configuration/options.mdx b/versioned_docs/version-4-preview/configuration/options.mdx new file mode 100644 index 0000000..c6c85c6 --- /dev/null +++ b/versioned_docs/version-4-preview/configuration/options.mdx @@ -0,0 +1,813 @@ +--- +description: Learn about imgproxy's configuration options +--- + +# Configuration options + +imgproxy is [Twelve-Factor-App](https://12factor.net/)-ready and can be configured using `ENV` variables. + +## URL signature + +imgproxy allows URLs to be signed with a key and a salt. This feature is disabled by default, but is _highly_ recommended to be enabled in production. To enable URL signature checking, define the key/salt pair: + +* [`IMGPROXY_KEY`]: hex-encoded key +* [`IMGPROXY_SALT`]: hex-encoded salt +* [`IMGPROXY_SIGNATURE_SIZE`]: number of bytes to use for signature before encoding to Base64. Default: 32 + +You can specify multiple key/salt pairs by dividing the keys and salts with a comma (`,`). imgproxy will check URL signatures with each pair. This is useful when you need to change key/salt pairs in your application while incurring zero downtime. + +If you need a random key/salt pair really fast, as an example, you can quickly generate one using the following snippet: + +```bash +echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n') +``` + +* [`IMGPROXY_TRUSTED_SIGNATURES`]: a list of trusted signatures, comma divided. When set, imgproxy will trust the signatures from the list and won't check them even if `IMGPROXY_KEY` and `IMGPROXY_SALT` are set. Default: blank + +## Server + +* [`IMGPROXY_BIND`]: the address and port or Unix socket to listen to. Default: `:8080` +* [`IMGPROXY_NETWORK`]: the network to use. Known networks are `tcp`, `tcp4`, `tcp6`, `unix`, and `unixpacket`. Default: `tcp` +* [`IMGPROXY_TIMEOUT`]: the maximum duration (in seconds) for processing the response. Default: `10` +* [`IMGPROXY_GRACEFUL_STOP_TIMEOUT`]: the maximum duration (in seconds) to wait for ongoing requests to finish before shutting down the server. Default: twice the `IMGPROXY_TIMEOUT` value +* [`IMGPROXY_READ_REQUEST_TIMEOUT`]: the maximum duration (in seconds) for reading the entire incoming HTTP request, including the body. Default: `10` +* [`IMGPROXY_WRITE_RESPONSE_TIMEOUT`]: the maximum duration (in seconds) for writing the HTTP response body. Default: `10` +* [`IMGPROXY_KEEP_ALIVE_TIMEOUT`]: the maximum duration (in seconds) to wait for the next request before closing the connection. When set to `0`, keep-alive is disabled. Default: `10` +* [`IMGPROXY_CLIENT_KEEP_ALIVE_TIMEOUT`]: the maximum duration (in seconds) to wait for the next request before closing the HTTP client connection. The HTTP client is used to download source images. When set to `0`, keep-alive is disabled. Default: `90` +* [`IMGPROXY_DOWNLOAD_TIMEOUT`]: the maximum duration (in seconds) for downloading the source image. Default: `5` +* [`IMGPROXY_WORKERS`]: the maximum number of images an imgproxy instance can process simultaneously without creating a queue. Default: the number of CPU cores multiplied by two + :::info + When running in AWS Lambda, imgproxy automatically sets `IMGPROXY_WORKERS` to `1` since each Lambda instance processes only one request at a time. + ::: +* [`IMGPROXY_REQUESTS_QUEUE_SIZE`]: the maximum number of image requests that can be put in the queue. Requests that exceed this limit are rejected with `429` HTTP status. When set to `0`, the requests queue is unlimited. Default: `0` +* [`IMGPROXY_MAX_CLIENTS`]: the maximum number of simultaneous active connections. When set to `0`, connection limit is disabled. Default: `2048` +* [`IMGPROXY_TTL`]: a duration (in seconds) sent via the `Cache-Control: max-age` HTTP header. Default: `31536000` (1 year) +* [`IMGPROXY_CACHE_CONTROL_PASSTHROUGH`]: when `true` and the source image response contains the `Expires` or `Cache-Control` headers, reuse those headers. Default: false +* [`IMGPROXY_SET_CANONICAL_HEADER`]: when `true` and the source image has an `http` or `https` scheme, set a `rel="canonical"` HTTP header to the value of the source image URL. More details [here](https://developers.google.com/search/docs/advanced/crawling/consolidate-duplicate-urls#rel-canonical-header-method). Default: `false` +* [`IMGPROXY_SO_REUSEPORT`]: when `true`, enables `SO_REUSEPORT` socket option (currently only available on Linux and macOS); +* [`IMGPROXY_PATH_PREFIX`]: the URL path prefix. Example: when set to `/abc/def`, the imgproxy URL will be `/abc/def/%signature/%processing_options/%source_url`. Default: blank +* [`IMGPROXY_USER_AGENT`]: the User-Agent header that will be sent with the source image request. You can use the `%current_version` variable to insert the current imgproxy version. Default: `imgproxy/%current_version` +* [`IMGPROXY_USE_ETAG`]: when set to `true`, enables using the [ETag](https://en.wikipedia.org/wiki/HTTP_ETag) HTTP header for HTTP cache control. Default: `false` +* [`IMGPROXY_ETAG_BUSTER`]: a global ETag buster value. Change this value if you update the configuration that affects image processing, to invalidate old ETags and avoid `304 Not Modified` responses from stale client/CDN validators. Default: blank +* [`IMGPROXY_USE_LAST_MODIFIED`]: when set to `true`, enables using the [Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) HTTP header for HTTP cache control. Default: `false` +* [`IMGPROXY_LAST_MODIFIED_BUSTER`]: a global `Last-Modified` buster timestamp in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html) format. Change this value if you update the configuration that affects image processing. It will make imgproxy treat all images as if they were modified at least at the specified datetime. Default: blank +* [`IMGPROXY_CUSTOM_REQUEST_HEADERS`]: ((pro)) list of custom headers that imgproxy will send while requesting the source image, divided by `\;` (can be redefined by `IMGPROXY_CUSTOM_HEADERS_SEPARATOR`). Example: `X-MyHeader1=Lorem\;X-MyHeader2=Ipsum` +* [`IMGPROXY_CUSTOM_RESPONSE_HEADERS`]: ((pro)) a list of custom response headers, separated by `\;` (can be redefined by `IMGPROXY_CUSTOM_HEADERS_SEPARATOR`). Example: `X-MyHeader1=Lorem\;X-MyHeader2=Ipsum` +* [`IMGPROXY_CUSTOM_HEADERS_SEPARATOR`]: ((pro)) a string that will be used as a custom header separator. Default: `\;` +* [`IMGPROXY_REQUEST_HEADERS_PASSTHROUGH`]: ((pro)) a list of names of incoming request headers that should be passed through to the source image request. +* [`IMGPROXY_RESPONSE_HEADERS_PASSTHROUGH`]: ((pro)) a list of names of source image response headers that should be passed through to the imgproxy response. +* [`IMGPROXY_ENABLE_DEBUG_HEADERS`]: when set to `true`, imgproxy will add debug headers to the response. Default: `false`. The following headers will be added: + * `X-Origin-Content-Length`: the size of the source image + * `X-Origin-Width`: the width of the source image + * `X-Origin-Height`: the height of the source image + * `X-Result-Width`: the width of the resultant image + * `X-Result-Height`: the height of the resultant image +* [`IMGPROXY_SERVER_NAME`]: ((pro)) the `Server` header value. Default: `imgproxy` + +## Security + +imgproxy protects you from so-called image bombs. Here's how you can specify the maximum image resolution which you consider reasonable: + +* [`IMGPROXY_MAX_SRC_RESOLUTION`]: the maximum resolution of the source image, in megapixels. Images with larger actual size will be rejected. Default: `50` + + :::warning + When the source image is animated, imgproxy summarizes all its frames' resolutions while checking the source image resolution unless `IMGPROXY_MAX_ANIMATION_FRAME_RESOLUTION` is greater than zero. + ::: + +* [`IMGPROXY_MAX_SRC_FILE_SIZE`]: the maximum size of the source image, in bytes. Images with larger file size will be rejected. When set to `0`, file size check is disabled. Default: `0` + +imgproxy can process animated images (GIF, WebP), but since this operation is pretty memory heavy, only one frame is processed by default. You can increase the maximum animation frames that can be processed number of with the following variable: + +* [`IMGPROXY_MAX_ANIMATION_FRAMES`]: the maximum number of animated image frames that may be processed. Default: `1` +* [`IMGPROXY_MAX_ANIMATION_FRAME_RESOLUTION`]: the maximum resolution of the animated source image frame, in megapixels. Images with larger actual frame size will be rejected. When set to `0`, imgproxy will test the whole animated image resolution against `IMGPROXY_MAX_SRC_RESOLUTION` summarising all the frames' resolutions. Default: `0` + +* [`IMGPROXY_MAX_RESULT_DIMENSION`]: the maximum width or height the resultant image can have, in pixels. When any of the dimensions exceeds this value, imgproxy will scale the image down to fit within the specified maximum dimension. When set to `0`, this check is disabled. Default: `0` + +* [`IMGPROXY_ALLOWED_PROCESSING_OPTIONS`]: a list of processing options allowed to be used in imgproxy URLs, divided by comma. When blank, all processing options are allowed. Default: blank + + :::info + If you want to allow both full and short names of a processing option, you should specify them both. For example, if you specify only `resize`, imgproxy will reject URLs with `rs` as a processing option, and vice versa. + ::: + + :::tip + imgproxy doesn't check the processing options used in presets. This enables you to allow using a limited set of processing options directly in imgproxy URLs, while having a set of presets for the rest of them. + ::: + +* [`IMGPROXY_ALLOWED_INFO_OPTIONS`]: a list of info options allowed to be used in imgproxy URLs, divided by comma. When blank, all info options are allowed. Default: blank + + :::info + If you want to allow both full and short names of an info option, you should specify them both. For example, if you specify only `dominant_colors`, imgproxy will reject URLs with `dc` as an info option, and vice versa. + ::: + + :::tip + imgproxy doesn't check the info options used in presets. This enables you to allow using a limited set of info options directly in imgproxy URLs, while having a set of presets for the rest of them. + ::: + +* [`IMGPROXY_MAX_CHAINED_PIPELINES`]: the maximum number of chained pipelines that can be specified in the imgproxy URL. When set to `0`, this check is disabled. Default: `0` + + :::tip + imgproxy doesn't check the number of chained pipelines used in presets + ::: + +Requests to some image sources may go through too many redirects or enter an infinite loop. You can limit the number of allowed redirects: + +* [`IMGPROXY_MAX_REDIRECTS`]: the max number of redirects imgproxy can follow while requesting the source image. When set to `0`, no redirects are allowed. Default: `10` + +You can also specify a secret key to enable authorization with the HTTP `Authorization` header for use in production environments: + +* [`IMGPROXY_SECRET`]: the authorization token. If specified, the HTTP request should contain the `Authorization: Bearer %secret%` header. + +If you don't want to reveal your source URLs, you can encrypt them with the AES-CBC algorithm: + +* [`IMGPROXY_SOURCE_URL_ENCRYPTION_KEY`]: hex-encoded key used for source URL encryption. Default: blank + + :::tip + Read more about source URL encryption in the [encrypting the source URL guide](../usage/encrypting_source_url.mdx). + ::: + +imgproxy does not send CORS headers by default. CORS will need to be allowed by using the following variable: + +* [`IMGPROXY_ALLOW_ORIGIN`]: when specified, enables CORS headers with the provided origin. CORS headers are disabled by default. + +You can limit allowed source URLs with the following variable: + +* [`IMGPROXY_ALLOWED_SOURCES`]: a whitelist of source image URL prefixes divided by comma. Wildcards can be included with `*` to match all characters except `/`. When blank, imgproxy allows all source image URLs. Example: `s3://,https://*.example.com/,local://`. Default: blank + + :::warning + Be careful when using this config to limit source URL hosts, and always add a trailing slash after the host. + +

Bad: http://example.com

+ +

Good: http://example.com/

+ + If the trailing slash is absent, `http://example.com@baddomain.com` would be a permissable URL, however, the request would be made to `baddomain.com`. + ::: + +* [`IMGPROXY_ALLOW_LOOPBACK_SOURCE_ADDRESSES`]: when `true`, allows connecting to loopback IP addresses (`127.0.0.1`-`127.255.255.255` and IPv6 analogues) when requesting source images. Default: `false` +* [`IMGPROXY_ALLOW_LINK_LOCAL_SOURCE_ADDRESSES`]: when `true`, allows connecting to link-local multicast and unicast IP addresses (`224.0.0.1`-`224.0.0.255`, `169.254.0.1`-`169.254.255.255`, and IPv6 analogues) when requesting source images. Default: `false` +* [`IMGPROXY_ALLOW_PRIVATE_SOURCE_ADDRESSES`]: when `true`, allows connecting to private IP addresses (`10.0.0.0 - 10.255.255.255`, `172.16.0.0 - 172.31.255.255`, `192.168.0.0 - 192.168.255.255`, and IPv6 analogues) when requesting source images. Default: `true` + +* [`IMGPROXY_PNG_UNLIMITED`]: when `true`, disables the limit on the number of PNG chunks. Default: `false` + + :::warning + Disabling the limit on the number of PNG chunks can lead to memory exhaustion and DoS attacks. + ::: + +* [`IMGPROXY_SVG_UNLIMITED`]: when `true`, disables the limit on the SVG file size (10MB). Default: `false` + + :::warning + Disabling the limit on the SVG file size can lead to memory exhaustion and DoS attacks. + ::: + +* [`IMGPROXY_SANITIZE_SVG`]: when `true`, imgproxy will remove scripts from SVG images to prevent XSS attacks. Defaut: `true` + +When using imgproxy in a development environment, it can be useful to ignore SSL verification: + +* [`IMGPROXY_IGNORE_SSL_VERIFICATION`]: when `true`, disables SSL verification, so imgproxy can be used in a development environment with self-signed SSL certificates. + +Also you may want imgproxy to respond with the same error message that it writes to the log: + +* [`IMGPROXY_ALLOW_SECURITY_OPTIONS`]: when `true`, allows usage of security-related processing options such as `max_src_resolution`, `max_src_file_size`, `max_animation_frames`, `max_animation_frame_resolution`, and `max_result_dimension`. Default: `false`. + + :::warning + `IMGPROXY_ALLOW_SECURITY_OPTIONS` allows bypassing your security restrictions. Don't set it to `true` unless you are completely sure that an attacker can't change your imgproxy URLs. + ::: + +## Cookies + +imgproxy can pass cookies in image requests. This can be activated with `IMGPROXY_COOKIE_PASSTHROUGH`. Unfortunately the `Cookie` header doesn't contain information about which URLs these cookies are applicable to, so imgproxy can only assume (or must be told). + +When cookie forwarding is activated, by default, imgproxy assumes the scope of the cookies to be all URLs with the same hostname/port and request scheme as given by the headers `X-Forwarded-Host`, `X-Forwarded-Port`, `X-Forwarded-Scheme` or `Host`. To change that use `IMGPROXY_COOKIE_BASE_URL`. + +If you want to pass cookies to any image URL regardless of the hostname, path, or scheme, you can additionally set `IMGPROXY_COOKIE_PASSTHROUGH_ALL` to `true`. + +* [`IMGPROXY_COOKIE_PASSTHROUGH`]: when `true`, incoming cookies will be passed through the image request if they are applicable for the image URL. Default: `false` + +* [`IMGPROXY_COOKIE_BASE_URL`]: when set, assume that cookies have the scope of this URL for an incoming request (instead of using request headers). If the cookies are applicable to the image URL too, they will be passed along in the image request + +* [`IMGPROXY_COOKIE_PASSTHROUGH_ALL`]: when `true`, all incoming cookies will be passed through the image request regardless of the image URL. Default: `false` + +:::warning +Cookies can contain sensitive information. Be careful when using `IMGPROXY_COOKIE_PASSTHROUGH_ALL` and avoid its usage unless you completely trust the servers imgproxy will send image requests to. +::: + +## Compression + +* [`IMGPROXY_QUALITY`]: the default quality of the resultant image, percentage. Default: `80` +* [`IMGPROXY_FORMAT_QUALITY`]: default quality of the resulting image per format, separated by commas. Example: `jpeg=70,avif=40,webp=60`. When a value for the resulting format is not set, the `IMGPROXY_QUALITY` value is used. Default: `webp=79,avif=63,jxl=77` + +### Advanced JPEG compression + +* [`IMGPROXY_JPEG_PROGRESSIVE`]: when `true`, enables progressive JPEG compression. Default: `false` +* [`IMGPROXY_JPEG_NO_SUBSAMPLE`]: ((pro)) when `true`, chrominance subsampling is disabled. This will improve quality at the cost of larger file size. Default: `false` +* [`IMGPROXY_JPEG_TRELLIS_QUANT`]: ((pro)) when `true`, enables trellis quantisation for each 8x8 block. Reduces file size but increases compression time. Default: `false` +* [`IMGPROXY_JPEG_OVERSHOOT_DERINGING`]: ((pro)) when `true`, enables overshooting of samples with extreme values. Overshooting may reduce ringing artifacts from compression, in particular in areas where black text appears on a white background. Default: `false` +* [`IMGPROXY_JPEG_OPTIMIZE_SCANS`]: ((pro)) when `true`, splits the spectrum of DCT coefficients into separate scans. Reduces file size but increases compression time. Requires `IMGPROXY_JPEG_PROGRESSIVE` to be true. Default: `false` +* [`IMGPROXY_JPEG_QUANT_TABLE`]: ((pro)) quantization table to use. Supported values are: + * `0`: Table from JPEG Annex K (default) + * `1`: Flat table + * `2`: Table tuned for MSSIM on Kodak image set + * `3`: Table from ImageMagick by N. Robidoux + * `4`: Table tuned for PSNR-HVS-M on Kodak image set + * `5`: Table from Relevance of Human Vision to JPEG-DCT Compression (1992) + * `6`: Table from DCTune Perceptual Optimization of Compressed Dental X-Rays (1997) + * `7`: Table from A Visual Detection Model for DCT Coefficient Quantization (1993) + * `8`: Table from An Improved Detection Model for DCT Coefficient Quantization (1993) + +### Advanced PNG compression + +* [`IMGPROXY_PNG_INTERLACED`]: when `true`, enables interlaced PNG compression. Default: `false` +* [`IMGPROXY_PNG_QUANTIZE`]: when `true`, enables PNG quantization. libvips should be built with [Quantizr](https://github.com/DarthSim/quantizr) or libimagequant support. Default: `false` +* [`IMGPROXY_PNG_QUANTIZATION_COLORS`]: maximum number of quantization palette entries. Should be between 2 and 256. Default: 256 + +### Advanced WebP compression + +* [`IMGPROXY_WEBP_COMPRESSION`]: ((pro)) the compression method to use. Supported values are `lossy`, `near_lossless`, and `lossless`. Default: `lossy` +* [`IMGPROXY_WEBP_SMART_SUBSAMPLE`]: ((pro)) when `true`, enables smart subsampling. Smart subsampling increases the resulting file size and compression time but improves quality. Default: `false` +* [`IMGPROXY_WEBP_EFFORT`]: controls the CPU effort spent improving compression. The larger the value, the slower the encoding process but the better the compression. The value should be between 1 and 6. Default: `4` +* [`IMGPROXY_WEBP_PRESET`]: a hint to the encoder about the type of image being compressed. Supported values are: + * `default`: _(default)_ a general-purpose preset + * `photo`: a digital picture, like portrait, inner shot + * `picture`: an outdoor photograph, with natural lighting + * `drawing`: a hand or line drawing, with high-contrast details + * `icon`: a small-sized colorful image + * `text`: a text image, with large areas of uniform color + +### Advanced AVIF compression + +* [`IMGPROXY_AVIF_SPEED`]: controls the CPU effort spent improving compression. The lowest speed is at 0 and the fastest is at 9. Default: `8` +* [`IMGPROXY_AVIF_SUBSAMPLE`]: ((pro)) controls when chroma subsampling is used. Supported values are: + * `auto`: _(default)_ use subsampling when the image is saved with quality less than `90` + * `on`: always use subsampling + * `off`: never use subsampling + +### Advanced JPEG XL compression + +* [`IMGPROXY_JXL_EFFORT`]: controls the CPU effort spent improving compression. The larger the value, the slower the encoding process but the better the compression. The value should be between 1 and 9. Default: `4` + +### Autoquality + +imgproxy can calculate the quality of the resulting image based on selected metric. Read more in the [Autoquality](../features/autoquality.mdx) guide. + +:::warning +Autoquality requires the image to be saved several times. Use it only when you prefer the resulting size and quality over the speed. +::: + +* [`IMGPROXY_AUTOQUALITY_METHOD`]: ((pro)) the method of quality calculation. Default: `none` +* [`IMGPROXY_AUTOQUALITY_TARGET`]: ((pro)) desired value of the autoquality method metric. Default: 0.02 +* [`IMGPROXY_AUTOQUALITY_MIN`]: ((pro)) minimal quality imgproxy can use. Default: 70 +* [`IMGPROXY_AUTOQUALITY_FORMAT_MIN`]: ((pro)) the minimal quality imgproxy can use per format, comma divided. Example: `jpeg=70,avif=40,webp=60`. When value for the resulting format is not set, `IMGPROXY_AUTOQUALITY_MIN` value is used. Default: `avif=60` +* [`IMGPROXY_AUTOQUALITY_MAX`]: ((pro)) the maximum quality imgproxy can use. Default: 80 +* [`IMGPROXY_AUTOQUALITY_FORMAT_MAX`]: ((pro)) the maximum quality imgproxy can use per format, comma divided. Example: `jpeg=70,avif=40,webp=60`. When a value for the resulting format is not set, the `IMGPROXY_AUTOQUALITY_MAX` value is used. Default: `avif=65` +* [`IMGPROXY_AUTOQUALITY_ALLOWED_ERROR`]: ((pro)) the allowed `IMGPROXY_AUTOQUALITY_TARGET` error. Applicable only to `dssim` and `ml` methods. Default: 0.001 +* [`IMGPROXY_AUTOQUALITY_MAX_RESOLUTION`]: ((pro)) when this value is greater then zero and the resultant resolution exceeds the value, autoquality won't be used. Default: 0 +* [`IMGPROXY_AUTOQUALITY_JPEG_NET`]: ((pro)) the path to the neural network for JPEG. +* [`IMGPROXY_AUTOQUALITY_WEBP_NET`]: ((pro)) the path to the neural network for WebP. +* [`IMGPROXY_AUTOQUALITY_AVIF_NET`]: ((pro)) the path to the neural network for AVIF. +* [`IMGPROXY_AUTOQUALITY_JXL_NET`]: ((pro)) the path to the neural network for JPEG XL. + +## SVG processing +* [`IMGPROXY_ALWAYS_RASTERIZE_SVG`]: when `true`, imgproxy will always rasterize SVG images unless SVG processing is not [skipped](#skip-processing). Default: `false` + +## AVIF/WebP/JPEG XL support detection + +imgproxy can use the `Accept` HTTP header to detect if the browser supports AVIF, WebP, or JPEG XL and use it as the default format. This feature is disabled by default and can be enabled by the following options: + +* [`IMGPROXY_AUTO_WEBP`]: _(deprecated alias: [`IMGPROXY_ENABLE_WEBP_DETECTION`])_ enables WebP support detection. When the file extension is omitted in the imgproxy URL and browser supports WebP, imgproxy will use it as the resulting format. +* [`IMGPROXY_ENFORCE_WEBP`]: enables WebP support detection and enforces WebP usage. If the browser supports WebP, it will be used as resulting format even if another extension is specified in the imgproxy URL. +* [`IMGPROXY_AUTO_AVIF`]: _(deprecated alias: [`IMGPROXY_ENABLE_AVIF_DETECTION`])_ enables AVIF support detection. When the file extension is omitted in the imgproxy URL and browser supports AVIF, imgproxy will use it as the resulting format. +* [`IMGPROXY_ENFORCE_AVIF`]: enables AVIF support detection and enforces AVIF usage. If the browser supports AVIF, it will be used as resulting format even if another extension is specified in the imgproxy URL. +* [`IMGPROXY_AUTO_JXL`]: enables JPEG XL support detection. When the file extension is omitted in the imgproxy URL and browser supports JPEG XL, imgproxy will use it as the resulting format. +* [`IMGPROXY_ENFORCE_JXL`]: enables JPEG XL support detection and enforces JPEG XL usage. If the browser supports JPEG XL, it will be used as the resulting format even if another extension is specified in the imgproxy URL. + +:::info +If multiple format detection/enforcement options are enabled, and the browser supports multiple of them, imgproxy will use the format with the highest priority. The priority is as follows (from the highest to the lowest): JPEG XL, AVIF, WebP +::: + +:::info +If both the source and the requested image formats support animation and AVIF detection/enforcement is enabled, AVIF won't be used as AVIF sequence is not supported yet. +::: + +:::info +If both the source and the requested image formats support animation and JPEG XL detection/enforcement is enabled, JPEG XL won't be used as animated JPEG XL is not widely supported by browsers yet. +::: + +:::tip +When AVIF/WebP/JPEG XL support detection is enabled, please take care to configure your CDN or caching proxy to take the `Accept` HTTP header into account while caching. +::: + +:::warning +Headers cannot be signed. This means that an attacker can bypass your CDN cache by changing the `Accept` HTTP headers. Keep this in mind when configuring your production caching setup. +::: + +## Preferred formats + +When the resulting image format is not explicitly specified in the imgproxy URL via the extension or the `format` processing option, imgproxy will choose one of the preferred formats: + +* [`IMGPROXY_PREFERRED_FORMATS`]: a list of preferred formats, comma divided. Default: `jpeg,png,gif` + +imgproxy is guided by the following rules when choosing the resulting format: + +1. If the preferred formats list contains the source image format, it will be used +2. If the resulting image is animated, the resulting image format should support animations +3. If the resulting image contains transparency, the resulting image format should support transparency +4. imgproxy chooses the first preferred format that meets those requirements +5. If none of the preferred formats meet the requirements, the first preferred format is used + +:::info +When AVIF/WebP/JPEG XL support detection is enabled and the browser supports AVIF/WebP/JPEG XL, it may be used as the resultant format even if the preferred formats list doesn't contain it. +::: + +## Skip processing + +You can configure imgproxy to skip processing of some formats: + +* [`IMGPROXY_SKIP_PROCESSING_FORMATS`]: a list of formats that imgproxy shouldn't process, comma divided. + +:::info +Processing can only be skipped when the requested format is the same as the source format. +::: + +:::info +Video thumbnail processing can't be skipped. +::: + +## Best format + +You can use the `best` value for the [format](../usage/processing.mdx#format) option or the [extension](../usage/processing.mdx#extension) to make imgproxy pick the best format for the resultant image. + +* [`IMGPROXY_BEST_FORMAT_COMPLEXITY_THRESHOLD`]: ((pro)) the image complexity threshold. imgproxy will use a lossless or near-lossless encoding for images with low complexity. Default: `5.5` +* [`IMGPROXY_BEST_FORMAT_MAX_RESOLUTION`]: ((pro)) when greater than `0` and the image's resolution (in megapixels) is larger than the provided value, imgproxy won't try all the applicable formats and will just pick one that seems the best for the image +* [`IMGPROXY_BEST_FORMAT_BY_DEFAULT`]: ((pro)) when `true` and the resulting image format is not specified explicitly, imgproxy will use the `best` format instead of the source image format +* [`IMGPROXY_BEST_FORMAT_ALLOW_SKIPS`]: ((pro)) when `true` and the `best` format is used, imgproxy will skip processing of SVG and formats [listed to skip processing](#skip-processing) + +Check out the [Best format](../features/best_format.mdx) guide to learn more. + +## Colorspace and HDR + +* [`IMGPROXY_PRESERVE_HDR`]: when `true`, imgproxy will preserve high bit images. When `false`, imgproxy will convert high bit images to 8-bit. Colorspace (color/grayscale) is always preserved regardless of this setting. See the [Colorspace and HDR preservation](../image_formats_support.mdx#colorspace-and-hdr-preservation) guide for more details. Default: `false` + +## Client Hints support + +imgproxy can use the `Width` and `DPR` HTTP headers to determine default width and DPR options using Client Hints. This feature is disabled by default and can be enabled by the following option: + +* [`IMGPROXY_ENABLE_CLIENT_HINTS`]: enables Client Hints support to determine default width and DPR options. Read more details [here](https://developers.google.com/web/updates/2015/09/automating-resource-selection-with-client-hints) about Client Hints. + +:::warning +Headers cannot be signed. This means that an attacker can bypass your CDN cache by changing the `Width` or `DPR` HTTP headers. Keep this in mind when configuring your production caching setup. +::: + +## Video thumbnails + +imgproxy Pro can extract specific video frames to create thumbnails. This feature is disabled by default, but can be enabled with `IMGPROXY_ENABLE_VIDEO_THUMBNAILS`. + +* [`IMGPROXY_ENABLE_VIDEO_THUMBNAILS`]: ((pro)) when `true`, enables video thumbnail generation. Default: `false` +* [`IMGPROXY_VIDEO_THUMBNAIL_SECOND`]: ((pro)) the timestamp of the frame (in seconds) that will be used for a thumbnail. Default: `1` +* [`IMGPROXY_VIDEO_THUMBNAIL_KEYFRAMES`]: ((pro)) when `true`, imgproxy will use the latest keyframe before `IMGPROXY_VIDEO_THUMBNAIL_SECOND` for video thumbnail generation. This makes video thumbnail generation faster yet the used frame timestamp will not be exactly equal to the requested one. Default: `false` +* [`IMGPROXY_VIDEO_THUMBNAIL_TILE_AUTO_KEYFRAMES`]: ((pro)) when `true` and the `step` argument value of the `video_thumbnail_tile` processing option is greater than the interval between keyframes, imgproxy will use only keyframes. This allows to speed up `video_thumbnail_tile` for long steps between tiles yet keep it precise for short ones. Default: `false` +* [`IMGPROXY_VIDEO_THUMBNAIL_PROBE_SIZE`]: ((pro)) the maximum amount of bytes used to determine the format. Lower values can decrease memory usage but can produce inaccurate data, or even lead to errors. Default: 5000000 +* [`IMGPROXY_VIDEO_THUMBNAIL_MAX_ANALYZE_DURATION`]: ((pro)) the maximum number of milliseconds used to get the stream info. Lower values can decrease memory usage but can produce inaccurate data, or even lead to errors. When set to `0`, the heuristic is used. Default: `0` + +:::warning +Though using `IMGPROXY_VIDEO_THUMBNAIL_PROBE_SIZE` and `IMGPROXY_VIDEO_THUMBNAIL_MAX_ANALYZE_DURATION` can lower the memory footprint of video thumbnail generation, they should be used in production only when you know what you're doing. +::: + +## Watermark + +* [`IMGPROXY_WATERMARK_DATA`]: Base64-encoded image data. You can easily calculate it with `base64 tmp/watermark.png | tr -d '\n'`. +* [`IMGPROXY_WATERMARK_PATH`]: the path to the locally stored image +* [`IMGPROXY_WATERMARK_URL`]: the watermark image URL +* [`IMGPROXY_WATERMARK_PREPROCESS_URL`]: ((pro)) when `true`, imgproxy will apply `IMGPROXY_URL_REPLACEMENTS` and `IMGPROXY_BASE_URL` to values of the `watermark_url` processing option. +* [`IMGPROXY_WATERMARK_OPACITY`]: the watermark's base opacity +* [`IMGPROXY_WATERMARKS_CACHE_SIZE`]: ((pro)) custom watermarks cache size. When set to `0`, the watermark cache is disabled. 256 watermarks are cached by default. + +Read more about watermarks in the [Watermark](../features/watermark.mdx) guide. + +## Unsharp masking + +imgproxy Pro can apply unsharp masking to your images. + +* [`IMGPROXY_UNSHARP_MASKING_MODE`]: ((pro)) controls when unsharp masking should be applied. The following modes are supported: + * `auto`: _(default)_ apply unsharp masking only when an image is downscaled and the `sharpen` option has not been set. + * `none`: unsharp masking is not applied. + * `always`: always applies unsharp masking. +* [`IMGPROXY_UNSHARP_MASKING_WEIGHT`]: ((pro)) a floating-point number that defines how neighboring pixels will affect the current pixel. The greater the value, the sharper the image. This value should be greater than zero. Default: `1` +* [`IMGPROXY_UNSHARP_MASKING_DIVIDER`]: ((pro)) a floating-point number that defines unsharp masking strength. The lesser the value, the sharper the image. This value be greater than zero. Default: `24` + +## Smart crop + +* [`IMGPROXY_SMART_CROP_ADVANCED`]: ((pro)) when `true`, enables usage of the advanced smart crop method. Advanced smart crop may take more time than regular one, yet it produces better results. +* [`IMGPROXY_SMART_CROP_ADVANCED_MODE`]: ((pro)) the mode of the advanced smart crop method. Supported values are: + * `max_score_area`: _(default)_ in this mode, imgproxy builds a featres map and selects the area with the highest sum of feature scores. + * `center_of_mass`: in this mode, imgproxy calculates the center of mass of the features map and selects the area around it. +* [`IMGPROXY_SMART_CROP_FACE_DETECTION`]: ((pro)) when `true`, adds an additional fast face detection step to smart crop. + +## Object detection + +imgproxy can detect objects on the image and use them to perform smart cropping, to blur the detections, or to draw the detections. + +* [`IMGPROXY_OBJECT_DETECTION_NET`]: ((pro)) a path to the neural network model in ONNX format. Default: blank +* [`IMGPROXY_OBJECT_DETECTION_NET_TYPE`]: ((pro)) the type of the neural network model. Default: `yolox` +* [`IMGPROXY_OBJECT_DETECTION_CLASSES`]: ((pro)) the path to the text file with the classes names, one per line. Default: blank +* [`IMGPROXY_OBJECT_DETECTION_NET_SIZE`]: ((pro)) the size of the neural network input. The width and the heights of the inputs should be the same, so this config value should be a single number. Default: 416 +* [`IMGPROXY_OBJECT_DETECTION_CONFIDENCE_THRESHOLD`]: ((pro)) detections with confidences below this value will be discarded. Default: 0.2 +* [`IMGPROXY_OBJECT_DETECTION_NMS_THRESHOLD`]: ((pro)) non-max supression threshold. Don't change this if you don't know what you're doing. Default: 0.4 +* [`IMGPROXY_OBJECT_DETECTION_SWAP_RB`]: ((pro)) when set to `true`, imgproxy will swap the R and B channels in the input image. Some models are trained on BGR images and perform incorrectly with RGB inputs. This option allows you to fix this issue. Default: `false` +* [`IMGPROXY_OBJECT_DETECTION_FALLBACK_TO_SMART_CROP`]: ((pro)) defines imgproxy's behavior when object-oriented crop gravity is used but no objects are detected. When set to `true`, imgproxy will fallback to smart crop. When set to `false`, imgproxy will fallback to the center gravity. Default: `true` +* [`IMGPROXY_OBJECT_DETECTION_GRAVITY_MODE`]: ((pro)) defines how imgproxy should use object-oriented crop gravity. Supported values are: + * `max_score_area`: _(default)_ in this mode, imgproxy will select the area that covers the most detected objects, respecting their weights. + * `one_best`: in this mode, imgproxy will focus on the object with the highest score based on its area, confidence, and class weight. + * `one_best_centermost`: the same as `one_best,` but imgproxy will add the object's proximity to the image center to its score. + +Read the [Object Detection guide](../features/object_detection.mdx) for more info. + +## Classification + +imgproxy can classify images by assigning them to predefined categories based on their overall content, similar to object detection but without identifying or locating individual objects. + +* [`IMGPROXY_CLASSIFICATION_NET`]: ((pro)) a path to the classification neural network model in ONNX format. Default: blank +* [`IMGPROXY_CLASSIFICATION_CLASSES`]: ((pro)) the path to the text file with the class names, one per line. Default: blank +* [`IMGPROXY_CLASSIFICATION_NET_SIZE`]: ((pro)) the size of the neural network input. The width and the heights of the inputs should be the same, so this config value should be a single number. Default: 224 +* [`IMGPROXY_CLASSIFICATION_THRESHOLD`]: ((pro)) classifications with confidence below this value will be discarded. Default: 0.5 +* [`IMGPROXY_CLASSIFICATION_NORMALIZATION`]: ((pro)) the normalization type to apply to the input image. Possible values are: + * `none`: _(default)_ no normalization + * `half`: normalize to [0, 1] range + * `full`: normalize to [-1, 1] range + * `imagenet`: normalize using ImageNet mean and standard deviation +* [`IMGPROXY_CLASSIFICATION_LAYOUT`]: ((pro)) the data layout of the neural network input. Possible values are: + * `nhwc`: _(default)_ channels last (TensorFlow default) + * `nchw`: channels first (PyTorch default) + +Read the [Classification guide](../features/classification.mdx) for more info. + +## Cache + +imgproxy can cache processed images in various storage backends to improve performance and reduce processing overhead. + +* [`IMGPROXY_CACHE_USE`]: ((pro)) the cache storage adapter to use. Can be `fs`, `s3`, `gcs`, `abs` (Azure Blob Storage), or `swift` (OpenStack Swift). When blank, the cache is disabled. Default: blank +* [`IMGPROXY_CACHE_PATH_PREFIX`]: ((pro)) a path prefix for the cache files. This can be useful to organize cache files in a specific directory structure. Default: blank +* [`IMGPROXY_CACHE_BUCKET`]: ((pro)) the bucket name for cloud storage adapters (S3, GCS, ABS, OpenStack Swift). When using filesystem adapter, this can be used as an additional path component. Default: blank +* [`IMGPROXY_CACHE_KEY_HEADERS`]: ((pro)) a comma-separated list of HTTP request headers to include in the cache key. This allows caching different versions of the same image based on request headers. Default: blank +* [`IMGPROXY_CACHE_KEY_COOKIES`]: ((pro)) a comma-separated list of HTTP request cookies to include in the cache key. This allows caching different versions of the same image based on cookies. Default: blank +* [`IMGPROXY_CACHE_REPORT_ERRORS`]: ((pro)) when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` + +Read the [Internal cache guide](../cache/internal.mdx) for more info. + +### Local filesystem {#cache-storage-local-filesystem} + +imgproxy can store cached images on the local filesystem. To use [filesystem cache](../cache/internal/local_filesystem.mdx), set `IMGPROXY_CACHE_USE` to `fs`: + +* [`IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT`]: ((pro)) the root directory for filesystem cache. Default: blank + +See full documentation in [Cache storage: Local filesystem](../cache/internal/local_filesystem.mdx). + +### Amazon S3 {#cache-storage-amazon-s3} + +imgproxy can store cached images in Amazon S3 buckets or S3-compatible storage. To use [S3 cache](../cache/internal/amazon_s3.mdx), set `IMGPROXY_CACHE_USE` to `s3`: + +* [`IMGPROXY_CACHE_S3_REGION`]: ((pro)) the S3 region for the cache bucket +* [`IMGPROXY_CACHE_S3_ENDPOINT`]: ((pro)) a custom S3 endpoint for the cache. Useful for S3-compatible services like MinIO, Cloudflare R2, DigitalOcean Spaces, etc. Default: blank +* [`IMGPROXY_CACHE_S3_ENDPOINT_USE_PATH_STYLE`]: ((pro)) controls how the S3 bucket endpoint is constructed. When `true`, the endpoint will be constructed using the path style (`https://your-endpoint.com/%bucket`). When `false`, the endpoint will be constructed using the virtual host style (`https://%bucket.your-endpoint.com`). Default: `true` +* [`IMGPROXY_CACHE_S3_USE_DECRYPTION_CLIENT`]: ((pro)) when `true`, enables client-side decryption for cached objects. Default: `false` +* [`IMGPROXY_CACHE_S3_ASSUME_ROLE_ARN`]: ((pro)) the ARN of an IAM role to assume for cache access +* [`IMGPROXY_CACHE_S3_ASSUME_ROLE_EXTERNAL_ID`]: ((pro)) the external ID required to assume the IAM role for cache access + +:::info +Credentials for S3 cache can be provided using the same methods as for S3 image sources: IAM roles, `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables, or a shared credentials file. +::: + +### Google Cloud Storage {#cache-storage-google-cloud-storage} + +imgproxy can store cached images in Google Cloud Storage buckets. To use [GCS cache](../cache/internal/google_cloud_storage.mdx), set `IMGPROXY_CACHE_USE` to `gcs`: + +* [`IMGPROXY_CACHE_GCS_KEY`]: ((pro)) the Google Cloud JSON key for cache access. When running inside Google Cloud infrastructure, imgproxy will try to use the default service account credentials if this is not set. Default: blank +* [`IMGPROXY_CACHE_GCS_ENDPOINT`]: ((pro)) a custom Google Cloud Storage endpoint for cache. Default: blank + +### Azure Blob Storage {#cache-storage-azure-blob-storage} + +imgproxy can store cached images in Azure Blob Storage containers. To use [Azure cache](../cache/internal/azure_blob_storage.mdx), set `IMGPROXY_CACHE_USE` to `abs`: + +* [`IMGPROXY_CACHE_ABS_NAME`]: ((pro)) the Azure account name for cache storage. Default: blank +* [`IMGPROXY_CACHE_ABS_KEY`]: ((pro)) the Azure account key for cache storage. Default: blank +* [`IMGPROXY_CACHE_ABS_ENDPOINT`]: ((pro)) a custom Azure Blob Storage endpoint for cache. Default: blank + +:::info +Azure cache also supports authentication via Managed Identity or Service Principal using the same `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, and related environment variables as Azure Blob Storage image sources. +::: + +### OpenStack Swift {#cache-storage-openstack-swift} + +imgproxy can store cached images in OpenStack Object Storage (Swift). To use [Swift cache](../cache/internal/openstack_swift.mdx), set `IMGPROXY_CACHE_USE` to `swift`: + +* [`IMGPROXY_CACHE_SWIFT_USERNAME`]: ((pro)) the username for Swift API access for cache. Default: blank +* [`IMGPROXY_CACHE_SWIFT_API_KEY`]: ((pro)) the API key for Swift API access for cache. Default: blank +* [`IMGPROXY_CACHE_SWIFT_AUTH_URL`]: ((pro)) the Swift Auth URL for cache. Default: blank +* [`IMGPROXY_CACHE_SWIFT_AUTH_VERSION`]: ((pro)) the Swift auth version for cache. Set to 1, 2 or 3 or leave at 0 for autodetect. Default: 0 +* [`IMGPROXY_CACHE_SWIFT_TENANT`]: ((pro)) the tenant name for cache (optional, v2 auth only). Default: blank +* [`IMGPROXY_CACHE_SWIFT_DOMAIN`]: ((pro)) the Swift domain name for cache (optional, v3 auth only). Default: blank +* [`IMGPROXY_CACHE_SWIFT_TIMEOUT_SECONDS`]: ((pro)) the data channel timeout in seconds for cache operations. Default: 60 +* [`IMGPROXY_CACHE_SWIFT_CONNECT_TIMEOUT_SECONDS`]: ((pro)) the connect channel timeout in seconds for cache operations. Default: 10 + +## Fallback image + +You can set up a fallback image that will be used in case imgproxy is unable to fetch the requested one. Use one of the following variables: + +* [`IMGPROXY_FALLBACK_IMAGE_DATA`]: Base64-encoded image data. You can easily calculate it with `base64 tmp/fallback.png | tr -d '\n'`. +* [`IMGPROXY_FALLBACK_IMAGE_PATH`]: the path to the locally stored image +* [`IMGPROXY_FALLBACK_IMAGE_URL`]: the fallback image URL +* [`IMGPROXY_FALLBACK_IMAGE_PREPROCESS_URL`]: ((pro)) when `true`, imgproxy will apply `IMGPROXY_URL_REPLACEMENTS` and `IMGPROXY_BASE_URL` to values of the `fallback_image_url` processing option. +* [`IMGPROXY_FALLBACK_IMAGE_HTTP_CODE`]: the HTTP code for the fallback image response. When set to zero, imgproxy will respond with the usual HTTP code. Default: `200` +* [`IMGPROXY_FALLBACK_IMAGE_TTL`]: a duration (in seconds) sent via the `Cache-Control: max-age` HTTP header when a fallback image was used. When blank or `0`, the value from `IMGPROXY_TTL` is used. +* [`IMGPROXY_FALLBACK_IMAGES_CACHE_SIZE`]: ((pro)) the size of custom fallback images cache. When set to `0`, the fallback image cache is disabled. 256 fallback images are cached by default. + +## Presets + +Read more about imgproxy presets in the [Presets](../usage/presets.mdx) guide. + +There are two ways to define presets: + +#### Using an environment variable + +* [`IMGPROXY_PRESETS`]: a set of processing preset definitions, comma divided. Example: `default=resizing_type:fill/enlarge:1,sharp=sharpen:0.7,blurry=blur:2`. Default: blank +* [`IMGPROXY_INFO_PRESETS`]: ((pro)) a set of info preset definitions, comma divided. Example: `default=xmp:0/blurhash:4:3`. Default: blank +* [`IMGPROXY_PRESETS_SEPARATOR`]: a string that will be used as a presets' separator. Default: `,` +* [`IMGPROXY_PRESETS_PATH`]: the path to the file with processing preset definitions. Default: blank + + The file should contain processing preset definitions, one per line. Lines starting with `#` are treated as comments. Example: + + ```imgproxy_presets + default=resizing_type:fill/enlarge:1 + + # Sharpen the image to make it look better + sharp=sharpen:0.7 + + # Blur the image to hide details + blurry=blur:2 + ``` +* [`IMGPROXY_INFO_PRESETS_PATH`]: ((pro)) the path to the file with info preset definitions. Default: blank + + The file should contain info preset definitions, one per line. Lines starting with `#` are treated as comments. Example: + + ```imgproxy_presets + default=xmp:0/blurhash:4:3 + + # Detect objects on the image + with_objects=detect_objects:1 + ``` + +### Using only presets + +imgproxy can be switched into "presets-only mode". In this mode, imgproxy accepts only `preset` option arguments as processing options. Example: `http://imgproxy.example.com/unsafe/thumbnail:blurry:watermarked/plain/http://example.com/images/curiosity.jpg@png` + +* [`IMGPROXY_ONLY_PRESETS`]: when `true`, enables presets-only mode. Default: `false` +* [`IMGPROXY_INFO_ONLY_PRESETS`]: when `true`, enables presets-only mode for the [info](../usage/getting_info.mdx) endpoint. Default: `IMGPROXY_ONLY_PRESETS` value + +## Image sources + +* [`IMGPROXY_SOURCE_URL_QUERY_SEPARATOR`]: a string that will be used as a separator between non-HTTP(S) source URLs' paths and their query strings. When blank, imgproxy won't extract query string from non-HTTP(S) source URLs. Default: `?` + +:::tip +If filenames in your S3/Google Cloud Storage/local filesystem/etc may contain `?`, you may want to set `IMGPROXY_SOURCE_URL_QUERY_SEPARATOR` to another string that is not used in filenames or set it to blank to disable query string extraction. +::: + +### Local files {#serving-local-files} + +imgproxy can serve your local images, but this feature is disabled by default. To enable it, specify your local filesystem root: + +* [`IMGPROXY_LOCAL_FILESYSTEM_ROOT`]: the root of the local filesystem. Keep this empty to disable local file serving. + +Check out the [Serving local files](../image_sources/local_files.mdx) guide to learn more. + +### Amazon S3 {#serving-files-from-amazon-s3} + +imgproxy can process files from Amazon S3 buckets, but this feature is disabled by default. To enable it, set `IMGPROXY_USE_S3` to `true`: + +* [`IMGPROXY_USE_S3`]: when `true`, enables image fetching from Amazon S3 buckets. Default: `false` +* [`IMGPROXY_S3_REGION`]: an S3 buckets region +* [`IMGPROXY_S3_ENDPOINT`]: a custom S3 endpoint to being used by imgproxy +* [`IMGPROXY_S3_ENDPOINT_USE_PATH_STYLE`]: controls how the S3 bucket endpoint is constructed. When `true`, the endpoint will be constructed using the path style (`https://your-endpoint.com/%bucket`). When `false`, the endpoint will be constructed using the virtual host style (`https://%bucket.your-endpoint.com`). Default: `true` +* [`IMGPROXY_S3_USE_DECRYPTION_CLIENT`]: when `true`, enables client-side decryption. Default: `false` +* [`IMGPROXY_S3_ASSUME_ROLE_ARN`]: a custom role to assume +* [`IMGPROXY_S3_ASSUME_ROLE_EXTERNAL_ID`]: the external ID required to assume a custom role +* [`IMGPROXY_S3_ALLOWED_BUCKETS`]: a comma-separated list of S3 bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed) +* [`IMGPROXY_S3_DENIED_BUCKETS`]: a comma-separated list of S3 bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank + +Check out the [Serving files from S3](../image_sources/amazon_s3.mdx) guide to learn more. + +### Google Cloud Storage {#serving-files-from-google-cloud-storage} + +imgproxy can process files from Google Cloud Storage buckets, but this feature is disabled by default. To enable it, set the value of `IMGPROXY_USE_GCS` to `true`: + +* [`IMGPROXY_USE_GCS`]: when `true`, enables image fetching from Google Cloud Storage buckets. Default: `false` +* [`IMGPROXY_GCS_KEY`]: the Google Cloud JSON key. Default: blank +* [`IMGPROXY_GCS_ENDPOINT`]: a custom Google Cloud Storage endpoint to being used by imgproxy +* [`IMGPROXY_GCS_ALLOWED_BUCKETS`]: a comma-separated list of GCS bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed) +* [`IMGPROXY_GCS_DENIED_BUCKETS`]: a comma-separated list of GCS bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank + +Check out the [Serving files from Google Cloud Storage](../image_sources/google_cloud_storage.mdx) guide to learn more. + +### Azure Blob Storage {#serving-files-from-azure-blob-storage} + +imgproxy can process files from Azure Blob Storage containers, but this feature is disabled by default. To enable it, set `IMGPROXY_USE_ABS` to `true`: + +* [`IMGPROXY_USE_ABS`]: when `true`, enables image fetching from Azure Blob Storage containers. Default: `false` +* [`IMGPROXY_ABS_NAME`]: the Azure account name. Default: blank +* [`IMGPROXY_ABS_KEY`]: the Azure account key. Default: blank +* [`IMGPROXY_ABS_ENDPOINT`]: the custom Azure Blob Storage endpoint to be used by imgproxy. Default: blank +* [`IMGPROXY_ABS_ALLOWED_BUCKETS`]: a comma-separated list of Azure Blob Storage container names that imgproxy is allowed to access. When set, imgproxy will only process images from these containers. Default: blank (all containers allowed) +* [`IMGPROXY_ABS_DENIED_BUCKETS`]: a comma-separated list of Azure Blob Storage container names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these containers. Default: blank + +Check out the [Serving files from Azure Blob Storage](../image_sources/azure_blob_storage.mdx) guide to learn more. + +### OpenStack Object Storage ("Swift") {#serving-files-from-openstack-object-storage-swift} + +imgproxy can process files from OpenStack Object Storage, but this feature is disabled by default. To enable it, set `IMGPROXY_USE_SWIFT` to `true`. +* [`IMGPROXY_USE_SWIFT`]: when `true`, enables image fetching from OpenStack Swift Object Storage. Default: `false` +* [`IMGPROXY_SWIFT_USERNAME`]: the username for Swift API access. Default: blank +* [`IMGPROXY_SWIFT_API_KEY`]: the API key for Swift API access. Default: blank +* [`IMGPROXY_SWIFT_AUTH_URL`]: the Swift Auth URL. Default: blank +* [`IMGPROXY_SWIFT_AUTH_VERSION`]: the Swift auth version, set to 1, 2 or 3 or leave at 0 for autodetect. +* [`IMGPROXY_SWIFT_TENANT`]: the tenant name (optional, v2 auth only). Default: blank +* [`IMGPROXY_SWIFT_DOMAIN`]: the Swift domain name (optional, v3 auth only): Default: blank +* [`IMGRPOXY_SWIFT_TIMEOUT_SECONDS`]: the data channel timeout in seconds. Default: 60 +* [`IMGRPOXY_SWIFT_CONNECT_TIMEOUT_SECONDS`]: the connect channel timeout in seconds. Default: 10 +* [`IMGPROXY_SWIFT_ALLOWED_BUCKETS`]: a comma-separated list of Swift container names that imgproxy is allowed to access. When set, imgproxy will only process images from these containers. Default: blank (all containers allowed) +* [`IMGPROXY_SWIFT_DENIED_BUCKETS`]: a comma-separated list of Swift container names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these containers. Default: blank + +Check out the [Serving files from OpenStack Object Storage](../image_sources/openstack_swift.mdx) guide to learn more. + +## Source image URLs + +* [`IMGPROXY_BASE_URL`]: a base URL prefix that will be added to each source image URL. For example, if the base URL is `http://example.com/images` and `/path/to/image.png` is requested, imgproxy will download the source image from `http://example.com/images/path/to/image.png`. If the image URL already contains the prefix, it won't be added. Default: blank + +* [`IMGPROXY_URL_REPLACEMENTS`]: a list of `pattern=replacement` pairs, semicolon (`;`) divided. imgproxy will replace source URL prefixes matching the pattern with the corresponding replacement. Wildcards can be included in patterns with `*` to match all characters except `/`. `${N}` in replacement strings will be replaced with wildcard values, where `N` is the number of the wildcard. Examples: + * `mys3://=s3://my_bucket/images/` will replace `mys3://image01.jpg` with `s3://my_bucket/images/image01.jpg` + * `mys3://*/=s3://my_bucket/${1}/images` will replace `mys3://items/image01.jpg` with `s3://my_bucket/items/images/image01.jpg` + +:::info +Replacements defined in `IMGPROXY_URL_REPLACEMENTS` are applied before `IMGPROXY_BASE_URL` is added. +::: + +* [`IMGPROXY_BASE64_URL_INCLUDES_FILENAME`]: when `true` and the source image URL is Base64-encoded or encrypted, imgproxy will treat the part after the last slash (`/`) as an SEO-friendly filename and will discard it when decoding the URL. Default: `false` + +:::tip +For example, if you have `IMGPROXY_BASE64_URL_INCLUDES_FILENAME` enabled and want to add a `puppy.jpg` filename to your imgproxy URL for SEO reasons, the URL will look like this: + +``` +https://my-imgproxy.dev/.../aHR0cDovL2V4YW1wbGUuY29tL3B1cHB5LmpwZw/puppy.jpg +``` + +imgproxy will treat `puppy.jpg` as an SEO-friendly filename and will use `aHR0cDovL2V4YW1wbGUuY29tL3B1cHB5LmpwZw` as a Base64-encoded source URL. +::: + +## Metrics + +### New Relic {#new-relic-metrics} + +imgproxy can send its metrics to New Relic. Specify your New Relic license key to activate this feature: + +* [`IMGPROXY_NEW_RELIC_KEY`]: the New Relic license key +* [`IMGPROXY_NEW_RELIC_APP_NAME`]: a New Relic application name. Default: `imgproxy` +* [`IMGPROXY_NEW_RELIC_LABELS`]: the list of New Relic labels, semicolon divided. Example: `label1=value1;label2=value2`. Default: blank +* [`IMGPROXY_NEW_RELIC_PROPAGATE_EXTERNAL`]: when `true`, imgproxy will propagate New Relic tracing headers to external requests such as image downloads. Default: `false` + +Check out the [New Relic](../monitoring/new_relic.mdx) guide to learn more. + +### Prometheus {#prometheus-metrics} + +imgproxy can collect its metrics for Prometheus. Specify a binding for Prometheus metrics server to activate this feature: + +* [`IMGPROXY_PROMETHEUS_BIND`]: Prometheus metrics server binding. Can't be the same as `IMGPROXY_BIND`. Default: blank +* [`IMGPROXY_PROMETHEUS_NAMESPACE`]: Namespace (prefix) for imgproxy metrics. Default: blank + +Check out the [Prometheus](../monitoring/prometheus.mdx) guide to learn more. + +### Datadog {#datadog-metrics} + +imgproxy can send its metrics to Datadog: + +* [`IMGPROXY_DATADOG_ENABLE`]: when `true`, enables sending metrics to Datadog. Default: false +* [`IMGPROXY_DATADOG_ENABLE_ADDITIONAL_METRICS`]: when `true`, enables sending the additional metrics to Datadog. Default: false +* [`IMGPROXY_DATADOG_PROPAGATE_EXTERNAL`]: when `true`, imgproxy will propagate Datadog tracing headers to external requests such as image downloads. Default: `false` + +:::warning +Since the additional metrics are treated by Datadog as custom, Datadog can additionally bill you for their usage. Please, check out Datadog's [Custom Metrics Billing](https://docs.datadoghq.com/account_management/billing/custom_metrics/) page for additional details. +::: + +Check out the [Datadog](../monitoring/datadog.mdx) guide to learn more. + +### OpenTelemetry {#opentelemetry-metrics} + +imgproxy can send request traces to an OpenTelemetry collector: + +* [`IMGPROXY_OPEN_TELEMETRY_ENABLE`]: when `true`, enables sending request traces to OpenTelemetry collector. Default: false +* [`IMGPROXY_OPEN_TELEMETRY_ENABLE_METRICS`]: when `true`, imgproxy will send metrics over OpenTelemetry Metrics API. Default: `false` +* [`IMGPROXY_OPEN_TELEMETRY_ENABLE_LOGS`]: when `true`, imgproxy will send logs to OpenTelemetry collector. Default: `false` +* [`IMGPROXY_OPEN_TELEMETRY_SERVER_CERT`]: OpenTelemetry collector TLS certificate, PEM-encoded (you can replace line breaks with `\n`). Default: blank +* [`IMGPROXY_OPEN_TELEMETRY_CLIENT_CERT`]: OpenTelemetry client TLS certificate, PEM-encoded (you can replace line breaks with `\n`). Default: blank +* [`IMGPROXY_OPEN_TELEMETRY_CLIENT_KEY`]: OpenTelemetry client TLS key, PEM-encoded (you can replace line breaks with `\n`). Default: blank +* [`IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR`]: OpenTelemetry trace ID generator. Supported generators are `xray` and `random`. Default: `xray` +* [`IMGPROXY_OPEN_TELEMETRY_PROPAGATE_EXTERNAL`]: when `true`, imgproxy will propagate OpenTelemetry tracing headers to external requests such as image downloads. Default: `false` + +Check out the [OpenTelemetry](../monitoring/open_telemetry.mdx) guide to learn more. + +### Amazon CloudWatch metrics {#amazon-cloudwatch-metrics} + +imgproxy can send its metrics to Amazon CloudWatch. Specify a desired `ServiceName` dimesion value to activate this feature: + +* [`IMGPROXY_CLOUD_WATCH_SERVICE_NAME`]: the value of the `ServiceName` dimension which will be used in the metrics. Default: blank +* [`IMGPROXY_CLOUD_WATCH_NAMESPACE`]: the CloudWatch namespace for the metrics +* [`IMGPROXY_CLOUD_WATCH_REGION`]: the code of the AWS region to which the metrics should be sent + +Check out the [CloudWatch](../monitoring/cloud_watch.mdx) guide to learn more. + +## Error reporting + +imgproxy can report occurred errors to Bugsnag, Honeybadger and Sentry: + +* [`IMGPROXY_REPORT_DOWNLOADING_ERRORS`]: when `true`, imgproxy will report downloading errors. Default: `true` +* [`IMGPROXY_DEVELOPMENT_ERRORS_MODE`]: when `true`, imgproxy will respond with detailed error messages and stack traces in a pretty HTML format. Useful for development and debugging. If the client does not `Accept: text/html`, imgproxy reponds with plain text error. Default: `false` + +### Bugsnag + +* [`IMGPROXY_BUGSNAG_KEY`]: Bugsnag API key. When provided, enables error reporting to Bugsnag. +* [`IMGPROXY_BUGSNAG_STAGE`]: the Bugsnag stage to report to. Default: `production` + +### Honeybadger + +* [`IMGPROXY_HONEYBADGER_KEY`]: the Honeybadger API key. When provided, enables error reporting to Honeybadger. +* [`IMGPROXY_HONEYBADGER_ENV`]: the Honeybadger env to report to. Default: `production` + +### Sentry + +* [`IMGPROXY_SENTRY_DSN`]: Sentry project DSN. When provided, enables error reporting to Sentry. +* [`IMGPROXY_SENTRY_ENVIRONMENT`]: the Sentry environment to report to. Default: `production` +* [`IMGPROXY_SENTRY_RELEASE`]: the Sentry release to report to. Default: `imgproxy@{imgproxy version}` + +### Airbrake + +* [`IMGPROXY_AIRBRAKE_PROJECT_ID`]: an Airbrake project id +* [`IMGPROXY_AIRBRAKE_PROJECT_KEY`]: an Airbrake project key +* [`IMGPROXY_AIRBRAKE_ENVIRONMENT`]: the Airbrake environment to report to. Default: `production` + +## Log + +* [`IMGPROXY_LOG_FORMAT`]: the log format. The following formats are supported: + * `pretty`: _(default)_ colored human-readable format + * `structured`: machine-readable format + * `json`: JSON format + * `gcp`: Google Cloud Logging agent compliant format +* [`IMGPROXY_LOG_LEVEL`]: the log level. The following levels are supported `error`, `warn`, `info` and `debug`. Default: `info` + +imgproxy can send logs to syslog, but this feature is disabled by default. To enable it, set `IMGPROXY_SYSLOG_ENABLE` to `true`: + +* [`IMGPROXY_SYSLOG_ENABLE`]: when `true`, enables sending logs to syslog. +* [`IMGPROXY_SYSLOG_LEVEL`]: the maximum log level to send to syslog. Known levels are: `crit`, `error`, `warning` and `info`. Default: `info` +* [`IMGPROXY_SYSLOG_NETWORK`]: the network that will be used to connect to syslog. When blank, the local syslog server will be used. Known networks are `tcp`, `tcp4`, `tcp6`, `udp`, `udp4`, `udp6`, `ip`, `ip4`, `ip6`, `unix`, `unixgram` and `unixpacket`. Default: blank +* [`IMGPROXY_SYSLOG_ADDRESS`]: the address of the syslog service. Not used if `IMGPROXY_SYSLOG_NETWORK` is blank. Default: blank +* [`IMGPROXY_SYSLOG_TAG`]: the specific syslog tag. Default: `imgproxy` + +:::info +imgproxy always uses structured log format for syslog. +::: + +## Licensing + +* [`IMGPROXY_LICENSE_KEY`]: ((pro)) the imgproxy Pro license key. When not provided, imgproxy Pro will run in development mode with a limit of 100 requests per minute. Default: blank +* [`IMGPROXY_LICENSE_DEVELOPMENT_MODE`]: ((pro)) when `true`, enables development mode even if `IMGPROXY_LICENSE_KEY` is provided. In development mode, imgproxy Pro will run with a limit of 100 requests per minute but won't meter the license usage. Default: `false` + +:::info +If you bought imgproxyPro in a cloud marketplace (like AWS Marketplace), you don't need to set `IMGPROXY_LICENSE_KEY`. You can still use `IMGPROXY_LICENSE_DEVELOPMENT_MODE` to enable development mode for local testing. +::: + +## Memory usage tweaks + +:::danger +We highly recommended reading the [Memory usage tweaks](../memory_usage_tweaks.mdx) guide before changing these settings. +::: + +* [`IMGPROXY_DOWNLOAD_BUFFER_SIZE`]: the initial size (in bytes) of a single download buffer. When set to zero, initializes empty download buffers. Default: `0` +* [`IMGPROXY_FREE_MEMORY_INTERVAL`]: the interval (in seconds) at which unused memory will be returned to the OS. Default: `10` +* [`IMGPROXY_BUFFER_POOL_CALIBRATION_THRESHOLD`]: the number of buffers that should be returned to a pool before calibration. Default: `1024` +* [`IMGPROXY_MALLOC`]: _(Docker only)_ malloc implementation to use. The following implementations are supported: + * `malloc`: standard malloc implementation + * `jemalloc`: https://jemalloc.net/ + * `tcmalloc`: https://github.com/google/tcmalloc + +## Miscellaneous + +* [`IMGPROXY_ARGUMENTS_SEPARATOR`]: a string that will be used as a processing/info options arguments' separator. Default: `:` +* [`IMGPROXY_USE_LINEAR_COLORSPACE`]: when `true`, imgproxy will process images in linear colorspace. This will slow down processing. Note that images won't be fully processed in linear colorspace while shrink-on-load is enabled (see below). +* [`IMGPROXY_DISABLE_SHRINK_ON_LOAD`]: when `true`, disables shrink-on-load for JPEGs and WebP files. Allows processing the entire image in linear colorspace but dramatically slows down resizing and increases memory usage when working with large images. +* [`IMGPROXY_PDF_NO_BACKGROUND`]: ((pro)) when `true`, imgproxy will not add a white background to the PDF pages. Default: `false` +* [`IMGPROXY_STRIP_METADATA`]: when `true`, imgproxy will strip the output images' metadata (EXIF, IPTC, etc.). Default: `true` +* [`IMGPROXY_KEEP_COPYRIGHT`]: when `true`, imgproxy will not remove copyright info while stripping metadata. Default: `true` +* [`IMGPROXY_STRIP_METADATA_DPI`]: ((pro)) the DPI metadata value that should be set for the image when its metadata is stripped. Default: `72.0` +* [`IMGPROXY_STRIP_COLOR_PROFILE`]: when `true`, imgproxy will transform the embedded color profile (ICC) to sRGB and remove it from the image. Otherwise, imgproxy will try to keep it as is. Default: `true` +* [`IMGPROXY_COLOR_PROFILES_DIR`]: ((pro)) the path to the directory containing color profiles that can be used with the [color_profile](../usage/processing.mdx#color-profile) processing option. Default: `/usr/share/color/icc` +* [`IMGPROXY_AUTO_ROTATE`]: when `true`, imgproxy will automatically rotate images based on the EXIF Orientation parameter (if available in the image meta data). The orientation tag will be removed from the image in all cases. Default: `true` +* [`IMGPROXY_ENFORCE_THUMBNAIL`]: when `true` and the source image has an embedded thumbnail, imgproxy will always use the embedded thumbnail instead of the main image. Currently, only thumbnails embedded in `heic` and `avif` are supported. Default: `false` +* [`IMGPROXY_RETURN_ATTACHMENT`]: when `true`, response header `Content-Disposition` will include `attachment`. Default: `false` +* [`IMGPROXY_HEALTH_CHECK_MESSAGE`]: ((pro)) the content of the health check response. Default: `imgproxy is running` +* [`IMGPROXY_HEALTH_CHECK_PATH`]: an additional path of the health check. Default: blank +* [`IMGPROXY_FAIL_ON_DEPRECATION`]: when `true`, imgproxy will exit with a fatal error if a deprecated config option is used. Default: `false` diff --git a/versioned_docs/version-4-preview/features/autoquality.mdx b/versioned_docs/version-4-preview/features/autoquality.mdx new file mode 100644 index 0000000..972edc8 --- /dev/null +++ b/versioned_docs/version-4-preview/features/autoquality.mdx @@ -0,0 +1,139 @@ +--- +title: Autoquality +description: Learn about how to automatically pick quality for your resultant images with imgproxy +--- + +# Autoquality ((pro)) + +imgproxy can calculate quality for your resultant images so they best fit the selected metric. The supported methods are [none](#none), [size](#autoquality-by-file-size), [dssim](#autoquality-by-dssim), and [ml](#autoquality-with-ml). + +:::warning +Autoquality requires an image to be saved several times. Use it only when you prefer the resultant quality and size over speed. +::: + +You can enable autoquality using [configuration options](../configuration/options.mdx#autoquality) (for all images) or with [processing options](../usage/processing.mdx#autoquality) (for each image individually). + +## None + +Disable the autoquality. + +**Method name:** `none` + +### Config example + +```bash +IMGPROXY_AUTOQUALITY_METHOD="none" +``` + +### Processing options example + +```imgproxy_url +.../autoquality:none/... +``` + +## Autoquality by file size + +With this method, imgproxy will try to degrade the quality so your image fits the desired file size. + +**Method name:** `size` + +**Target:** the desired file size + +### Config example + +```bash +IMGPROXY_AUTOQUALITY_METHOD="size" +# Change value to the desired size in bytes +IMGPROXY_AUTOQUALITY_TARGET=10240 +IMGPROXY_AUTOQUALITY_MIN=10 +IMGPROXY_AUTOQUALITY_MAX=80 +# Quality 63 for AVIF is pretty the same as 80 for JPEG +IMGPROXY_AUTOQUALITY_FORMAT_MAX="avif=65" +``` + +### Processing options example + +```imgproxy_url +.../autoquality:size:10240:10:80/... +``` + +## Autoquality by DSSIM + +With this method imgproxy will try to select a level of quality so that the saved image will have the desired [DSSIM](https://en.wikipedia.org/wiki/Structural_similarity#Structural_Dissimilarity) value. + +**Method name:** `dssim` + +**Target:** the desired DSSIM value + +### Config example + +```bash +IMGPROXY_AUTOQUALITY_METHOD="dssim" +# Change value to the desired DSSIM +IMGPROXY_AUTOQUALITY_TARGET=0.02 +# We're happy enough if the resulting DSSIM will differ from the desired by 0.001 +IMGPROXY_AUTOQUALITY_ALLOWED_ERROR=0.001 +IMGPROXY_AUTOQUALITY_MIN=70 +IMGPROXY_AUTOQUALITY_MAX=80 +# Quality 63 for AVIF is pretty the same as 80 for JPEG +IMGPROXY_AUTOQUALITY_FORMAT_MIN="avif=60" +IMGPROXY_AUTOQUALITY_FORMAT_MAX="avif=65" +``` + +### Processing options example + +```imgproxy_url +.../autoquality:dssim:0.02:70:80:0.001/... +``` + +## Autoquality with ML + +This method is almost the same as autoquality with [DSSIM](#autoquality-by-dssim) but imgproxy will try to predict the initial quality using neural networks. This requires neural networks to be configured (see the config examlpe or the config documentation). If a neural network for the resulting format is not provided, the [DSSIM](#autoquality-by-dssim) method will be used instead. + +:::info +When this method is used, imgproxy will save JPEG images with the most optimal [advanced JPEG compression](../configuration/options.mdx#advanced-jpeg-compression) settings, ignoring config and processing options. +::: + +**Method name:** `ml` + +**Target:** the desired DSSIM value + +### Config example + +```bash +IMGPROXY_AUTOQUALITY_METHOD="ml" +# Change value to the desired DSSIM +IMGPROXY_AUTOQUALITY_TARGET=0.02 +# We're happy enough if the resulting DSSIM will differ from the desired by 0.001 +IMGPROXY_AUTOQUALITY_ALLOWED_ERROR=0.001 +IMGPROXY_AUTOQUALITY_MIN=70 +IMGPROXY_AUTOQUALITY_MAX=80 +# Quality 63 for AVIF is pretty the same as 80 for JPEG +IMGPROXY_AUTOQUALITY_FORMAT_MIN="avif=60" +IMGPROXY_AUTOQUALITY_FORMAT_MAX="avif=65" +# Neural networks paths for JPEG, WebP, AVIF, and JPEG XL +IMGPROXY_AUTOQUALITY_JPEG_NET="/networks/autoquality-jpeg.pb" +IMGPROXY_AUTOQUALITY_WEBP_NET="/networks/autoquality-webp.pb" +IMGPROXY_AUTOQUALITY_AVIF_NET="/networks/autoquality-avif.pb" +IMGPROXY_AUTOQUALITY_JXL_NET="/networks/autoquality-jxl.pb" +``` + +:::info +If you trust your neural network's autoquality, you may want to set `IMGPROXY_AUTOQUALITY_ALLOWED_ERROR` to 1 (the maximum possible DSSIM value). In this case, imgproxy will always use the quality predicted by the neural network. +::: + +### Processing options example + +```imgproxy_url +.../autoquality:ml:0.02:70:80:0.001/... +``` + +## Neural networks format + +Neural networks should fit the following requirements: +* Tensorflow frozen graph format +* Input layer size is 416x416 +* Output layer size is 1x100 +* Output layer values are logits of quality probabilities + +If you're an imgproxy Pro user and you want to train your own network but you don't know how, feel free to contact the imgproxy team for instructions. diff --git a/versioned_docs/version-4-preview/features/best_format.mdx b/versioned_docs/version-4-preview/features/best_format.mdx new file mode 100644 index 0000000..e55e033 --- /dev/null +++ b/versioned_docs/version-4-preview/features/best_format.mdx @@ -0,0 +1,29 @@ +--- +title: Best format +description: Learn about how to automatically pick the best format for your resultant images with imgproxy +--- + +# Best format ((pro)) + +You can use the `best` value for the [format](../usage/processing.mdx#format) option or the [extension](../usage/processing.mdx#extension) to make imgproxy pick the best format for the resultant image. + +imgproxy measures the complexity of the image to choose when it should use a lossless or near-lossless encoding. Then imgproxy tries to save the image in multiple formats to pick one with the smallest resulting size. + +:::info +imgproxy uses only the formats listed as [preferred](../configuration/options.mdx#preferred-formats) when choosing the best format. It may also use AVIF, WebP, or JPEG XL if [AVIF/WebP/JPEG XL support detection](../configuration/options.mdx#avifwebpjpeg-xl-support-detection) is enabled. +::: + +:::info +imgproxy will use AVIF, WebP, or JPEG XL _only_ if [AVIF/WebP/JPEG XL support detection](../configuration/options.mdx#avifwebpjpeg-xl-support-detection) is enabled. +::: + +:::info +imgproxy may change your quality and autoquality settings if the `best` format is used. +::: + +## Configuration + +* `IMGPROXY_BEST_FORMAT_COMPLEXITY_THRESHOLD `: the image complexity threshold. imgproxy will use a lossless or near-lossless encoding for images with low complexity. Default: `5.5` +* `IMGPROXY_BEST_FORMAT_MAX_RESOLUTION`: when greater than `0` and the image's resolution (in megapixels) is larger than the provided value, imgproxy won't try all the applicable formats and will just pick one that seems the best for the image +* `IMGPROXY_BEST_FORMAT_BY_DEFAULT`: when `true` and the resulting image format is not specified explicitly, imgproxy will use the `best` format instead of the source image format +* `IMGPROXY_BEST_FORMAT_ALLOW_SKIPS`: when `true` and the `best` format is used, imgproxy will skip processing of SVG and formats [listed to skip processing](../configuration/options.mdx#skip-processing) diff --git a/versioned_docs/version-4-preview/features/chained_pipelines.mdx b/versioned_docs/version-4-preview/features/chained_pipelines.mdx new file mode 100644 index 0000000..a5a04f8 --- /dev/null +++ b/versioned_docs/version-4-preview/features/chained_pipelines.mdx @@ -0,0 +1,63 @@ +--- +title: Chained pipelines +description: Learn about how to connect multiple processing pipelines with imgproxy +--- + +# Chained pipelines ((pro)) + +Though imgproxy's [processing pipeline](../about_processing_pipeline.mdx) is suitable for most cases, sometimes it's handy to run multiple chained pipelines with different options. + +imgproxy Pro allows you to start a new pipeline by inserting a section with a minus sign (`-`) to the URL path: + +```imgproxy_url +.../width:500/crop:1000/-/trim:10/... + ^ the new pipeline starts here +``` + +### Example 1: Multiple watermarks + +If you need to place multiple watermarks on the same image, you can use chained pipelines for that: + +```imgproxy_url +.../rs:fit:500:500/wm:0.5:nowe/wmu:aW1hZ2UxCg/-/wm:0.7:soea/wmu:aW1hZ2UyCg/... +``` + +In this example, the first pipeline resizes the image and places the first watermark, and the second pipeline places the second watermark. + +### Example 2: Fast trim + +Performing the `trim` operation is pretty heavy as it involves loading the entire image into memory from the very start of processing. However, if you're going to scale down your image and trim accuracy is not very important to you, it's better to move trimming to a separate pipeline. + +```imgproxy_url +.../rs:fit:500:500/-/trim:10/... +``` + +In this example, the first pipeline resizes the image, and the second pipeline trims the result. Since the result of the first pipeline is already resized and loaded to the memory, trimming will be done much faster. + +## Using with presets + +You can use presets in your chained pipelines, and you can use chained pipelines in your presets. However, the behaior may be not obvious. The rules are the following: + +* A preset is applied to the pipeline where is was used. +* A preset may contain a chained pipeline, and will be chained to the pipeline where the preset was used. +* Chained pipelines from the preset and from the URL are merged. + +### Example + +If we have the following preset: + +```imgproxy_presets +test=width:300/height:300/-/width:200/height:200/-/width:100/height:200 +``` + +And the following URL: + +```imgproxy_url +.../width:400/-/preset:test/width:500/-/width:600/... +``` + +The result will look like this: + +```imgproxy_url +.../width:400/-/width:500/height:300/-/width:600/height:200/-/width:100/height:200/... +``` diff --git a/docs/features/classification.mdx b/versioned_docs/version-4-preview/features/classification.mdx similarity index 100% rename from docs/features/classification.mdx rename to versioned_docs/version-4-preview/features/classification.mdx diff --git a/versioned_docs/version-4-preview/features/object_detection.mdx b/versioned_docs/version-4-preview/features/object_detection.mdx new file mode 100644 index 0000000..22818c4 --- /dev/null +++ b/versioned_docs/version-4-preview/features/object_detection.mdx @@ -0,0 +1,341 @@ +--- +title: Object detection +description: Learn about how to detect objects in your images and use them with imgproxy +--- + +# Object detection ((pro)) + +imgproxy can detect objects in the image and use them for smart cropping, blurring the detections, drawing the detections, or cropping to detected objects. You can also [fetch the detected objects info](../usage/getting_info.mdx#detect-objects). + +For object purposes, imgproxy uses the YOLO (You Only Look Once) model family. imgproxy supports models in ONNX format. We provide Docker images with a model trained for face detection, but you can use any YOLO model found on the internet or train your own model. + +## Configuration + +:::tip +You don't need to configure object detection if you're using an imgproxy Pro Docker image with a tag suffixed with `-ml` and you want to use the face detection model. The model is already included in the image and the configuration is already set up. +::: + +You need to define the following config variables to enable object detection with an ONNX model: + +* [`IMGPROXY_OBJECT_DETECTION_NET`]: a path to the neural network model in ONNX format +* [`IMGPROXY_OBJECT_DETECTION_NET_TYPE`]: the type of the neural network model. Possible values: + * `yolox`: _(default)_ [YOLOX](https://github.com/Megvii-BaseDetection/YOLOX) model +
+ Export YOLOX to ONNX + + ```bash + python tools/export_onnx.py \ + -f /path/to/experiment.py \ + -c /path/to/checkpoint.pth \ + --output-name /path/to/output.onnx \ + --decode_in_inference + ``` +
+ * `yolov4`: [YOLOv4](https://github.com/Tianxiaomo/pytorch-YOLOv4) model +
+ Export YOLOv4 to ONNX + + ```bash + pip install onnxruntime + + python demo_pytorch2onnx.py + + # Example + python demo_pytorch2onnx.py yolov4.pth dog.jpg 1 80 416 416 + ``` +
+ * `yolov5`: [YOLOv5](https://github.com/ultralytics/yolov5) model +
+ Export YOLOv5 to ONNX + + ```bash + # Export with FP32 precision + python export.py \ + --weights yolov5s.pt \ + --include onnx \ + --simplify + + # Export with FP16 precision (CUDA-compatible GPU is required) + python export.py \ + --weights yolov5s.pt \ + --include onnx \ + --simplify \ + --half + ``` +
+ * `yolov6`: [YOLOv6](https://github.com/meituan/YOLOv6) model +
+ Export YOLOv6 to ONNX + + ```bash + # Export with FP32 precision + python deploy/ONNX/export_onnx.py \ + --weights yolov6s.pt \ + --img 640 \ + --batch 1 \ + --simplify + + # Export with FP16 precision (CUDA-compatible GPU is required) + python deploy/ONNX/export_onnx.py \ + --weights yolov6s.pt \ + --img 640 \ + --batch 1 \ + --simplify \ + --half + ``` +
+ * `yolov7`: [YOLOv7](https://github.com/WongKinYiu/yolov7) model +
+ Export YOLOv7 to ONNX + + ```bash + # Export with FP32 precision + python export.py \ + --weights yolov7-tiny.pt \ + --grid \ + --simplify \ + --img-size 640 640 \ + --max-wh 640 + + # Export with FP16 precision (CUDA-compatible GPU is required) + python export.py \ + --weights yolov7-tiny.pt \ + --grid \ + --simplify \ + --img-size 640 640 \ + --max-wh 640 \ + --fp16 + ``` +
+ * `yolov8`: [YOLOv8](https://github.com/ultralytics/ultralytics) model +
+ Export YOLOv8 to ONNX + + ```bash + pip install ultralytics + + # Export with FP32 precision + yolo export \ + model=yolov8n.pt \ + format=onnx \ + simplify=True + + # Export with FP16 precision using CUDA-compatible GPU + yolo export \ + model=yolov8n.pt \ + format=onnx \ + simplify=True \ + half=True \ + device=0 + + # Export with FP16 precision using Apple Silicon GPU + yolo export \ + model=yolov8n.pt \ + format=onnx \ + simplify=True \ + half=True \ + device=mps + ``` +
+ * `yolov9`: [YOLOv9](https://github.com/WongKinYiu/yolov9) model +
+ Export YOLOv9 to ONNX + + ```bash + # Export with FP32 precision + python export.py \ + --weights yolov9-s.pt \ + --include onnx \ + --simplify + + # Export with FP16 precision (CUDA-compatible GPU is required) + python export.py \ + --weights yolov9-s.pt \ + --include onnx \ + --simplify \ + --half + ``` +
+ * `yolov10`: [YOLOv10](https://github.com/THU-MIG/yolov10) model +
+ Export YOLOv10 to ONNX + + Unfortunately, the export script from the original YOLOv10 repository adds NMS and other postprocessing operations to the model and doesn't allow to disable them. You can apply a patch to the YOLOv10 code to fix this issue: + + ```bash + curl -Ls https://gist.githubusercontent.com/DarthSim/216551dfd58e5628290e90c1d358704b/raw/27a828a48c84f93e0e70b14923bf697541ebe5a1/yolov10.patch | git apply + ``` + + ...and then export the model: + + ```bash + # Export with FP32 precision + python export_opencv.py \ + --weights yolov10s.pt \ + --imgsz 640 640 + + # Export with FP16 precision (CUDA-compatible GPU is required) + python export_opencv.py \ + --weights yolov10s.pt \ + --imgsz 640 640 \ + --half + ``` +
+ * `yolov11`: [YOLOv11](https://github.com/ultralytics/ultralytics) model +
+ Export YOLOv11 to ONNX + + ```bash + pip install ultralytics + + # Export with FP32 precision + yolo export \ + model=yolov11n.pt \ + format=onnx \ + simplify=True + + # Export with FP16 precision using CUDA-compatible GPU + yolo export \ + model=yolov11n.pt \ + format=onnx \ + simplify=True \ + half=True \ + device=0 + + # Export with FP16 precision using Apple Silicon GPU + yolo export \ + model=yolov11n.pt \ + format=onnx \ + simplify=True \ + half=True \ + device=mps + ``` +
+ * `yolo-nas`: [YOLO-NAS](https://github.com/Deci-AI/super-gradients) model +
+ Export YOLO-NAS to ONNX + + ```python + from super_gradients.training import models + from super_gradients.common.object_names import Models + from super_gradients.conversion import DetectionOutputFormatMode + from super_gradients.conversion.conversion_enums import ExportQuantizationMode + + # Load the model from the SuperGradients model zoo + model = models.get( + Models.YOLO_NAS_S, + pretrained_weights="coco" + ) + # Or load the model from a checkpoint + model = models.get( + Models.YOLO_NAS_S, + num_classes=80, + checkpoint_path=f"neural-yolo_nas_s.pth" + ) + + model.eval() + model.prep_model_for_conversion(input_size=[1, 3, 640, 640]) + + # Disable preprocessing and postprocessing since imgproxy will handle it + model.export( + "/content/yolo_nas_s.onnx", + preprocessing=False, + postprocessing=False, + output_predictions_format=DetectionOutputFormatMode.FLAT_FORMAT, + input_image_shape=[640, 640], + quantization_mode=ExportQuantizationMode.FP16, + ) + ``` +
+* [`IMGPROXY_OBJECT_DETECTION_CLASSES`]: a path to the [class names file](#class-names-file) + +### Common config options + +* [`IMGPROXY_OBJECT_DETECTION_NET_SIZE`]: the size of the neural network input. The inputs' width and heights should be the same, so this config value should be a single number. Default: 416 +* [`IMGPROXY_OBJECT_DETECTION_CONFIDENCE_THRESHOLD`]: detections with confidence below this value will be discarded. Default: 0.2 +* [`IMGPROXY_OBJECT_DETECTION_NMS_THRESHOLD`]: non-max supression threshold. Don't change this if you don't know what you're doing. Default: 0.4 +* [`IMGPROXY_OBJECT_DETECTION_SWAP_RB`]: when set to `true`, imgproxy will swap the R and B channels in the input image. Some models are trained on BGR images and perform incorrectly with RGB inputs. This option allows you to fix this issue. Default: `false` +* [`IMGPROXY_OBJECT_DETECTION_FALLBACK_TO_SMART_CROP`]: ((pro)) defines imgproxy's behavior when object-oriented crop gravity is used but no objects are detected. When set to `true`, imgproxy will fallback to smart crop. When set to `false`, imgproxy will fallback to the center gravity. Default: `true` + +### Class names file + +The class names file is used to map the class indexes from the neural network output to human-readable class names. The path to the class names file should be defined in the `IMGPROXY_OBJECT_DETECTION_CLASSES` config variable. + +The class names file should contain one class name per line. The class names should be in the same order as the classes in the neural network output. Example: + +```text +person +dog +cat +``` + +By default, during the object-oriented crop, all the detected objects have the default weight of `1`. You can change the weight of the detected objects by adding the `=%weight` suffix to the object class name. Example: + +```text +person=2 +dog +cat=3 +``` + +In this example, the detected `person` and `cat` objects will have the weight of `2` and `3` respectively. The `dog` object will have the default weight of `1`. + +## Usage examples +### Object-oriented crop + +You can [crop](../usage/processing.mdx#crop) your images and keep objects of desired classes in frame: + +```imgproxy_url +.../crop:256:256/gravity:obj:face:cat:dog/... +``` + +Also, you can use the `objw` gravity type to redefine the weights of the detected objects: + +```imgproxy_url +.../crop:256:256/gravity:objw:face:2:cat:3:dog:4/... +``` + +The `all` pseudo-class matches all the detected objects. You can use it to set the weight for all the detected objects: + +```imgproxy_url +.../crop:256:256/gravity:objw:all:2:face:10/... +``` + +In this example, all the detected objects will have the weight of `2`, except for the `face` objects, which will have the weight of `10`. + +### Blurring detections + +You can [blur objects](../usage/processing.mdx#blur-detections) of desired classes, thus making anonymization or hiding NSFW content possible: + +```imgproxy_url +.../blur_detections:7:face/... +``` + +### Draw detections + +You can make imgproxy [draw bounding boxes](../usage/processing.mdx#draw-detections) for the detected objects of the desired classes (this is handy for testing your models): + +```imgproxy_url +.../draw_detections:1:face/... +``` + +### Crop to detected objects + +You can make imgproxy [crop the image](../usage/processing.mdx#crop-objects) to fit all detected objects of the desired classes: + +```imgproxy_url +.../crop_objects:1.2:face:person/... +``` + +This will automatically crop the image to include all detected faces and persons with 20% padding around them. You can omit class names to crop to all detected objects: + +```imgproxy_url +.../co:1.0/... +``` + +### Fetch the detected objects' info + +You can [fetch the detected objects info](../usage/getting_info.mdx#detect-objects) using the `/info` endpoint: + +```imgproxy_url +.../info/detect_objects:1/... +``` diff --git a/versioned_docs/version-4-preview/features/watermark.mdx b/versioned_docs/version-4-preview/features/watermark.mdx new file mode 100644 index 0000000..97cd0c0 --- /dev/null +++ b/versioned_docs/version-4-preview/features/watermark.mdx @@ -0,0 +1,79 @@ +--- +description: Learn about how to put watermarks on your images +--- + +# Watermark + +imgproxy supports the watermarking of processed images using another image. + +## Specifying watermark image + +There are three ways to specify a watermark image using environment variables: + +* `IMGPROXY_WATERMARK_PATH`: the path to the locally stored image +* `IMGPROXY_WATERMARK_URL`: the watermark image URL +* `IMGPROXY_WATERMARK_DATA`: Base64-encoded image data. You can easily calculate it with the following snippet: + + ```bash + base64 tmp/watermark.webp | tr -d '\n'`. + ``` + +You can also specify the base opacity of a watermark using the `IMGPROXY_WATERMARK_OPACITY` environment variable. + +:::info +If you're going to use the `scale` argument of `watermark`, it's highly recommended to use SVG, WebP or JPEG watermarks since these formats support scale-on-load. +::: + +## Watermarking an image + +Use the [watermark](../usage/processing.mdx#watermark) processing option to put a watermark on a processed image: + +```imgproxy_url_option +watermark:%opacity:%position:%x_offset:%y_offset:%scale +wm:%opacity:%position:%x_offset:%y_offset:%scale +``` + +The available arguments are: + +* `opacity` - watermark opacity modifier. The final opacity is calculated as `base_opacity * opacity`. +* `position` - (optional) specifies the position of the watermark. Available values: + * `ce`: (default) center + * `no`: north (top edge) + * `so`: south (bottom edge) + * `ea`: east (right edge) + * `we`: west (left edge) + * `noea`: north-east (top-right corner) + * `nowe`: north-west (top-left corner) + * `soea`: south-east (bottom-right corner) + * `sowe`: south-west (bottom-left corner) + * `re`: repeat and tile the watermark to fill the entire image +* `x_offset`, `y_offset` - (optional) specify watermark offset by X and Y axes. When using `re` position, these values define the spacing between the tiles. +* `scale` - (optional) a floating point number that defines the watermark size relative to the resulting image size. When set to `0` or omitted, the watermark size won't be changed. + +## Custom watermarks ((pro)) {#custom-watermarks} + +You can use a custom watermark by specifying its URL with the [watermark_url](../usage/processing.mdx#watermark-url) processing option: + +```imgproxy_url_option +watermark_url:%url +wmu:%url +``` + +The value of `url` should be the Base64-encoded URL of the custom watermark. + +By default, imgproxy caches 256 custom watermarks with an adaptive replacement cache (ARC). You can change the cache size using the `IMGPROXY_WATERMARKS_CACHE_SIZE` environment variable. When `IMGPROXY_WATERMARKS_CACHE_SIZE` is set to `0`, the cache is disabled. + +## Text watermarks ((pro)) {#text-watermarks} + +You can put a text as a watermark on your image with the [watermark_text](../usage/processing.mdx#watermark-text) processing option: + +```imgproxy_url_option +watermark_text:%text +wmt:%text +``` + +The value of `text` should be the URL-safe Base64-encoded text of the custom watermark. + +By default, the text color is black and the font is `sans 16`. You can use [Pango markup](https://docs.gtk.org/Pango/pango_markup.html) in the `text` value to change the style. + +If you want to use a custom font, you need to put it in `/usr/share/fonts` inside a container. diff --git a/versioned_docs/version-4-preview/getting_started.mdx b/versioned_docs/version-4-preview/getting_started.mdx new file mode 100644 index 0000000..0418734 --- /dev/null +++ b/versioned_docs/version-4-preview/getting_started.mdx @@ -0,0 +1,34 @@ +--- +description: Learn about how to quickly resize your first image using imgproxy +--- + +# Getting started + +This guide will show you how to quickly resize your first image using imgproxy. + +## Install + +Let's assume you already have Docker installed on your machine — you can pull an official imgproxy Docker image, and you’re done! + +```bash +docker pull ghcr.io/imgproxy/imgproxy:latest +docker run -p 8080:8080 -it ghcr.io/imgproxy/imgproxy:latest +``` + +If you don't have docker or if you want to deploy imgproxy to a cloud, you can check out our [installation guide](./installation.mdx) for more installation options. + +And that's it! No further configuration is needed, but if you want to unleash the full power of imgproxy, read our [configuration guide](./configuration/options.mdx). + +## Resize an image + +After you’ve successfully installed imgproxy, a good first step is to make sure that everything is working correctly. To do that, you can use the following URL to get a resized image of Matt Damon from “The Martian” (replace `localhost:8080` with your domain if you’ve installed imgproxy on a remote server): + +[http://localhost:8080/insecure/rs:fill:300:400/g:sm/aHR0cHM6Ly9tLm1l/ZGlhLWFtYXpvbi5j/b20vaW1hZ2VzL00v/TVY1QllUY3hOamhr/WmpndE5Ea3dPQzAw/TXpReUxUaGxaRFV0/Tm1OaU1UaGtZek5r/T0dKbFhrRXlYa0Zx/Y0djQC5fVjFfRk1q/cGdfVVgyMTYwXy5q/cGc.jpg](http://localhost:8080/insecure/rs:fill:300:400/g:sm/aHR0cHM6Ly9tLm1l/ZGlhLWFtYXpvbi5j/b20vaW1hZ2VzL00v/TVY1QllUY3hOamhr/WmpndE5Ea3dPQzAw/TXpReUxUaGxaRFV0/Tm1OaU1UaGtZek5r/T0dKbFhrRXlYa0Zx/Y0djQC5fVjFfRk1q/cGdfVVgyMTYwXy5q/cGc.jpg) + +Just for reference, here’s [the original image](https://m.media-amazon.com/images/M/MV5BYTcxNjhkZjgtNDkwOC00MzQyLThlZDUtNmNiMThkYzNkOGJlXkEyXkFqcGc@._V1_FMjpg_UX2160_.jpg). Using the URL above, imgproxy is instructed to resize it to fill an area of `300x400` size with “smart” gravity. “Smart” means that the `libvips` library chooses the most “interesting” part of the image. + +You can learn more on how to process images with imgproxy in the [Processing an image](./usage/processing.mdx) guide. + +## Security + +Note that the URL in the above example is not signed. However, it’s highly recommended to use signed URLs in production. Read our [Signing a URL](./usage/signing_url.mdx) guide to learn how to secure your imgproxy installation from attackers. diff --git a/versioned_docs/version-4-preview/healthcheck.mdx b/versioned_docs/version-4-preview/healthcheck.mdx new file mode 100644 index 0000000..2d44b6f --- /dev/null +++ b/versioned_docs/version-4-preview/healthcheck.mdx @@ -0,0 +1,23 @@ +--- +description: Learn about how check if imgproxy is healthy using the health chech +--- + +# Health check + +imgproxy comes with a built-in health check HTTP endpoint at `/health`. + +`GET /health` returns an HTTP Status of `200 OK` if the server has been successfully started. + +You can use this for readiness/liveness probes when deploying with a container orchestration system such as Kubernetes. + +## imgproxy health + +imgproxy provides an `imgproxy health` command that makes an HTTP request to the health endpoint based on the [IMGPROXY_BIND](./configuration/options.mdx#IMGPROXY_BIND) and [IMGPROXY_NETWORK](./configuration/options.mdx#IMGPROXY_NETWORK) configs. It exits with `0` when the request is successful and with `1` otherwise. The command is handy to use with Docker Compose: + +```yaml +healthcheck: + test: [ "CMD", "imgproxy", "health" ] + timeout: "10s" + interval: "10s" + retries: 3 +``` diff --git a/versioned_docs/version-4-preview/image_formats_support.mdx b/versioned_docs/version-4-preview/image_formats_support.mdx new file mode 100644 index 0000000..85279e6 --- /dev/null +++ b/versioned_docs/version-4-preview/image_formats_support.mdx @@ -0,0 +1,108 @@ +--- +description: Learn about image formats supported by imgproxy +--- + +# Image formats support + +At the moment, imgproxy supports only the most popular image formats: + +| Format | Extension | Source | Result | +| ----------------------------|-----------|--------------------------------|---------------------------| +| PNG | `png` | :white_check_mark: | :white_check_mark: | +| JPEG | `jpg` | :white_check_mark: | :white_check_mark: | +| JPEG XL | `jxl` | :white_check_mark: | [See notes](#jxl-support) | +| WebP | `webp` | :white_check_mark: | :white_check_mark: | +| AVIF | `avif` | :white_check_mark: | :white_check_mark: | +| GIF | `gif` | :white_check_mark: | :white_check_mark: | +| ICO | `ico` | :white_check_mark: | :white_check_mark: | +| SVG | `svg` | :white_check_mark: | [See notes](#svg-support) | +| HEIC | `heic` | :white_check_mark: | :white_check_mark: | +| BMP | `bmp` | :white_check_mark: | :white_check_mark: | +| TIFF | `tiff` | :white_check_mark: | :white_check_mark: | +| PDF ((pro)) | `pdf` | :white_check_mark: | [See notes](#pdf-support) | +| PSD ((pro)) | `psd` | [See notes](#psd-support) | :x: | +| RAW ((pro)) | | [See notes](#raw-support) | :x: | +| MP4 (h264) ((pro)) | `mp4` | [See notes](#video-thumbnails) | :white_check_mark: | +| Other video formats ((pro)) | | [See notes](#video-thumbnails) | :x: | + +## JPEG XL support {#jxl-support} + +imgproxy supports JPEG XL as a source format without limitations. + +When JPEG XL is used as a result format, animations are not supported because animated JPEG XL is not yet supported by browsers. + +## SVG support + +imgproxy supports SVG sources without limitations, but SVG results are not supported when the source image is not SVG. + +When the source image is SVG and an SVG result is requested, imgproxy returns the source image without modifications. + +## Animated images support + +Since the processing of animated images is a pretty heavy process, only one frame is processed by default. You can increase the maximum of animation frames to process with the following variable: + +* `IMGPROXY_MAX_ANIMATION_FRAMES`: the maximum of animated image frames to be processed. Default: `1`. + +:::info +imgproxy summarizes all frames resolutions while the checking source image resolution. +::: + +## PDF support ((pro)) {#pdf-support} + +imgproxy supports PDF both as a source and result format. + +When PDF is used as a source, imgproxy renders the specified pages as raster images. + +When PDF is used as a result format, imgproxy renders the image as a JPEG image and embeds it into a single-page PDF document. + +## PSD support ((pro)) {#psd-support} + +PSD (Photoshop Document) and PSB (Photoshop Big) files are supported as source images, but there are some limitations: + +PSD/PSB files should be saved with Photoshop's "Maximize Compatibility" option enabled, which is enabled by default. If this option is disabled, imgproxy won't return an error but will render the PSD/PSB file as a solid white image. + +We tested imgproxy with all variants of PSD/PSB files that we could find or produce with Adobe Photoshop 2025. If you encounter any PSD/PSB file that imgproxy can't process, please let us know. + +:::warning +We couldn't find any PSD/PSB files with their image data compressed with ZIP, so imgproxy renders them as solid white images. If you had such files, we would very much appreciate it if you could share them with us. +::: + +## RAW support ((pro)) {#raw-support} + +RAW image formats from digital cameras are supported as source images only (read-only). RAW files are decoded and converted to standard image formats during processing. + +imgproxy uses [libraw](https://www.libraw.org/) to process RAW files. For a complete list of supported camera models and RAW formats, see the [libraw supported cameras list](https://www.libraw.org/supported-cameras). + +## Converting animated images to MP4 ((pro)) {#converting-animated-images-to-mp4} + +Animated image results can be converted to MP4 by specifying the `mp4` extension. + +Since MP4 requires use of a `