diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 650b321..f90218b 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -100,13 +100,16 @@ const config: Config = { routeBasePath: "/", sidebarPath: require.resolve("./sidebars.js"), // sidebarCollapsed: false, - + lastVersion: "3.31.x", versions: { current: { label: "latest", path: "latest", banner: "unreleased", }, + "4-preview": { + banner: "unreleased", + }, }, editUrl: "https://github.com/imgproxy/imgproxy-docs/tree/master/", diff --git a/src/css/badge.css b/src/css/badge.css index ba21c5f..79df86d 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; @@ -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"; } 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/versioned_docs/version-4-preview/cache/external.mdx b/versioned_docs/version-4-preview/cache/external.mdx new file mode 100644 index 0000000..ce320ff --- /dev/null +++ b/versioned_docs/version-4-preview/cache/external.mdx @@ -0,0 +1,217 @@ +--- +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 + +* **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](../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 + +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; + + # 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 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; + 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](../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"; +``` + +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"; +``` + +Use the smallest key that still prevents collisions for your traffic profile. + +### Key recommendations + +* 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. +* 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 30 days + if (beresp.status == 200) { + set beresp.ttl = 30d; + set beresp.keep = 30d; + } + + # 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](../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`. +* 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/versioned_docs/version-4-preview/cache/internal.mdx b/versioned_docs/version-4-preview/cache/internal.mdx new file mode 100644 index 0000000..2c9ab15 --- /dev/null +++ b/versioned_docs/version-4-preview/cache/internal.mdx @@ -0,0 +1,68 @@ +--- +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 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. + +## 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. diff --git a/versioned_docs/version-4-preview/cache/internal/amazon_s3.mdx b/versioned_docs/version-4-preview/cache/internal/amazon_s3.mdx new file mode 100644 index 0000000..ef7ae59 --- /dev/null +++ b/versioned_docs/version-4-preview/cache/internal/amazon_s3.mdx @@ -0,0 +1,70 @@ +--- +description: Learn about how to configure Amazon S3 cache in imgproxy +--- + +# Internal cache: 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. 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. + +### 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/versioned_docs/version-4-preview/cache/internal/azure_blob_storage.mdx b/versioned_docs/version-4-preview/cache/internal/azure_blob_storage.mdx new file mode 100644 index 0000000..dd40c08 --- /dev/null +++ b/versioned_docs/version-4-preview/cache/internal/azure_blob_storage.mdx @@ -0,0 +1,60 @@ +--- +description: Learn about how to configure Azure Blob Storage cache in imgproxy +--- + +# Internal cache: 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. 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/versioned_docs/version-4-preview/cache/internal/google_cloud_storage.mdx b/versioned_docs/version-4-preview/cache/internal/google_cloud_storage.mdx new file mode 100644 index 0000000..12215ee --- /dev/null +++ b/versioned_docs/version-4-preview/cache/internal/google_cloud_storage.mdx @@ -0,0 +1,33 @@ +--- +description: Learn about how to configure Google Cloud Storage cache in imgproxy +--- + +# Internal cache: 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. 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/versioned_docs/version-4-preview/cache/internal/local_filesystem.mdx b/versioned_docs/version-4-preview/cache/internal/local_filesystem.mdx new file mode 100644 index 0000000..b044e99 --- /dev/null +++ b/versioned_docs/version-4-preview/cache/internal/local_filesystem.mdx @@ -0,0 +1,29 @@ +--- +description: Learn about how to configure the local filesystem cache in imgproxy +--- + +# Internal cache: 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 `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`. + +### 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=fs IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT=/var/cache/imgproxy imgproxy +``` diff --git a/versioned_docs/version-4-preview/cache/internal/openstack_swift.mdx b/versioned_docs/version-4-preview/cache/internal/openstack_swift.mdx new file mode 100644 index 0000000..7b2001b --- /dev/null +++ b/versioned_docs/version-4-preview/cache/internal/openstack_swift.mdx @@ -0,0 +1,35 @@ +--- +description: Learn about how to configure OpenStack Object Storage cache in imgproxy +--- + +# 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: + +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. 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/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/versioned_docs/version-4-preview/features/classification.mdx b/versioned_docs/version-4-preview/features/classification.mdx new file mode 100644 index 0000000..c776213 --- /dev/null +++ b/versioned_docs/version-4-preview/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](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. + +## 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: + * `nhwc`: channels last (TensorFlow default) + * `nchw`: channels first (PyTorch 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 `cl` (classify) 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/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 `