mirror of
https://github.com/imgproxy/imgproxy.git
synced 2024-11-18 16:31:44 +02:00
Docs were moved to https://github.com/imgproxy/imgproxy-docs
This commit is contained in:
DarthSim
parent
760b27783f
commit
92d88fbfbd
68
CHANGELOG.md
68
CHANGELOG.md
@ -382,7 +382,7 @@
|
||||
- (pro) [fallback_image_url](https://docs.imgproxy.net/generating_the_url?id=fallback-image-url) processing option.
|
||||
- [expires](https://docs.imgproxy.net/generating_the_url?id=expires) processing option.
|
||||
- [skip processing](https://docs.imgproxy.net/generating_the_url?id=skip-processing) processing option.
|
||||
- [Datadog](./docs/datadog.md) metrics.
|
||||
- [Datadog](https://docs.imgproxy.net/datadog) metrics.
|
||||
- `force` and `fill-down` resizing types.
|
||||
- [min-width](https://docs.imgproxy.net/generating_the_url?id=min-width) and [min-height](https://docs.imgproxy.net/generating_the_url?id=min-height) processing options.
|
||||
- [format_quality](https://docs.imgproxy.net/generating_the_url?id=format-quality) processing option.
|
||||
@ -407,11 +407,11 @@
|
||||
- Escape double quotes in content disposition.
|
||||
|
||||
### Removed
|
||||
- Removed basic URL format, use [advanced one](./docs/generating_the_url.md) instead.
|
||||
- Removed basic URL format, use [advanced one](https://docs.imgproxy.net/generating_the_url) instead.
|
||||
- Removed `IMGPROXY_MAX_SRC_DIMENSION` config, use `IMGPROXY_MAX_SRC_RESOLUTION` instead.
|
||||
- Removed `IMGPROXY_GZIP_COMPRESSION` config.
|
||||
- Removed `IMGPROXY_MAX_GIF_FRAMES` config, use `IMGPROXY_MAX_ANIMATION_FRAMES` instead.
|
||||
- Removed `crop` resizing type, use [crop](./docs/generating_the_url.md#crop) processing option instead.
|
||||
- Removed `crop` resizing type, use [crop](https://docs.imgproxy.net/generating_the_url#crop) processing option instead.
|
||||
- Dropped old libvips (<8.10) support.
|
||||
- (pro) Removed advanced GIF optimizations. All optimizations are applied by default ib both OSS and Pro versions.
|
||||
|
||||
@ -441,7 +441,7 @@
|
||||
- (pro) [fallback_image_url](https://docs.imgproxy.net/generating_the_url?id=fallback-image-url) processing option.
|
||||
- [expires](https://docs.imgproxy.net/generating_the_url?id=expires) processing option.
|
||||
- [skip processing](https://docs.imgproxy.net/generating_the_url?id=skip-processing) processing option.
|
||||
- [Datadog](./docs/datadog.md) metrics.
|
||||
- [Datadog](https://docs.imgproxy.net/datadog) metrics.
|
||||
- `force` and `fill-down` resizing types.
|
||||
- [min-width](https://docs.imgproxy.net/generating_the_url?id=min-width) and [min-height](https://docs.imgproxy.net/generating_the_url?id=min-height) processing options.
|
||||
- [format_quality](https://docs.imgproxy.net/generating_the_url?id=format-quality) processing option.
|
||||
@ -450,11 +450,11 @@
|
||||
- ETag generator & checker uses source image ETag when possible.
|
||||
|
||||
### Removed
|
||||
- Removed basic URL format, use [advanced one](./docs/generating_the_url.md) instead.
|
||||
- Removed basic URL format, use [advanced one](https://docs.imgproxy.net/generating_the_url) instead.
|
||||
- Removed `IMGPROXY_MAX_SRC_DIMENSION` config, use `IMGPROXY_MAX_SRC_RESOLUTION` instead.
|
||||
- Removed `IMGPROXY_GZIP_COMPRESSION` config.
|
||||
- Removed `IMGPROXY_MAX_GIF_FRAMES` config, use `IMGPROXY_MAX_ANIMATION_FRAMES` instead.
|
||||
- Removed `crop` resizing type, use [crop](./docs/generating_the_url.md#crop) processing option instead.
|
||||
- Removed `crop` resizing type, use [crop](https://docs.imgproxy.net/generating_the_url#crop) processing option instead.
|
||||
- Dropped old libvips (<8.8) support.
|
||||
|
||||
## [2.17.0] - 2021-09-07
|
||||
@ -710,7 +710,7 @@
|
||||
## [2.4.0] - 2019-08-20
|
||||
### Added
|
||||
- `SO_REUSEPORT` socker option support. Can be enabled with `IMGPROXY_SO_REUSEPORT`.
|
||||
- [filename](./docs/generating_the_url.md#filename) option.
|
||||
- [filename](https://docs.imgproxy.net/generating_the_url#filename) option.
|
||||
|
||||
### Changed
|
||||
- Better handling if non-sRGB images.
|
||||
@ -726,9 +726,9 @@
|
||||
### Added
|
||||
- `libvips` v8.8 support: better processing of animated GIFs, built-in CMYK profile, better WebP scale-on-load, etc;
|
||||
- Animated WebP support. `IMGPROXY_MAX_GIF_FRAMES` is deprecated, use `IMGPROXY_MAX_ANIMATION_FRAMES`;
|
||||
- [HEIC support](./docs/image_formats_support.md#heic-support);
|
||||
- [crop](./docs/generating_the_url.md#crop) processing option. `resizing_type:crop` is deprecated;
|
||||
- Offsets for [gravity](./docs/generating_the_url.md#gravity);
|
||||
- [HEIC support](https://docs.imgproxy.net/image_formats_support#heic-support);
|
||||
- [crop](https://docs.imgproxy.net/generating_the_url#crop) processing option. `resizing_type:crop` is deprecated;
|
||||
- Offsets for [gravity](https://docs.imgproxy.net/generating_the_url#gravity);
|
||||
- Resizing type `auto`. If both source and resulting dimensions have the same orientation (portrait or landscape), imgproxy will use `fill`. Otherwise, it will use `fit`;
|
||||
- Development errors mode. When `IMGPROXY_DEVELOPMENT_ERRORS_MODE` is true, imgproxy will respond with detailed error messages. Not recommended for production because some errors may contain stack trace;
|
||||
- `IMGPROXY_KEEP_ALIVE_TIMEOUT` config.
|
||||
@ -786,7 +786,7 @@ Fixed processing of images with embedded profiles that was broken in v2.2.8.
|
||||
|
||||
## [2.2.5] - 2019-02-21
|
||||
### Added
|
||||
- [extend](./docs/generating_the_url.md#extend) processing option.
|
||||
- [extend](https://docs.imgproxy.net/generating_the_url#extend) processing option.
|
||||
- `vips_memory_bytes`, `vips_max_memory_bytes` and `vips_allocs` metrics for Prometheus.
|
||||
|
||||
### Fixed
|
||||
@ -816,14 +816,14 @@ Fixed processing of images with embedded profiles that was broken in v2.2.8.
|
||||
|
||||
## [2.2.0] - 2019-01-19
|
||||
### Changed
|
||||
- Optimized memory usage. [Memory usage tweaks](./docs/memory_usage_tweaks.md).
|
||||
- Optimized memory usage. [Memory usage tweaks](https://docs.imgproxy.net/memory_usage_tweaks).
|
||||
- `Vary` header is set when WebP detection, client hints or GZip compression are enabled.
|
||||
- Health check doesn't require `Authorization` header anymore.
|
||||
|
||||
## [2.1.5] - 2019-01-14
|
||||
### Added
|
||||
- [Sentry support](./docs/configuration.md#error-reporting) (thanks to [@koenpunt](https://github.com/koenpunt)).
|
||||
- [Syslog support](./docs/configuration.md#syslog).
|
||||
- [Sentry support](https://docs.imgproxy.net/configuration#error-reporting) (thanks to [@koenpunt](https://github.com/koenpunt)).
|
||||
- [Syslog support](https://docs.imgproxy.net/configuration#syslog).
|
||||
|
||||
### Fixed
|
||||
- Fix detection of some kind of WebP images;
|
||||
@ -841,7 +841,7 @@ Fixed processing of images with embedded profiles that was broken in v2.2.8.
|
||||
|
||||
## [2.1.3] - 2018-12-10
|
||||
### Added
|
||||
- [Minio support](./docs/serving_files_from_s3.md#minio)
|
||||
- [Minio support](https://docs.imgproxy.net/serving_files_from_s3#minio)
|
||||
|
||||
## [2.1.2] - 2018-12-02
|
||||
### Added
|
||||
@ -856,18 +856,18 @@ Fixed processing of images with embedded profiles that was broken in v2.2.8.
|
||||
|
||||
## [2.1.0] - 2018-11-16
|
||||
### Added
|
||||
- [Plain source URLs](./docs/generating_the_url.md#plain) support.
|
||||
- [Serving images from Google Cloud Storage](./docs/serving_files_from_google_cloud_storage.md).
|
||||
- [Full support of GIFs](./docs/image_formats_support.md#gif-support) including animated ones.
|
||||
- [Watermarks](./docs/watermark.md).
|
||||
- [New Relic](./docs/new_relic.md) metrics.
|
||||
- [Prometheus](./docs/prometheus.md) metrics.
|
||||
- [DPR](./docs/generating_the_url.md#dpr) option (thanks to [selul](https://github.com/selul)).
|
||||
- [Cache buster](./docs/generating_the_url.md#cache-buster) option.
|
||||
- [Quality](./docs/generating_the_url.md#quality) option.
|
||||
- Support for custom [Amazon S3](./docs/serving_files_from_s3.md) endpoints.
|
||||
- Support for [Amazon S3](./docs/serving_files_from_s3.md) versioning.
|
||||
- [Client hints](./docs/configuration.md#client-hints-support) support (thanks to [selul](https://github.com/selul)).
|
||||
- [Plain source URLs](https://docs.imgproxy.net/generating_the_url#plain) support.
|
||||
- [Serving images from Google Cloud Storage](https://docs.imgproxy.net/serving_files_from_google_cloud_storage).
|
||||
- [Full support of GIFs](https://docs.imgproxy.net/image_formats_support#gif-support) including animated ones.
|
||||
- [Watermarks](https://docs.imgproxy.net/watermark).
|
||||
- [New Relic](https://docs.imgproxy.net/new_relic) metrics.
|
||||
- [Prometheus](https://docs.imgproxy.net/prometheus) metrics.
|
||||
- [DPR](https://docs.imgproxy.net/generating_the_url#dpr) option (thanks to [selul](https://github.com/selul)).
|
||||
- [Cache buster](https://docs.imgproxy.net/generating_the_url#cache-buster) option.
|
||||
- [Quality](https://docs.imgproxy.net/generating_the_url#quality) option.
|
||||
- Support for custom [Amazon S3](https://docs.imgproxy.net/serving_files_from_s3) endpoints.
|
||||
- Support for [Amazon S3](https://docs.imgproxy.net/serving_files_from_s3) versioning.
|
||||
- [Client hints](https://docs.imgproxy.net/configuration#client-hints-support) support (thanks to [selul](https://github.com/selul)).
|
||||
- Truncated signature support (thanks to [printercu](https://github.com/printercu)).
|
||||
|
||||
### Changed
|
||||
@ -893,13 +893,13 @@ Fixed processing of images with embedded profiles that was broken in v2.2.8.
|
||||
## [2.0.0] - 2018-10-08
|
||||
All-You-Ever-Wanted release! :tada:
|
||||
### Added
|
||||
- [New advanced URL format](./docs/generating_the_url.md). Unleash the full power of imgproxy v2.0.
|
||||
- [Presets](./docs/presets.md). Shorten your urls by reusing processing options.
|
||||
- [Serving images from Amazon S3](./docs/serving_files_from_s3.md). Thanks to [@crohr](https://github.com/crohr), now we have a way to serve files from private S3 buckets.
|
||||
- [Autoconverting to WebP when supported by browser](./docs/configuration.md#avifwebp-support-detection) (disabled by default). Use WebP as resulting format when browser supports it.
|
||||
- [Gaussian blur](./docs/generating_the_url.md#blur) and [sharpen](./docs/generating_the_url.md#sharpen) filters. Make your images look better than before.
|
||||
- [Focus point gravity](./docs/generating_the_url.md#gravity). Tell imgproxy what point will be the center of the image.
|
||||
- [Background color](./docs/generating_the_url.md#background). Control the color of background when converting PNG with alpha-channel to JPEG.
|
||||
- [New advanced URL format](https://docs.imgproxy.net/generating_the_url). Unleash the full power of imgproxy v2.0.
|
||||
- [Presets](https://docs.imgproxy.net/presets). Shorten your urls by reusing processing options.
|
||||
- [Serving images from Amazon S3](https://docs.imgproxy.net/serving_files_from_s3). Thanks to [@crohr](https://github.com/crohr), now we have a way to serve files from private S3 buckets.
|
||||
- [Autoconverting to WebP when supported by browser](https://docs.imgproxy.net/configuration#avifwebp-support-detection) (disabled by default). Use WebP as resulting format when browser supports it.
|
||||
- [Gaussian blur](https://docs.imgproxy.net/generating_the_url#blur) and [sharpen](https://docs.imgproxy.net/generating_the_url#sharpen) filters. Make your images look better than before.
|
||||
- [Focus point gravity](https://docs.imgproxy.net/generating_the_url#gravity). Tell imgproxy what point will be the center of the image.
|
||||
- [Background color](https://docs.imgproxy.net/generating_the_url#background). Control the color of background when converting PNG with alpha-channel to JPEG.
|
||||
|
||||
### Changed
|
||||
- Key and salt are not required anymore. When key or salt is not specified, signature checking is disabled.
|
||||
|
||||
@ -1,34 +0,0 @@
|
||||
# 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 darthsim/imgproxy:latest
|
||||
docker run -p 8080:8080 -it darthsim/imgproxy
|
||||
```
|
||||
|
||||
If you don't have docker, you can use Heroku for a quick start.
|
||||
|
||||
[](https://heroku.com/deploy?template=https://github.com/DarthSim/imgproxy)
|
||||
|
||||
Check out our [installation guide](installation.md) for more details and instructions.
|
||||
|
||||
In both cases, that's it! No further configuration is needed, but if you want to unleash the full power of imgproxy, read our [configuration guide](configuration.md).
|
||||
|
||||
## 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/TVY1Qk1tUTNabVk0/TnpZdFkyVm1ZaTAw/WkRSbUxUZ3lPREF0/WldZelpqaGxOemsx/TnpVMlhrRXlYa0Zx/Y0dkZVFYVnlOVGMz/TWpVek5USUAuanBn.jpg](http://localhost:8080/insecure/rs:fill:300:400/g:sm/aHR0cHM6Ly9tLm1l/ZGlhLWFtYXpvbi5j/b20vaW1hZ2VzL00v/TVY1Qk1tUTNabVk0/TnpZdFkyVm1ZaTAw/WkRSbUxUZ3lPREF0/WldZelpqaGxOemsx/TnpVMlhrRXlYa0Zx/Y0dkZVFYVnlOVGMz/TWpVek5USUAuanBn.jpg)
|
||||
|
||||
Just for reference, here’s [the original image](https://m.media-amazon.com/images/M/MV5BMmQ3ZmY4NzYtY2VmYi00ZDRmLTgyODAtZWYzZjhlNzk1NzU2XkEyXkFqcGdeQXVyNTc3MjUzNTI@.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 generate imgproxy URLs in the [Generating the URL](generating_the_url.md) 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 the URL](signing_the_url.md) guide to learn how to secure your imgproxy installation from attackers.
|
||||
@ -1,59 +1,5 @@
|
||||
# imgproxy
|
||||
# imgproxy documentation
|
||||
|
||||
imgproxy is a fast and secure standalone server for resizing and converting remote images. The guiding principles behind imgproxy are security, speed, and simplicity.
|
||||
You can find imgproxy documentation at the [documentation website](https://docs.imgproxy.net).
|
||||
|
||||
imgproxy is able to quickly and easily resize images on the fly, and it's well-equipped to handle a large amount of image resizing. imgproxy is a fast, secure replacement for all the image resizing code inside your web application (such as resizing libraries, or code that calls ImageMagick or GraphicsMagic). It's also an indispensable tool for processing images from a remote source. With imgproxy, you don’t need to repeatedly prepare images to fit your design every time it changes.
|
||||
|
||||
To get an even better introduction, and to dive deeper into the nitty gritty details, check out this article: [imgproxy: Resize your images instantly and securely](https://evilmartians.com/chronicles/introducing-imgproxy)
|
||||
|
||||
<a href="https://evilmartians.com/?utm_source=imgproxy" target="_blank">
|
||||
<img src="https://evilmartians.com/badges/sponsored-by-evil-martians_v2.0_for-dark-bg.svg" alt="Sponsored by Evil Martians" width="236" height="54">
|
||||
</a>
|
||||
|
||||
#### Simplicity
|
||||
|
||||
> "No code is better than no code."
|
||||
|
||||
imgproxy only includes the must-have features for image processing, fine-tuning and security. Specifically,
|
||||
|
||||
* It would be great to be able to rotate, flip and apply masks to images, but in most of the cases, it is possible — and is much easier — to do that using CSS3.
|
||||
* It may be great to have built-in HTTP caching of some kind, but it is way better to use a Content-Delivery Network or a caching proxy server for this, as you will have to do this sooner or later in the production environment.
|
||||
* It might be useful to have everything built in — such as HTTPS support — but an easy way to solve that would be just to use a proxying HTTP server such as nginx.
|
||||
|
||||
#### Speed
|
||||
|
||||
imgproxy takes advantage of probably the most efficient image processing library out there – `libvips`. It’s scary fast and comes with a very low memory footprint. Thanks to libvips, we can readily and extemporaneously process a massive amount of images.
|
||||
|
||||
imgproxy uses Go’s raw (no wrappers) native `net/http` package to omit any overhead while processing requests and provides the best possible HTTP support.
|
||||
|
||||
You can take a look at some benchmarking results and compare imgproxy with some well-known alternatives in our [benchmark report](https://github.com/imgproxy/imgproxy/blob/master/BENCHMARK.md).
|
||||
|
||||
#### Security
|
||||
|
||||
In terms of security, the massive processing of remote images is a potentially dangerous endeavor. There are a number of possible attack vectors, so it’s a good idea to take an approach that considers attack prevention measures as a priority. Here’s how imgproxy does this:
|
||||
|
||||
* imgproxy checks the image type and its “real” dimensions when downloading. The image will not be fully downloaded if it has an unknown format or if the dimensions are too big (you can set the max allowed dimensions). This is how imgproxy protects from so called "image bombs”, like those described in [this doc](https://www.bamsoftware.com/hacks/deflate.html).
|
||||
|
||||
* imgproxy protects image URLs with a signature, so an attacker cannot enact a denial-of-service attack by requesting multiple image resizes.
|
||||
|
||||
* imgproxy supports authorization by HTTP header. This prevents imgproxy from being used directly by an attacker, but allows it to be used via a CDN or a caching server — simply by adding a header to a proxy or CDN config.
|
||||
|
||||
## Author
|
||||
|
||||
Sergey "[DarthSim](https://github.com/DarthSim)" Alexandrovich
|
||||
|
||||
## Special thanks
|
||||
|
||||
Many thanks to:
|
||||
|
||||
* [Roman Shamin](https://github.com/romashamin) for the awesome logo.
|
||||
* [Alena Kirdina](https://github.com/egodyston) and [Alexander Madyankin](https://github.com/madyankin) for the great website.
|
||||
* [John Cupitt](https://github.com/jcupitt) for developing [libvips](https://github.com/libvips/libvips) and for helping me optimize its usage with imgproxy.
|
||||
* [Kirill Kuznetsov](https://github.com/dragonsmith) for the [Helm chart](https://github.com/imgproxy/imgproxy-helm).
|
||||
* [Travis Turner](https://github.com/Travis-Turner) for keeping the documentation in good shape.
|
||||
|
||||
## License
|
||||
|
||||
imgproxy is licensed under the MIT license.
|
||||
|
||||
See [LICENSE](https://github.com/imgproxy/imgproxy/blob/master/LICENSE) for the full license text.
|
||||
The documentation source code was moved to https://github.com/imgproxy/imgproxy-docs
|
||||
|
||||
@ -1,35 +0,0 @@
|
||||
* [Getting started](GETTING_STARTED.md)
|
||||
* [Pro version<img src="/assets/pro.svg">](https://imgproxy.net/#pro)
|
||||
* [Installation](installation.md)
|
||||
* Configuration
|
||||
* [Configuration](configuration.md)
|
||||
* [Loading environment variables](loading_environment_variables.md)
|
||||
* Generating the URL
|
||||
* [Generating the URL](generating_the_url.md)
|
||||
* [Getting the image info<img title="imgproxy Pro feature" src="/assets/pro.svg">](getting_the_image_info.md)
|
||||
* [Signing the URL](signing_the_url.md)
|
||||
* [Encrypting the source URL<img src="/assets/pro.svg">](encrypting_the_source_url.md)
|
||||
* [Presets](presets.md)
|
||||
* Features
|
||||
* [Watermark](watermark.md)
|
||||
* [Object detection<img title="imgproxy Pro feature" src="/assets/pro.svg">](object_detection.md)
|
||||
* [Autoquality<img title="imgproxy Pro feature" src="/assets/pro.svg">](autoquality.md)
|
||||
* [Best format<img title="imgproxy Pro feature" src="/assets/pro.svg">](best_format.md)
|
||||
* [Chained pipelines<img title="imgproxy Pro feature" src="/assets/pro.svg">](chained_pipelines.md)
|
||||
* Image sources
|
||||
* [Local files](serving_local_files.md)
|
||||
* [Amazon S3](serving_files_from_s3.md)
|
||||
* [Google Cloud Storage](serving_files_from_google_cloud_storage.md)
|
||||
* [Azure Blob Storage](serving_files_from_azure_blob_storage.md)
|
||||
* [OpenStack Object Storage ("Swift")](serving_files_from_openstack_swift.md)
|
||||
* Monitoring
|
||||
* [New Relic](new_relic.md)
|
||||
* [Prometheus](prometheus.md)
|
||||
* [Datadog](datadog.md)
|
||||
* [OpenTelemetry](open_telemetry.md)
|
||||
* [Amazon CloudWatch](cloud_watch.md)
|
||||
* Miscellaneous
|
||||
* [Image formats support](image_formats_support.md)
|
||||
* [About processing pipeline](about_processing_pipeline.md)
|
||||
* [Health check](healthcheck.md)
|
||||
* [Memory usage tweaks](memory_usage_tweaks.md)
|
||||
@ -1,16 +0,0 @@
|
||||
# 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 gaussian blur and sharpen 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.
|
||||
@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Pro 6.4.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path fill="#77b33a" d="M256 48a208 208 0 1 1 0 416 208 208 0 1 1 0-416zm0 464A256 256 0 1 0 256 0a256 256 0 1 0 0 512zM369 209c9.4-9.4 9.4-24.6 0-33.9s-24.6-9.4-33.9 0l-111 111-47-47c-9.4-9.4-24.6-9.4-33.9 0s-9.4 24.6 0 33.9l64 64c9.4 9.4 24.6 9.4 33.9 0L369 209z"/></svg>
|
||||
|
Before Width: | Height: | Size: 504 B |
@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Pro 6.4.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path fill="#fff" d="M208 0H332.1c12.7 0 24.9 5.1 33.9 14.1l67.9 67.9c9 9 14.1 21.2 14.1 33.9V336c0 26.5-21.5 48-48 48H208c-26.5 0-48-21.5-48-48V48c0-26.5 21.5-48 48-48zM48 128h80v64H64V448H256V416h64v48c0 26.5-21.5 48-48 48H48c-26.5 0-48-21.5-48-48V176c0-26.5 21.5-48 48-48z"/></svg>
|
||||
|
Before Width: | Height: | Size: 515 B |
@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Pro 6.4.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path fill="#e65855" d="M256 48a208 208 0 1 1 0 416 208 208 0 1 1 0-416zm0 464A256 256 0 1 0 256 0a256 256 0 1 0 0 512zM175 175c-9.4 9.4-9.4 24.6 0 33.9l47 47-47 47c-9.4 9.4-9.4 24.6 0 33.9s24.6 9.4 33.9 0l47-47 47 47c9.4 9.4 24.6 9.4 33.9 0s9.4-24.6 0-33.9l-47-47 47-47c9.4-9.4 9.4-24.6 0-33.9s-24.6-9.4-33.9 0l-47 47-47-47c-9.4-9.4-24.6-9.4-33.9 0z"/></svg>
|
||||
|
Before Width: | Height: | Size: 590 B |
@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512"><!--! Font Awesome Pro 6.4.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path fill="#fff" d="M524.531,69.836a1.5,1.5,0,0,0-.764-.7A485.065,485.065,0,0,0,404.081,32.03a1.816,1.816,0,0,0-1.923.91,337.461,337.461,0,0,0-14.9,30.6,447.848,447.848,0,0,0-134.426,0,309.541,309.541,0,0,0-15.135-30.6,1.89,1.89,0,0,0-1.924-.91A483.689,483.689,0,0,0,116.085,69.137a1.712,1.712,0,0,0-.788.676C39.068,183.651,18.186,294.69,28.43,404.354a2.016,2.016,0,0,0,.765,1.375A487.666,487.666,0,0,0,176.02,479.918a1.9,1.9,0,0,0,2.063-.676A348.2,348.2,0,0,0,208.12,430.4a1.86,1.86,0,0,0-1.019-2.588,321.173,321.173,0,0,1-45.868-21.853,1.885,1.885,0,0,1-.185-3.126c3.082-2.309,6.166-4.711,9.109-7.137a1.819,1.819,0,0,1,1.9-.256c96.229,43.917,200.41,43.917,295.5,0a1.812,1.812,0,0,1,1.924.233c2.944,2.426,6.027,4.851,9.132,7.16a1.884,1.884,0,0,1-.162,3.126,301.407,301.407,0,0,1-45.89,21.83,1.875,1.875,0,0,0-1,2.611,391.055,391.055,0,0,0,30.014,48.815,1.864,1.864,0,0,0,2.063.7A486.048,486.048,0,0,0,610.7,405.729a1.882,1.882,0,0,0,.765-1.352C623.729,277.594,590.933,167.465,524.531,69.836ZM222.491,337.58c-28.972,0-52.844-26.587-52.844-59.239S193.056,219.1,222.491,219.1c29.665,0,53.306,26.82,52.843,59.239C275.334,310.993,251.924,337.58,222.491,337.58Zm195.38,0c-28.971,0-52.843-26.587-52.843-59.239S388.437,219.1,417.871,219.1c29.667,0,53.307,26.82,52.844,59.239C470.715,310.993,447.538,337.58,417.871,337.58Z"/></svg>
|
||||
|
Before Width: | Height: | Size: 1.5 KiB |
@ -1,273 +0,0 @@
|
||||
let clink = null;
|
||||
|
||||
if (window.DOCSIFY_ROUTER_MODE === "history") {
|
||||
clink = Docsify.dom.create("link");
|
||||
clink.rel = "canonical";
|
||||
Docsify.dom.appendTo(Docsify.dom.head, clink);
|
||||
}
|
||||
|
||||
const documentTitleBase = document.title;
|
||||
|
||||
const linksMenu = '<div class="links-menu">' +
|
||||
'<a href="https://imgproxy.net" target="_blank" title="Website"><img src="/assets/website.svg" /></a>' +
|
||||
'<a href="https://github.com/imgproxy" target="_blank" title="GitHub"><img src="/assets/github.svg" /></a>' +
|
||||
'<a href="https://twitter.com/imgproxy_net" target="_blank" title="Twitter"><img src="/assets/twitter.svg" /></a>' +
|
||||
'<a href="https://discord.gg/5GgpXgtC9u" target="_blank" title="Discord"><img src="/assets/discord.svg" /></a>' +
|
||||
'<a href="https://github.com/sponsors/imgproxy" target="_blank" title="Sponsor"><img src="/assets/heart.svg" /></a>' +
|
||||
'</div>';
|
||||
|
||||
const docEditBase = 'https://github.com/imgproxy/imgproxy/edit/master/docs/';
|
||||
|
||||
const proBadge = Docsify.dom.create("img");
|
||||
proBadge.setAttribute("src", "/assets/pro.svg");
|
||||
proBadge.setAttribute("title", "This feature is available in imgproxy Pro");
|
||||
|
||||
const proBadgeRegex = /\!\[pro\]\((\S+)\)/g;
|
||||
const proLink = `<a class="badge" href="https://imgproxy.net/#pro" target="_blank">${proBadge.outerHTML}</a>`;
|
||||
|
||||
const oldProBadge = "<i class='badge badge-pro'></i>";
|
||||
|
||||
const configRegex = /^\* `([^`]+)`:/gm;
|
||||
|
||||
const copyCodeBtn = '<button class="copy-code" title="Copy code"></button>';
|
||||
|
||||
const defaultVersions = [["latest", "latest"]];
|
||||
|
||||
const configureDocsify = (additionalVersions, latestVersion, latestTag) => {
|
||||
const versions = defaultVersions.concat(additionalVersions);
|
||||
|
||||
const versionAliases = {};
|
||||
|
||||
const versionSelect = ['<div class="sidebar-version-select"><select id="version-selector" name="version">'];
|
||||
versions.forEach(([version, tag]) => {
|
||||
const value = version == latestVersion ? "" : version;
|
||||
versionSelect.push(`<option value="${value}">${version}</value>`);
|
||||
|
||||
if (version !== "latest") {
|
||||
versionAliases[`/${version}/(.*)`] =
|
||||
`https://raw.githubusercontent.com/imgproxy/imgproxy/${tag}/docs/$1`;
|
||||
versionAliases[`/${version}/`] =
|
||||
`https://raw.githubusercontent.com/imgproxy/imgproxy/${tag}/docs/README.md`;
|
||||
}
|
||||
});
|
||||
versionSelect.push('</select></div>');
|
||||
|
||||
if (latestTag === "latest") latestTag = "master";
|
||||
|
||||
window.$docsify = {
|
||||
name: '<a id="home-link" class="app-name-link" href="/"><img src="/assets/logo.svg"></a>' +
|
||||
linksMenu +
|
||||
versionSelect.join(""),
|
||||
nameLink: false,
|
||||
loadSidebar: true,
|
||||
relativePath: true,
|
||||
subMaxLevel: 3,
|
||||
auto2top: true,
|
||||
routerMode: window.DOCSIFY_ROUTER_MODE || "hash",
|
||||
noEmoji: true,
|
||||
alias: Object.assign(versionAliases, {
|
||||
'/latest/': 'README.md',
|
||||
'/latest/(.*)': '$1',
|
||||
'/([0-9]+\.[0-9]+)/(.*)': 'https://raw.githubusercontent.com/imgproxy/imgproxy/v$1.0/docs/$2',
|
||||
'/([0-9]+\.[0-9]+)/': 'https://raw.githubusercontent.com/imgproxy/imgproxy/v$1.0/docs/README.md',
|
||||
'/(.*)': `https://raw.githubusercontent.com/imgproxy/imgproxy/${latestTag}/docs/$1`,
|
||||
'/': `https://raw.githubusercontent.com/imgproxy/imgproxy/${latestTag}/docs/README.md`,
|
||||
}),
|
||||
search: {
|
||||
namespace: 'docs-imgproxy',
|
||||
depth: 6,
|
||||
// pathNamespaces: versions.map(v => "/" + v[0]),
|
||||
pathNamespaces: /^(\/(latest|([0-9]+\.[0-9]+)))?/,
|
||||
},
|
||||
namespaces: [
|
||||
{
|
||||
id: "version",
|
||||
values: versions.map(v => v[0]),
|
||||
optional: true,
|
||||
selector: "#version-selector",
|
||||
}
|
||||
],
|
||||
plugins: window.$docsify.plugins.concat([
|
||||
(hook, vm) => {
|
||||
window.DocsifyVM = vm;
|
||||
|
||||
hook.beforeEach(() => {
|
||||
if (clink)
|
||||
clink.href = "https://docs.imgproxy.net" + vm.route.path;
|
||||
});
|
||||
|
||||
hook.doneEach(() => {
|
||||
const appNameLink = Docsify.dom.find("#home-link");
|
||||
|
||||
if (!appNameLink) return;
|
||||
|
||||
appNameLink.href = vm.config.currentNamespace;
|
||||
});
|
||||
|
||||
hook.doneEach(() => {
|
||||
if (document.title != documentTitleBase)
|
||||
document.title += " | " + documentTitleBase;
|
||||
});
|
||||
|
||||
|
||||
hook.afterEach(html => {
|
||||
const docName = vm.route.file.replace(
|
||||
/https\:\/\/raw.githubusercontent\.com\/(.*)\/docs\//, ''
|
||||
);
|
||||
|
||||
if (!docName) return html;
|
||||
|
||||
const editButton = '<a class="github-edit-btn" title="Edit on GitHub" href="' +
|
||||
docEditBase + docName +
|
||||
'" target="_blank">' +
|
||||
'Edit on <strong>GitHub</strong>' +
|
||||
'</a>';
|
||||
|
||||
return html + editButton;
|
||||
})
|
||||
|
||||
hook.beforeEach((content, next) => {
|
||||
content = content
|
||||
.replaceAll(proBadgeRegex, proLink)
|
||||
.replaceAll(oldProBadge, proLink);
|
||||
|
||||
content = content
|
||||
.replaceAll("📝", '<i class="icon icon-note"></i>')
|
||||
.replaceAll("⚠️", '<i class="icon icon-warn"></i>')
|
||||
.replaceAll("✅", '<i class="icon icon-check"></i>')
|
||||
.replaceAll("❌", '<i class="icon icon-cross"></i>')
|
||||
.replaceAll("⏳", '<i class="icon icon-hourglass"></i>');
|
||||
|
||||
if (vm.route.path.endsWith('/configuration'))
|
||||
content = content.replaceAll(configRegex, '* <code id="$1">$1</code>:');
|
||||
|
||||
next(content);
|
||||
})
|
||||
|
||||
hook.doneEach(() => {
|
||||
const badges = Docsify.dom.findAll(".sidebar .badge-pro");
|
||||
badges.forEach(b => { b.replaceWith(proBadge.cloneNode()) });
|
||||
|
||||
// Docsify cuts off "target" sometimes
|
||||
const links = Docsify.dom.findAll("a.badge");
|
||||
links.forEach(l => { l.setAttribute("target", "_blank") });
|
||||
|
||||
const codeBlocks = Docsify.dom.findAll('pre[data-lang]');
|
||||
codeBlocks.forEach(elm =>
|
||||
elm.insertAdjacentHTML('beforeend', copyCodeBtn));
|
||||
})
|
||||
|
||||
hook.mounted(() => {
|
||||
const content = Docsify.dom.find('.content');
|
||||
|
||||
content.addEventListener('click', function(e) {
|
||||
if (!e.target.classList.contains('copy-code'))
|
||||
return;
|
||||
|
||||
const btn = e.target;
|
||||
const code = Docsify.dom.find(btn.parentNode, 'code');
|
||||
|
||||
navigator.clipboard.writeText(code.innerText).then(() => {
|
||||
btn.classList.add('copy-code-success');
|
||||
setTimeout(() => {
|
||||
btn.classList.remove('copy-code-success');
|
||||
}, 1500);
|
||||
}).catch((err) =>{
|
||||
console.log(`Can't copy code: ${err}`);
|
||||
|
||||
btn.classList.add('copy-code-error');
|
||||
setTimeout(() => {
|
||||
btn.classList.remove('copy-code-error');
|
||||
}, 1500);
|
||||
});
|
||||
});
|
||||
})
|
||||
}
|
||||
])
|
||||
}
|
||||
}
|
||||
|
||||
const initDocsify = (versions, latestVersion, latestTag) => {
|
||||
configureDocsify(versions, latestVersion, latestTag);
|
||||
window.runDocsify();
|
||||
};
|
||||
|
||||
const VERSIONS_KEY = "imgproxy.versions";
|
||||
const VERSIONS_ETAG_KEY = "imgproxy.versions.etag";
|
||||
|
||||
let latestVersion = "latest";
|
||||
let latestTag = "latest";
|
||||
|
||||
let storedVersions = [];
|
||||
let storedVersionsJson = localStorage.getItem(VERSIONS_KEY);
|
||||
let storedVersionsEtag = localStorage.getItem(VERSIONS_ETAG_KEY);
|
||||
|
||||
if (storedVersionsJson) {
|
||||
try {
|
||||
storedVersions = JSON.parse(storedVersionsJson);
|
||||
} catch {
|
||||
storedVersions = [];
|
||||
}
|
||||
}
|
||||
|
||||
if (storedVersions?.length)
|
||||
[latestVersion, latestTag] = storedVersions[0];
|
||||
else {
|
||||
// Just in case storedVersions is not an array
|
||||
storedVersions = [];
|
||||
storedVersionsEtag = null;
|
||||
}
|
||||
|
||||
fetch(
|
||||
"https://api.github.com/repos/imgproxy/imgproxy/releases",
|
||||
{
|
||||
headers: {
|
||||
"Accept": "application/json",
|
||||
"If-None-Match": storedVersionsEtag,
|
||||
},
|
||||
},
|
||||
).then((resp) => {
|
||||
if (resp.status === 304) {
|
||||
initDocsify(storedVersions, latestVersion, latestTag);
|
||||
return;
|
||||
}
|
||||
|
||||
if (resp.status != 200)
|
||||
throw new Error(`Can't fetch imgproxy versions: ${resp.statusText}`);
|
||||
|
||||
resp.json().then((data) => {
|
||||
const uniq = {};
|
||||
const fetchedVersions = [];
|
||||
|
||||
data.forEach((release) => {
|
||||
if (release.draft || release.prerelease) return;
|
||||
|
||||
var tag = release.tag_name;
|
||||
var matches = tag?.match(/^v([0-9]+\.[0-9]+)/);
|
||||
|
||||
if (!matches?.length) return;
|
||||
|
||||
var version = matches[1];
|
||||
|
||||
if (uniq[version]) return;
|
||||
|
||||
fetchedVersions.push([version, tag]);
|
||||
uniq[version] = true;
|
||||
});
|
||||
|
||||
if (fetchedVersions.length)
|
||||
[latestVersion, latestTag] = fetchedVersions[0];
|
||||
|
||||
localStorage.setItem(VERSIONS_KEY, JSON.stringify(fetchedVersions));
|
||||
localStorage.setItem(VERSIONS_ETAG_KEY, resp.headers.get("Etag"));
|
||||
|
||||
initDocsify(fetchedVersions, latestVersion, latestTag);
|
||||
|
||||
}).catch((e) => {
|
||||
initDocsify(storedVersions, latestVersion, latestTag);
|
||||
throw e;
|
||||
});
|
||||
}).catch((e) => {
|
||||
initDocsify(storedVersions, latestVersion, latestTag);
|
||||
throw e;
|
||||
});
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
Binary file not shown.
|
Before Width: | Height: | Size: 2.3 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 316 B |
Binary file not shown.
|
Before Width: | Height: | Size: 5.5 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 695 B |
Binary file not shown.
|
Before Width: | Height: | Size: 2.2 KiB |
@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><!--! Font Awesome Pro 6.4.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path fill="#fff" d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg>
|
||||
|
Before Width: | Height: | Size: 1.5 KiB |
@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Pro 6.4.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path fill="#fff" d="M47.6 300.4L228.3 469.1c7.5 7 17.4 10.9 27.7 10.9s20.2-3.9 27.7-10.9L464.4 300.4c30.4-28.3 47.6-68 47.6-109.5v-5.8c0-69.9-50.5-129.5-119.4-141C347 36.5 300.6 51.4 268 84L256 96 244 84c-32.6-32.6-79-47.5-124.6-39.9C50.5 55.6 0 115.2 0 185.1v5.8c0 41.5 17.2 81.2 47.6 109.5z"/></svg>
|
||||
|
Before Width: | Height: | Size: 533 B |
@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" height="1em" viewBox="0 0 384 512"><!--! Font Awesome Free 6.4.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path fill="#f6c744" d="M32 0C14.3 0 0 14.3 0 32S14.3 64 32 64V75c0 42.4 16.9 83.1 46.9 113.1L146.7 256 78.9 323.9C48.9 353.9 32 394.6 32 437v11c-17.7 0-32 14.3-32 32s14.3 32 32 32H64 320h32c17.7 0 32-14.3 32-32s-14.3-32-32-32V437c0-42.4-16.9-83.1-46.9-113.1L237.3 256l67.9-67.9c30-30 46.9-70.7 46.9-113.1V64c17.7 0 32-14.3 32-32s-14.3-32-32-32H320 64 32zM96 75V64H288V75c0 19-5.6 37.4-16 53H112c-10.3-15.6-16-34-16-53zm16 309c3.5-5.3 7.6-10.3 12.1-14.9L192 301.3l67.9 67.9c4.6 4.6 8.6 9.6 12.1 14.9H112z"/></svg>
|
||||
|
Before Width: | Height: | Size: 758 B |
@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="266" height="100" viewBox="0 0 1883 710"><path fill="#fff" d="M665 302.1v20.7h41.2v82.7H665v20.7h104.6v-20.7h-40.4V302.1H665zm34.9-31c0 10.1 5.9 17.2 17.4 17.2 11.5 0 17.4-7.1 17.4-17.2s-5.9-17.2-17.4-17.2c-11.5 0-17.4 7.1-17.4 17.2zm102.8 31v124h23v-80c0-17.8 6.1-25.8 19.7-25.8s19.7 8.1 19.7 25.8v80h23v-80c0-18 6.1-25.8 19.7-25.8s19.7 7.9 19.7 25.8v80h23v-86.4c0-24.6-14.9-40.9-37.2-40.9-11.7 0-22.4 5.2-28.5 13.6h-4.2c-6.1-8.7-15.3-13.6-26.6-13.6-11.7 0-20.5 4.1-25.3 11.6h-2.9v-8.3h-23.1zm303.2 120v-120h-23v11.2h-6.3c-5.9-8.7-19-14.5-33.1-14.5-33.1 0-55.2 24.4-55.2 61.2 0 36.2 22.2 60.4 55.2 60.4 13.6 0 26.8-5.4 33.1-13.6h6.3V420c0 19-13.4 30.2-36 30.2-18 0-31.4-7.4-36-19.8h-22.6c1.3 24.4 24.7 40.5 58.6 40.5 36.6-.1 59-19.5 59-48.8zm-94.6-62.1c0-24.6 13.8-39.7 36.4-39.7 22.6 0 36.4 15.1 36.4 39.7s-13.8 39.7-36.4 39.7c-22.6 0-36.4-15.1-36.4-39.7zm203.4-61.2c-15.1 0-28.9 6.2-34.7 15.7h-6.3v-12.4h-23v165.4h23v-53.8h6.3c5.8 9.5 19.7 15.7 34.7 15.7 33.9 0 56.5-26.1 56.5-65.3s-22.6-65.3-56.5-65.3zm-41.8 65.4c0-27.1 14.2-43.8 37.7-43.8 23.4 0 37.7 16.7 37.7 43.8 0 27.1-14.2 43.8-37.7 43.8-23.5 0-37.7-16.8-37.7-43.8zm133.8-62.1v20.7h29.4v82.7h-29.4v20.7h97.6v-20.7h-45.2V360c0-26.3 8.2-39.7 24.3-39.7 13 0 19.7 7.6 19.7 22.3v14.6h23.8v-17.9c0-25.2-13.6-40.5-36-40.5-11.9 0-21.8 4.5-27.2 12.8h-6.3v-9.5h-50.7zM1520 429.5c37 0 61.7-26.1 61.7-65.3s-24.7-65.3-61.7-65.3-61.7 26.1-61.7 65.3 24.6 65.3 61.7 65.3zm-38.7-65.3c0-27.1 14.7-43.8 38.7-43.8 24.1 0 38.7 16.7 38.7 43.8 0 27.1-14.6 43.8-38.7 43.8s-38.7-16.8-38.7-43.8zm127.6 62h26.4l29.3-43 2.3-6h2.1l2.3 6 28.9 43h28l-40.8-61 43.3-63.1H1705l-32.8 47.6-2.3 6h-2.1l-2.3-6-31.4-47.6h-27.6l42.9 65.1-40.5 59zm146.9-124.1 45 113.7h18.8l-7.5 21.1c-3.8 9.3-7.5 13.2-14.4 13.2-7.5 0-11.5-3.9-15.5-13.2h-20.9c1.7 21.7 15.3 33.9 37.7 33.9 15.1 0 27.4-9.9 33.5-26.9l50.6-141.8h-23.4l-32.8 93h-9l-36.6-93h-25.5z"/><defs><path id="a" d="M0 160h659v555H0z"/></defs><clipPath id="b"><use xlink:href="#a" overflow="visible"/></clipPath><g clip-path="url(#b)"><linearGradient id="c" x1="277.262" x2="277.262" y1="157.87" y2="552" gradientTransform="matrix(1 0 0 -1 0 712)" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#1d40b2"/><stop offset="1" stop-color="#1680d6"/></linearGradient><path fill="url(#c)" d="M554.5 232.4V160h-72.3v20.1H313.4V160h-72.3v20.1H72.3V160H0v72.4h20.1v88.5H0v72.4h20.1v88.5H0v72.4h72.3V534h168.8v20.1h72.3V534h168.8v20.1h72.3v-72.4h-20.1v-88.5h20.1v-72.4h-20.1v-88.5h20.1zm-297.3-56.3h40.2v40.2h-40.2v-40.2zM16.1 216.3v-40.2h40.2v40.2H16.1zm0 160.9V337h40.2v40.2H16.1zM56.3 538H16.1v-40.2h40.2V538zm241.1 0h-40.2v-40.2h40.2V538zm184.8-36.2H313.4v-20.1h-72.3v20.1H72.3v-20.1H52.2v-88.5h20.1v-72.4H52.2v-88.5h20.1v-20.1h168.8v20.1h72.3v-20.1h168.8v20.1h20.1v88.5h-20.1v72.4h20.1v88.5h-20.1v20.1zm56.3-4V538h-40.2v-40.2h40.2zm0-160.8v40.2h-40.2V337h40.2zm-40.2-120.7v-40.2h40.2v40.2h-40.2z"/><path fill="#1960c4" d="M285.3 328.9h-16.1V349h-20.1v16.1h20.1v20.1h16.1v-20.1h20.1V349h-20.1v-20.1z"/><path fill="#fff" fill-rule="evenodd" d="M575.4 651.4h77.8L519.8 517.9l55.6 133.5zm-55.6-133.5v189l55.5-55.6" clip-rule="evenodd"/></g><path fill="none" d="M0 0h1883v710H0z"/></svg>
|
||||
|
Before Width: | Height: | Size: 3.2 KiB |
@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Pro 6.4.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path fill="#5da4f7" d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512zM216 336h24V272H216c-13.3 0-24-10.7-24-24s10.7-24 24-24h48c13.3 0 24 10.7 24 24v88h8c13.3 0 24 10.7 24 24s-10.7 24-24 24H216c-13.3 0-24-10.7-24-24s10.7-24 24-24zm40-208a32 32 0 1 1 0 64 32 32 0 1 1 0-64z"/></svg>
|
||||
|
Before Width: | Height: | Size: 516 B |
@ -1 +0,0 @@
|
||||
<svg height="47" viewBox="0 0 47 47" width="47" xmlns="http://www.w3.org/2000/svg"><path d="m23 23v-3h1v3h3v1h-3v3h-1v-3h-3v-1z" fill="#56575b" fill-rule="evenodd"/></svg>
|
||||
|
Before Width: | Height: | Size: 171 B |
@ -1,6 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="64" height="27" viewBox="0 0 64 27">
|
||||
<svg fill="none" fill-rule="evenodd" x="5">
|
||||
<rect width="53" height="26" x=".5" y=".5" stroke="#40a6ff" rx="13"/>
|
||||
<path fill="#40a6ff" fill-rule="nonzero" d="M15.15 15.243V19h-2.198V8.336h4.16c.801 0 1.505.146 2.113.44.608.292 1.076.709 1.403 1.248.327.54.49 1.154.49 1.842 0 1.045-.357 1.87-1.072 2.472-.716.603-1.706.905-2.97.905h-1.927zm0-1.78h1.962c.581 0 1.024-.137 1.33-.41.305-.274.457-.664.457-1.172 0-.523-.153-.945-.461-1.267-.308-.322-.732-.489-1.274-.498h-2.015v3.347zm11.425 1.633h-1.75V19h-2.198V8.336h3.963c1.26 0 2.231.28 2.915.842.683.562 1.025 1.355 1.025 2.38 0 .728-.157 1.335-.472 1.82-.315.487-.792.873-1.432 1.162l2.307 4.357V19h-2.358l-2-3.904zm-1.75-1.78h1.772c.552 0 .98-.14 1.282-.42.303-.281.454-.668.454-1.162 0-.503-.143-.898-.428-1.186-.286-.288-.724-.432-1.315-.432h-1.765v3.2zm16.135.594c0 1.05-.186 1.97-.557 2.76-.37.792-.902 1.402-1.593 1.832-.69.43-1.483.644-2.376.644-.884 0-1.673-.212-2.366-.637-.693-.425-1.23-1.031-1.611-1.82-.381-.788-.574-1.695-.58-2.72v-.528c0-1.05.19-1.974.569-2.772.378-.799.913-1.411 1.604-1.839.69-.427 1.48-.64 2.369-.64.889 0 1.678.213 2.37.64.69.428 1.225 1.04 1.603 1.839.379.798.568 1.72.568 2.765v.476zm-2.227-.484c0-1.118-.2-1.968-.6-2.549-.4-.58-.972-.871-1.714-.871-.737 0-1.306.287-1.707.86-.4.574-.603 1.415-.608 2.524v.52c0 1.089.2 1.933.601 2.534.4.6.977.9 1.729.9.737 0 1.303-.289 1.699-.867.395-.579.596-1.422.6-2.53v-.52z"/>
|
||||
</svg>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 1.5 KiB |
@ -1,311 +0,0 @@
|
||||
:root {
|
||||
--white-5: #ffffff0d;
|
||||
--white-20: #fff3;
|
||||
|
||||
--base-color: rgb(255, 255, 255);
|
||||
|
||||
--mono-hue: var(--theme-hue);
|
||||
--mono-saturation: 10%;
|
||||
|
||||
--mono-shade4: hsl(var(--mono-hue), var(--mono-saturation), 10%);
|
||||
|
||||
--theme-hue : 208;
|
||||
--theme-saturation: 100%;
|
||||
--theme-lightness : 63%;
|
||||
|
||||
--base-background-color: rgb(13, 15, 21);
|
||||
--base-background-color-trans: rgba(13, 15, 21, 0);
|
||||
--base-font-family: 'Roboto',sans-serif;
|
||||
|
||||
--code-font-family: 'Martian Mono',monospace;
|
||||
--code-font-weight: 300;
|
||||
--code-block-border-radius: 0;
|
||||
--code-theme-background: var(--white-5);
|
||||
--code-inline-background: var(--white-20);
|
||||
|
||||
--blockquote-background: var(--white-5);
|
||||
--blockquote-border-width: 0 0 0 2px;
|
||||
|
||||
--heading-font-family: 'Roboto Condensed',sans-serif;
|
||||
--heading-h1-font-weight: 700;
|
||||
--heading-h2-font-weight: 700;
|
||||
--heading-h3-font-weight: 700;
|
||||
--heading-h4-font-weight: 700;
|
||||
--heading-h5-font-weight: 700;
|
||||
|
||||
--heading-h2-border-color: var(--white-20);
|
||||
--heading-h2-border-width: 0 0 2px;
|
||||
|
||||
--link-color: var(--theme-color);
|
||||
|
||||
--sidebar-background: var(--white-5);
|
||||
--sidebar-border-color: var(--white-20);
|
||||
--sidebar-border-width: 0 2px 0 0;
|
||||
--sidebar-width: 20rem;
|
||||
--sidebar-nav-link-before-content-l3: "";
|
||||
|
||||
--table-row-even-background: var(--base-background-color);
|
||||
|
||||
--selection-color: rgba(255, 255, 255, 0.3);
|
||||
|
||||
--search-input-background-color: var(--white-5);
|
||||
--search-input-border-color: var(--white-20);
|
||||
--search-input-border-width: 2px 0;
|
||||
}
|
||||
|
||||
.app-name-link img {
|
||||
width: 90%
|
||||
}
|
||||
|
||||
.content::before {
|
||||
content: "";
|
||||
position: absolute;
|
||||
top: 0;
|
||||
right: 0;
|
||||
width: 390px;
|
||||
height: 300px;
|
||||
background: url('/assets/pattern.svg');
|
||||
}
|
||||
|
||||
@media (max-width: 768px) {
|
||||
.content::before {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
|
||||
@media (min-width: 1200px) {
|
||||
:root {
|
||||
--base-font-size: 18px;
|
||||
--code-font-size: 14px;
|
||||
}
|
||||
}
|
||||
|
||||
@media (min-width: 1400px) {
|
||||
:root {
|
||||
--base-font-size: 20px;
|
||||
--code-font-size: 16px;
|
||||
}
|
||||
}
|
||||
|
||||
.markdown-section p {
|
||||
overflow-wrap: break-word;
|
||||
}
|
||||
|
||||
.markdown-section pre[data-lang] {
|
||||
border: 2px solid var(--white-20);
|
||||
}
|
||||
.markdown-section pre[data-lang]::after {
|
||||
display: none;
|
||||
}
|
||||
|
||||
.copy-code {
|
||||
appearance: none;
|
||||
cursor: pointer;
|
||||
position: absolute;
|
||||
top: 10px;
|
||||
right: 10px;
|
||||
width: 20px;
|
||||
height: 20px;
|
||||
border: none;
|
||||
padding: 0;
|
||||
background: none;
|
||||
background-image: url(/assets/copy.svg);
|
||||
background-position: center;
|
||||
background-size: contain;
|
||||
background-repeat: no-repeat;
|
||||
opacity: 0.8;
|
||||
}
|
||||
.copy-code:hover {
|
||||
opacity: 1;
|
||||
}
|
||||
.copy-code::before {
|
||||
content: "";
|
||||
position: absolute;
|
||||
display: block;
|
||||
font-size: 16px;
|
||||
font-weight: bold;
|
||||
line-height: 16px;
|
||||
height: 16px;
|
||||
left: 0;
|
||||
top: 50%;
|
||||
transform: translate3d(0, -50%, 0);
|
||||
}
|
||||
.copy-code-success {
|
||||
background-image: url(/assets/check.svg);
|
||||
opacity: 1;
|
||||
}
|
||||
.copy-code-success::before {
|
||||
content: "Copied!";
|
||||
color: #77b33a;
|
||||
}
|
||||
.copy-code-error {
|
||||
background-image: url(/assets/cross.svg);
|
||||
opacity: 1;
|
||||
}
|
||||
.copy-code-error::before {
|
||||
content: "Can't copy";
|
||||
color: #e65855;
|
||||
}
|
||||
.copy-code-success::before,
|
||||
.copy-code-error::before {
|
||||
padding-right: 8px;
|
||||
transform: translate3d(-100%, -50%, 0);
|
||||
transition: transform .2s;
|
||||
}
|
||||
|
||||
.loading {
|
||||
margin: 150px auto 0;
|
||||
position: relative;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.loading__spinner {
|
||||
--spinner-size: 50px;
|
||||
|
||||
box-sizing: border-box;
|
||||
width: var(--spinner-size);
|
||||
height: var(--spinner-size);
|
||||
margin: 0 auto;
|
||||
border: 1px solid rgba(255, 255, 255, 0.7);
|
||||
border-right-color: transparent;
|
||||
border-radius: 50%;
|
||||
animation: spinner 1s linear infinite;
|
||||
}
|
||||
|
||||
@keyframes spinner {
|
||||
0% {
|
||||
transform: rotate(0deg);
|
||||
}
|
||||
|
||||
100% {
|
||||
transform: rotate(360deg);
|
||||
}
|
||||
}
|
||||
|
||||
.sidebar-nav li {
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.sidebar-nav li>a:only-child {
|
||||
padding: var(--sidebar-nav-pagelink-padding, var(--sidebar-nav-link-padding));
|
||||
}
|
||||
|
||||
.badge img,
|
||||
.sidebar-nav li > a > img {
|
||||
display: inline-block;
|
||||
position: relative;
|
||||
height: 1em;
|
||||
top: .125em;
|
||||
}
|
||||
|
||||
.badge img:hover {
|
||||
filter: brightness(1.2);
|
||||
}
|
||||
|
||||
h1 .badge img, h3 .badge img, h3 .badge img {
|
||||
height: .8em;
|
||||
}
|
||||
|
||||
h1 .badge img, h3 .badge img, h3 .badge img, h4 .badge img, h5 .badge img {
|
||||
margin-left: .1em;
|
||||
}
|
||||
|
||||
i.icon::after {
|
||||
content: "";
|
||||
display: inline-block;
|
||||
position: relative;
|
||||
top: .125em;
|
||||
width: 1em;
|
||||
height: 1em;
|
||||
background-position: center;
|
||||
background-size: contain;
|
||||
background-repeat: no-repeat;
|
||||
}
|
||||
i.icon-note::after {
|
||||
background-image: url(/assets/note.svg);
|
||||
}
|
||||
i.icon-warn::after {
|
||||
background-image: url(/assets/warning.svg);
|
||||
}
|
||||
i.icon-check::after {
|
||||
background-image: url(/assets/check.svg);
|
||||
}
|
||||
i.icon-cross::after {
|
||||
background-image: url(/assets/cross.svg);
|
||||
}
|
||||
i.icon-hourglass::after {
|
||||
background-image: url(/assets/hourglass.svg);
|
||||
}
|
||||
|
||||
.github-edit-btn {
|
||||
display: block;
|
||||
position: fixed;
|
||||
bottom: 0;
|
||||
right: 1em;
|
||||
background: linear-gradient(0deg, #1d40b2, #1680d6);
|
||||
color: var(--base-color) !important;
|
||||
text-decoration: none !important;
|
||||
font-size: .8em;
|
||||
padding: 0.3em 1em;
|
||||
opacity: 0.75;
|
||||
z-index: 999;
|
||||
}
|
||||
|
||||
.github-edit-btn:hover {
|
||||
opacity: 1;
|
||||
}
|
||||
|
||||
@media (max-width: 768px) {
|
||||
.github-edit-btn {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
|
||||
.links-menu {
|
||||
width: 100%;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.links-menu a {
|
||||
margin: 0 .5em;
|
||||
}
|
||||
|
||||
.links-menu a img {
|
||||
height: 1em;
|
||||
}
|
||||
|
||||
.sidebar-version-select {
|
||||
position: relative;
|
||||
margin: var(--sidebar-nav-margin);
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
.sidebar-version-select > select {
|
||||
appearance: none;
|
||||
cursor: pointer;
|
||||
margin: 0;
|
||||
width: 100%;
|
||||
background: var(--white-5);
|
||||
border: 2px solid var(--white-20);
|
||||
border-radius: 0;
|
||||
padding: 0.35em 0.7em;
|
||||
color: var(--base-color);
|
||||
font-family: var(--base-font-family);
|
||||
}
|
||||
|
||||
.sidebar-version-select>select:hover {
|
||||
border: 2px solid var(--theme-color);
|
||||
}
|
||||
|
||||
.sidebar-version-select::after {
|
||||
content: "▼";
|
||||
color: var(--base-color);
|
||||
position: absolute;
|
||||
top: 50%;
|
||||
right: 1em;
|
||||
font-size: 16px;
|
||||
line-height: 16px;
|
||||
height: 16px;
|
||||
transform: translateY(-8px);
|
||||
pointer-events: none;
|
||||
}
|
||||
File diff suppressed because one or more lines are too long
@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Pro 6.4.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path fill="#fff" d="M459.37 151.716c.325 4.548.325 9.097.325 13.645 0 138.72-105.583 298.558-298.558 298.558-59.452 0-114.68-17.219-161.137-47.106 8.447.974 16.568 1.299 25.34 1.299 49.055 0 94.213-16.568 130.274-44.832-46.132-.975-84.792-31.188-98.112-72.772 6.498.974 12.995 1.624 19.818 1.624 9.421 0 18.843-1.3 27.614-3.573-48.081-9.747-84.143-51.98-84.143-102.985v-1.299c13.969 7.797 30.214 12.67 47.431 13.319-28.264-18.843-46.781-51.005-46.781-87.391 0-19.492 5.197-37.36 14.294-52.954 51.655 63.675 129.3 105.258 216.365 109.807-1.624-7.797-2.599-15.918-2.599-24.04 0-57.828 46.782-104.934 104.934-104.934 30.213 0 57.502 12.67 76.67 33.137 23.715-4.548 46.456-13.32 66.599-25.34-7.798 24.366-24.366 44.833-46.132 57.827 21.117-2.273 41.584-8.122 60.426-16.243-14.292 20.791-32.161 39.308-52.628 54.253z"/></svg>
|
||||
|
Before Width: | Height: | Size: 1.0 KiB |
@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Pro 6.4.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path fill="#f6c744" d="M256 32c14.2 0 27.3 7.5 34.5 19.8l216 368c7.3 12.4 7.3 27.7 .2 40.1S486.3 480 472 480H40c-14.3 0-27.6-7.7-34.7-20.1s-7-27.8 .2-40.1l216-368C228.7 39.5 241.8 32 256 32zm0 128c-13.3 0-24 10.7-24 24V296c0 13.3 10.7 24 24 24s24-10.7 24-24V184c0-13.3-10.7-24-24-24zm32 224a32 32 0 1 0 -64 0 32 32 0 1 0 64 0z"/></svg>
|
||||
|
Before Width: | Height: | Size: 567 B |
@ -1 +0,0 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Pro 6.4.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2023 Fonticons, Inc. --><path fill="#fff" d="M352 256c0 22.2-1.2 43.6-3.3 64H163.3c-2.2-20.4-3.3-41.8-3.3-64s1.2-43.6 3.3-64H348.7c2.2 20.4 3.3 41.8 3.3 64zm28.8-64H503.9c5.3 20.5 8.1 41.9 8.1 64s-2.8 43.5-8.1 64H380.8c2.1-20.6 3.2-42 3.2-64s-1.1-43.4-3.2-64zm112.6-32H376.7c-10-63.9-29.8-117.4-55.3-151.6c78.3 20.7 142 77.5 171.9 151.6zm-149.1 0H167.7c6.1-36.4 15.5-68.6 27-94.7c10.5-23.6 22.2-40.7 33.5-51.5C239.4 3.2 248.7 0 256 0s16.6 3.2 27.8 13.8c11.3 10.8 23 27.9 33.5 51.5c11.6 26 20.9 58.2 27 94.7zm-209 0H18.6C48.6 85.9 112.2 29.1 190.6 8.4C165.1 42.6 145.3 96.1 135.3 160zM8.1 192H131.2c-2.1 20.6-3.2 42-3.2 64s1.1 43.4 3.2 64H8.1C2.8 299.5 0 278.1 0 256s2.8-43.5 8.1-64zM194.7 446.6c-11.6-26-20.9-58.2-27-94.6H344.3c-6.1 36.4-15.5 68.6-27 94.6c-10.5 23.6-22.2 40.7-33.5 51.5C272.6 508.8 263.3 512 256 512s-16.6-3.2-27.8-13.8c-11.3-10.8-23-27.9-33.5-51.5zM135.3 352c10 63.9 29.8 117.4 55.3 151.6C112.2 482.9 48.6 426.1 18.6 352H135.3zm358.1 0c-30 74.1-93.6 130.9-171.9 151.6c25.5-34.2 45.2-87.7 55.3-151.6H493.4z"/></svg>
|
||||
|
Before Width: | Height: | Size: 1.2 KiB |
@ -1,127 +0,0 @@
|
||||
# Autoquality
|
||||
|
||||
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 [config options](configuration.md#autoquality) (for all images) or with [processing options](generating_the_url.md#autoquality) (for each image individually).
|
||||
|
||||
## None
|
||||
|
||||
Disable the autoquality.
|
||||
|
||||
**Method name:** `none`
|
||||
|
||||
#### Config example
|
||||
|
||||
```bash
|
||||
IMGPROXY_AUTOQUALITY_METHOD="none"
|
||||
```
|
||||
|
||||
#### Processing options example
|
||||
|
||||
```
|
||||
.../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 50 for AVIF is pretty the same as 80 for JPEG
|
||||
IMGPROXY_AUTOQUALITY_FORMAT_MAX="avif=50"
|
||||
```
|
||||
|
||||
#### Processing options example
|
||||
|
||||
```
|
||||
.../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 50 for AVIF is pretty the same as 80 for JPEG
|
||||
IMGPROXY_AUTOQUALITY_FORMAT_MIN="avif=40"
|
||||
IMGPROXY_AUTOQUALITY_FORMAT_MAX="avif=50"
|
||||
```
|
||||
|
||||
#### Processing options example
|
||||
|
||||
```
|
||||
.../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.
|
||||
|
||||
**📝 Note:** When this method is used, imgproxy will save JPEG images with the most optimal [advanced JPEG compression](configuration.md#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 50 for AVIF is pretty the same as 80 for JPEG
|
||||
IMGPROXY_AUTOQUALITY_FORMAT_MIN="avif=40"
|
||||
IMGPROXY_AUTOQUALITY_FORMAT_MAX="avif=50"
|
||||
# Neural networks paths for JPEG, WebP, and AVIF
|
||||
IMGPROXY_AUTOQUALITY_JPEG_NET="/networks/autoquality-jpeg.pb"
|
||||
IMGPROXY_AUTOQUALITY_WEBP_NET="/networks/autoquality-webp.pb"
|
||||
IMGPROXY_AUTOQUALITY_AVIF_NET="/networks/autoquality-avif.pb"
|
||||
```
|
||||
|
||||
**📝 Note:** 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
|
||||
|
||||
```
|
||||
.../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.
|
||||
@ -1,18 +0,0 @@
|
||||
# Best format
|
||||
|
||||
You can use the `best` value for the [format](generating_the_url.md#format) option or the [extension](generating_the_url.md#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.
|
||||
|
||||
**📝 Note:** imgproxy uses only the formats listed as [preferred](configuration.md#preferred-formats) when choosing the best format. It may also use AVIF or WebP if [AVIF/WebP support detection](configuration.md#avifwebp-support-detection) is enabled.
|
||||
|
||||
**📝 Note:** imgproxy will use AVIF or WebP _only_ if [AVIF/WebP support detection](configuration.md#avifwebp-support-detection) is enabled.
|
||||
|
||||
**📝 Note:** 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.md#skip-processing)
|
||||
@ -1,58 +0,0 @@
|
||||
# Chained pipelines
|
||||
|
||||
Though imgproxy's [processing pipeline](about_processing_pipeline.md) 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:
|
||||
|
||||
```
|
||||
.../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:
|
||||
|
||||
```
|
||||
.../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.
|
||||
|
||||
```
|
||||
.../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:
|
||||
|
||||
```
|
||||
test=width:300/height:300/-/width:200/height:200/-/width:100/height:200
|
||||
```
|
||||
|
||||
And the following URL:
|
||||
|
||||
```
|
||||
.../width:400/-/preset:test/width:500/-/width:600/...
|
||||
```
|
||||
|
||||
The result will look like this:
|
||||
|
||||
```
|
||||
.../width:400/-/width:500/height:300/-/width:600/height:200/-/width:100/height:200/...
|
||||
```
|
||||
@ -1,53 +0,0 @@
|
||||
# Amazon CloudWatch
|
||||
|
||||
imgproxy can send its metrics to Amazon CloudWatch. To use this feature, do the following:
|
||||
|
||||
1. Set the `IMGPROXY_CLOUD_WATCH_SERVICE_NAME` environment variable. imgproxy will use the value of this variable as a value for the `ServiceName` dimension.
|
||||
2. [Set up the necessary credentials](#set-up-credentials) to grant access to CloudWatch.
|
||||
3. _(optional)_ Specify the AWS region with `IMGPROXY_CLOUD_WATCH_REGION` or `AWS_REGION`. Default: `us-west-1`
|
||||
4. _(optional)_ Set the `IMGPROXY_CLOUD_WATCH_NAMESPACE` environment variable to be the desired CloudWatch namespace. Default: `imgproxy`
|
||||
|
||||
imgproxy sends the following metrics to CloudWatch:
|
||||
|
||||
* `RequestsInProgress`: the number of requests currently in progress
|
||||
* `ImagesInProgress`: the number of images currently in progress
|
||||
* `WorkersUtilization`, `ConcurrencyUtilization`: the percentage of imgproxy's workers utilization. Calculated as `RequestsInProgress / IMGPROXY_WORKERS * 100`
|
||||
* `BufferSize`: a summary of the download buffers sizes (in bytes)
|
||||
* `BufferDefaultSize`: calibrated default buffer size (in bytes)
|
||||
* `BufferMaxSize`: calibrated maximum buffer size (in bytes)
|
||||
* `VipsMemory`: libvips memory usage (in bytes)
|
||||
* `VipsMaxMemory`: libvips maximum memory usage (in bytes)
|
||||
* `VipsAllocs`: the number of active vips allocations
|
||||
|
||||
### Set up credentials
|
||||
|
||||
There are three ways to specify your AWS credentials. The credentials need to have rights to write metrics to CloudWatch:
|
||||
|
||||
#### 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 make calls to AWS CloudWatch.
|
||||
|
||||
* **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 darthsim/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
|
||||
```
|
||||
@ -1,556 +0,0 @@
|
||||
# Configuration
|
||||
|
||||
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.
|
||||
|
||||
You can also specify file paths using the command line by referencing a separate file containing hex-coded keys and salts line by line:
|
||||
|
||||
```bash
|
||||
imgproxy -keypath /path/to/file/with/key -saltpath /path/to/file/with/salt
|
||||
```
|
||||
|
||||
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')
|
||||
```
|
||||
|
||||
## 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_READ_TIMEOUT`: the maximum duration (in seconds) for reading the entire image request, including the body. Default: `10`
|
||||
* `IMGPROXY_WRITE_TIMEOUT`: the maximum duration (in seconds) for writing the response. Default: `10`
|
||||
* `IMGPROXY_KEEP_ALIVE_TIMEOUT`: the maximum duration (in seconds) to wait for the next request before closing the connection. When set to `0`, keep-alive is disabled. Default: `10`
|
||||
* `IMGPROXY_CLIENT_KEEP_ALIVE_TIMEOUT`: the maximum duration (in seconds) to wait for the next request before closing the HTTP client connection. The HTTP client is used to download source images. When set to `0`, keep-alive is disabled. Default: `90`
|
||||
* `IMGPROXY_DOWNLOAD_TIMEOUT`: the maximum duration (in seconds) for downloading the source image. Default: `5`
|
||||
* `IMGPROXY_WORKERS`: _(alias: `IMGPROXY_CONCURRENCY`)_ the maximum number of images an imgproxy instance can process simultaneously without creating a queue. Default: the number of CPU cores multiplied by two
|
||||
* `IMGPROXY_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 `Expires` and `Cache-Control: max-age` HTTP headers. 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. Default: `imgproxy/%current_version`
|
||||
* `IMGPROXY_USE_ETAG`: when set to `true`, enables using the [ETag](https://en.wikipedia.org/wiki/HTTP_ETag) HTTP header for HTTP cache control. Default: `false`
|
||||
* `IMGPROXY_ETAG_BUSTER`: change this to change ETags for all the images. Default: blank
|
||||
* `IMGPROXY_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_CUSTOM_REQUEST_HEADERS`:  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`:  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`:  a string that will be used as a custom header separator. Default: `\;`
|
||||
* `IMGPROXY_REQUEST_HEADERS_PASSTHROUGH`:  a list of names of incoming request headers that should be passed through to the source image request.
|
||||
* `IMGPROXY_RESPONSE_HEADERS_PASSTHROUGH`:  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`:  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: `16.8`
|
||||
|
||||
**⚠️ 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`
|
||||
|
||||
To check if the source image is SVG, imgproxy reads some amount of bytes; by default it reads a maximum of 32KB. However, you can change this value using the following variable:
|
||||
|
||||
* `IMGPROXY_MAX_SVG_CHECK_BYTES`: the maximum number of bytes imgproxy will read to recognize SVG files. If imgproxy is unable to recognize your SVG, try increasing this number. Default: `32768` (32KB)
|
||||
|
||||
Requests to some image sources may go through too many redirects or enter an infinite loop. You can limit the number of allowed redirects:
|
||||
|
||||
* `IMGPROXY_MAX_REDIRECTS`: the max number of redirects imgproxy can follow while requesting the source image. When set to `0`, no redirects are allowed. Default: `10`
|
||||
|
||||
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
|
||||
|
||||
**📝 Note:** Read more about source URL encryption in the [encrypting the source URL guide](encrypting_the_source_url.md).
|
||||
|
||||
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_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_DEVELOPMENT_ERRORS_MODE`: when `true`, imgproxy will respond with detailed error messages. Not recommended for production because some errors may contain stack traces.
|
||||
|
||||
* `IMGPROXY_ALLOW_SECURITY_OPTIONS`: when `true`, allows usage of security-related processing options such as `max_src_resolution`, `max_src_file_size`, `max_animation_frames`, and `max_animation_frame_resolution`. 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`.
|
||||
|
||||
* `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.
|
||||
|
||||
|
||||
## 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: `avif=65`
|
||||
|
||||
### Advanced JPEG compression
|
||||
|
||||
* `IMGPROXY_JPEG_PROGRESSIVE`: when `true`, enables progressive JPEG compression. Default: `false`
|
||||
* `IMGPROXY_JPEG_NO_SUBSAMPLE`:  when `true`, chrominance subsampling is disabled. This will improve quality at the cost of larger file size. Default: `false`
|
||||
* `IMGPROXY_JPEG_TRELLIS_QUANT`:  when `true`, enables trellis quantisation for each 8x8 block. Reduces file size but increases compression time. Default: `false`
|
||||
* `IMGPROXY_JPEG_OVERSHOOT_DERINGING`:  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`:  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`:  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 GIF compression
|
||||
|
||||
* `IMGPROXY_GIF_OPTIMIZE_FRAMES`:  when true, enables GIF frame optimization. This may produce a smaller result, but may increase compression time.
|
||||
* `IMGPROXY_GIF_OPTIMIZE_TRANSPARENCY`:  when true, enables GIF transparency optimization. This may produce a smaller result, but may also increase compression time. -->
|
||||
|
||||
### Advanced WebP compression
|
||||
|
||||
* `IMGPROXY_WEBP_COMPRESSION`:  the compression method to use. Supported values are `lossy`, `near_lossless`, and `lossless`. Default: `lossy`
|
||||
|
||||
### 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: `9`
|
||||
|
||||
### Autoquality
|
||||
|
||||
imgproxy can calculate the quality of the resulting image based on selected metric. Read more in the [Autoquality](autoquality.md) 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`:  the method of quality calculation. Default: `none`
|
||||
* `IMGPROXY_AUTOQUALITY_TARGET`:  desired value of the autoquality method metric. Default: 0.02
|
||||
* `IMGPROXY_AUTOQUALITY_MIN`:  minimal quality imgproxy can use. Default: 70
|
||||
* `IMGPROXY_AUTOQUALITY_FORMAT_MIN`:  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=40`
|
||||
* `IMGPROXY_AUTOQUALITY_MAX`:  the maximum quality imgproxy can use. Default: 80
|
||||
* `IMGPROXY_AUTOQUALITY_FORMAT_MAX`:  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=50`
|
||||
* `IMGPROXY_AUTOQUALITY_ALLOWED_ERROR`:  the allowed `IMGPROXY_AUTOQUALITY_TARGET` error. Applicable only to `dssim` and `ml` methods. Default: 0.001
|
||||
* `IMGPROXY_AUTOQUALITY_MAX_RESOLUTION`:  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`:  the path to the neural network for JPEG.
|
||||
* `IMGPROXY_AUTOQUALITY_WEBP_NET`:  the path to the neural network for WebP.
|
||||
* `IMGPROXY_AUTOQUALITY_AVIF_NET`:  the path to the neural network for AVIF.
|
||||
|
||||
## AVIF/WebP support detection
|
||||
|
||||
imgproxy can use the `Accept` HTTP header to detect if the browser supports AVIF or WebP and use it as the default format. This feature is disabled by default and can be enabled by the following options:
|
||||
|
||||
* `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_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.
|
||||
|
||||
**📝 Note:** imgproxy prefers AVIF over WebP. This means that if both AVIF and WebP detection/enforcement are enabled and the browser supports both of them, AVIF will be used.
|
||||
|
||||
**📝 Note:** 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.
|
||||
|
||||
**📝 Note:** When AVIF/WebP 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
|
||||
|
||||
**📝 Note:** When AVIF/WebP support detection is enabled and the browser supports AVIF/WebP, 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.
|
||||
|
||||
**📝 Note:** Processing can only be skipped when the requested format is the same as the source format.
|
||||
|
||||
**📝 Note:** Video thumbnail processing can't be skipped.
|
||||
|
||||
## Best format
|
||||
|
||||
You can use the `best` value for the [format](generating_the_url.md#format) option or the [extension](generating_the_url.md#extension) to make imgproxy pick the best format for the resultant image.
|
||||
|
||||
* `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.md#skip-processing)
|
||||
|
||||
Check out the [Best format](best_format.md) guide to learn more.
|
||||
|
||||
## 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`:  when `true`, enables video thumbnail generation. Default: `false`
|
||||
* `IMGPROXY_VIDEO_THUMBNAIL_SECOND`:  the timestamp of the frame (in seconds) that will be used for a thumbnail. Default: `1`
|
||||
* `IMGPROXY_VIDEO_THUMBNAIL_KEYFRAMES`:  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_PROBE_SIZE`:  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`:  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_OPACITY`: the watermark's base opacity
|
||||
* `IMGPROXY_WATERMARKS_CACHE_SIZE`:  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](watermark.md) guide.
|
||||
|
||||
## Unsharp masking
|
||||
|
||||
imgproxy Pro can apply unsharp masking to your images.
|
||||
|
||||
* `IMGPROXY_UNSHARP_MASKING_MODE`:  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`:  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`:  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`:  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_FACE_DETECTION`:  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_CONFIG`:  the path to the neural network config. Default: blank
|
||||
* `IMGPROXY_OBJECT_DETECTION_WEIGHTS`:  the path to the neural network weights. Default: blank
|
||||
* `IMGPROXY_OBJECT_DETECTION_CLASSES`:  the path to the text file with the classes names, one per line. Default: blank
|
||||
* `IMGPROXY_OBJECT_DETECTION_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: 416
|
||||
* `IMGPROXY_OBJECT_DETECTION_CONFIDENCE_THRESHOLD`:  detections with confidences 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
|
||||
|
||||
## 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_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 `Expires` and `Cache-Control: max-age` HTTP headers when a fallback image was used. When blank or `0`, the value from `IMGPROXY_TTL` is used.
|
||||
* `IMGPROXY_FALLBACK_IMAGES_CACHE_SIZE`:  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](presets.md) 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`:  a set of info preset definitions, comma divided. Example: `default=xmp:0/blurhash:4:3`. Default: blank
|
||||
|
||||
#### Using a command line argument
|
||||
|
||||
```bash
|
||||
imgproxy -presets /path/to/file/with/presets -info-presets /path/to/file/with/info-presets
|
||||
```
|
||||
|
||||
This file should contain preset definitions, one per line. Lines starting with `#` are treated as comments. Example:
|
||||
|
||||
```
|
||||
default=resizing_type:fill/enlarge:1
|
||||
|
||||
# Sharpen the image to make it look better
|
||||
sharp=sharpen:0.7
|
||||
|
||||
# Blur the image to hide details
|
||||
blurry=blur:2
|
||||
```
|
||||
|
||||
### Using only presets
|
||||
|
||||
imgproxy can be switched into "presets-only mode". In this mode, imgproxy accepts only `preset` option arguments as processing options. Example: `http://imgproxy.example.com/unsafe/thumbnail:blurry:watermarked/plain/http://example.com/images/curiosity.jpg@png`
|
||||
|
||||
* `IMGPROXY_ONLY_PRESETS`: when `true`, enables presets-only mode. Default: `false`
|
||||
* `IMGPROXY_INFO_ONLY_PRESETS`: when `true`, enables presets-only mode for the [info](getting_the_image_info.md) endpoint. Default: `IMGPROXY_ONLY_PRESETS` value
|
||||
|
||||
## Image sources
|
||||
|
||||
### Local files :id=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](serving_local_files.md) guide to learn more.
|
||||
|
||||
### Amazon S3 :id=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_MULTI_REGION`: when `true`, allows using S3 buckets from different regions
|
||||
|
||||
Check out the [Serving files from S3](serving_files_from_s3.md) guide to learn more.
|
||||
|
||||
### Google Cloud Storage :id=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. When set, enables image fetching from Google Cloud Storage buckets. Default: blank
|
||||
* `IMGPROXY_GCS_ENDPOINT`: a custom Google Cloud Storage endpoint to being used by imgproxy
|
||||
|
||||
Check out the [Serving files from Google Cloud Storage](serving_files_from_google_cloud_storage.md) guide to learn more.
|
||||
|
||||
### Azure Blob Storage :id=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
|
||||
|
||||
Check out the [Serving files from Azure Blob Storage](serving_files_from_azure_blob_storage.md) guide to learn more.
|
||||
|
||||
### OpenStack Object Storage ("Swift") :id=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
|
||||
|
||||
Check out the [Serving files from OpenStack Object Storage](serving_files_from_openstack_swift.md) 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`
|
||||
|
||||
**📝 Note:** Replacements defined in `IMGPROXY_URL_REPLACEMENTS` are applied before `IMGPROXY_BASE_URL` is added.
|
||||
|
||||
## Metrics
|
||||
|
||||
### New Relic :id=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
|
||||
|
||||
Check out the [New Relic](new_relic.md) guide to learn more.
|
||||
|
||||
### Prometheus :id=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](prometheus.md) guide to learn more.
|
||||
|
||||
### Datadog :id=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
|
||||
|
||||
**⚠️ 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](datadog.md) guide to learn more.
|
||||
|
||||
### OpenTelemetry :id=opentelemetry-metrics
|
||||
|
||||
imgproxy can send request traces to an OpenTelemetry collector:
|
||||
|
||||
* `IMGPROXY_OPEN_TELEMETRY_ENDPOINT`: OpenTelemetry collector endpoint (`host:port`). Default: blank
|
||||
* `IMGPROXY_OPEN_TELEMETRY_PROTOCOL`: OpenTelemetry collector protocol. Supported protocols are `grpc`, `https`, and `http`. Default: `grpc`
|
||||
* `IMGPROXY_OPEN_TELEMETRY_SERVICE_NAME`: OpenTelemetry service name. Default: `imgproxy`
|
||||
* `IMGPROXY_OPEN_TELEMETRY_ENABLE_METRICS`: when `true`, imgproxy will send metrics over OpenTelemetry Metrics API. 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_GRPC_INSECURE`: when `true`, imgproxy will use an insecure GRPC connection unless the collector TLS certificate is not provided. Default: `true`
|
||||
* `IMGPROXY_OPEN_TELEMETRY_PROPAGATORS`: a list of OpenTelemetry text map propagators, comma divided. Supported propagators are `tracecontext`, `baggage`, `b3`, `b3multi`, `jaeger`, `xray`, and `ottrace`. Default: blank
|
||||
* `IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR`: OpenTelemetry trace ID generator. Supported generators are `xray` and `random`. Default: `xray`
|
||||
* `IMGPROXY_OPEN_TELEMETRY_CONNECTION_TIMEOUT`: the maximum duration (in seconds) for establishing a connection to the OpenTelemetry collector. Default: `5`
|
||||
|
||||
Check out the [OpenTelemetry](open_telemetry.md) guide to learn more.
|
||||
|
||||
### Amazon CloudWatch metrics :id=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](cloud_watch.md) 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`
|
||||
|
||||
### 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`
|
||||
|
||||
**📝 Note:** imgproxy always uses structured log format for syslog.
|
||||
|
||||
## Memory usage tweaks
|
||||
|
||||
**⚠️ Warning:** We highly recommended reading the [Memory usage tweaks](memory_usage_tweaks.md) 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_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_STRIP_METADATA`: when `true`, imgproxy will strip all metadata (EXIF, IPTC, etc.) from JPEG and WebP output images. Default: `true`
|
||||
* `IMGPROXY_KEEP_COPYRIGHT`: when `true`, imgproxy will not remove copyright info while stripping metadata. Default: `true`
|
||||
* `IMGPROXY_STRIP_METADATA_DPI`:  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_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_SVG_FIX_UNSUPPORTED`: when `true`, imgproxy will try to replace SVG features unsupported by librsvg to minimize SVG rendering error. This config only takes effect on SVG rasterization. Default: `false`
|
||||
* `IMGPROXY_HEALTH_CHECK_MESSAGE`:  the content of the health check response. Default: `imgproxy is running`
|
||||
* `IMGPROXY_HEALTH_CHECK_PATH`: an additional path of the health check. Default: blank
|
||||
@ -1,42 +0,0 @@
|
||||
# Datadog
|
||||
|
||||
imgproxy can send its metrics to Datadog. To use this feature, do the following:
|
||||
|
||||
1. Install & configure the Datadog Trace Agent (>= 5.21.1).
|
||||
2. Set the `IMGPROXY_DATADOG_ENABLE` environment variable to `true`.
|
||||
3. Configure the Datadog tracer using `ENV` variables provided by [the package](https://github.com/DataDog/dd-trace-go):
|
||||
|
||||
* `DD_AGENT_HOST`: sets the address to connect to for sending metrics to the Datadog Agent. Default: `localhost`
|
||||
* `DD_TRACE_AGENT_PORT`: sets the Datadog Agent Trace port. Default: `8126`
|
||||
* `DD_DOGSTATSD_PORT`: set the DogStatsD port. Default: `8125`
|
||||
* `DD_SERVICE`: sets the desired application name. Default: `imgproxy`
|
||||
* `DD_ENV`: specifies the environment to which all traces will be submitted. Default: empty
|
||||
* `DD_TRACE_SOURCE_HOSTNAME`: specifies the hostname with which to mark outgoing traces. Default: empty
|
||||
* `DD_TRACE_REPORT_HOSTNAME`: when `true`, sets hostname to `os.Hostname()` with which to mark outgoing traces. Default: `false`
|
||||
* `DD_TAGS`: sets a key/value pair which will be set as a tag on all traces. Example: `DD_TAGS=datacenter:njc,key2:value2`. Default: empty
|
||||
* `DD_TRACE_ANALYTICS_ENABLED`: allows specifying whether Trace Search & Analytics should be enabled for integrations. Default: `false`
|
||||
* `DD_RUNTIME_METRICS_ENABLED`: enables automatic collection of runtime metrics every 10 seconds. Default: `false`
|
||||
* `DD_TRACE_STARTUP_LOGS`: causes various startup info to be written when the tracer starts. Default: `true`
|
||||
* `DD_TRACE_DEBUG`: enables detailed logs. Default: `false`
|
||||
4. _(optional)_ Set the `IMGPROXY_DATADOG_ENABLE_ADDITIONAL_METRICS` environment variable to `true` to collect the [additional metrics](#additional-metrics).
|
||||
|
||||
imgproxy will send the following info to Datadog:
|
||||
|
||||
* Response time
|
||||
* Queue time
|
||||
* Image downloading time
|
||||
* Image processing time
|
||||
* Errors that occurred while downloading and processing image
|
||||
|
||||
## Additional metrics
|
||||
|
||||
When the `IMGPROXY_DATADOG_ENABLE_ADDITIONAL_METRICS` environment variable is set to `true`, imgproxy will send the following additional metrics to Datadog:
|
||||
|
||||
* `imgproxy.requests_in_progress`: the number of requests currently in progress
|
||||
* `imgproxy.images_in_progress`: the number of images currently in progress
|
||||
* `imgproxy.buffer.size`: a histogram of the download buffers sizes (in bytes)
|
||||
* `imgproxy.buffer.default_size`: calibrated default buffer size (in bytes)
|
||||
* `imgproxy.buffer.max_size`: calibrated maximum buffer size (in bytes)
|
||||
* `imgproxy.vips.memory`: libvips memory usage (in bytes)
|
||||
* `imgproxy.vips.max_memory`: libvips maximum memory usage (in bytes)
|
||||
* `imgproxy.vips.allocs`: the number of active vips allocations
|
||||
@ -1,98 +0,0 @@
|
||||
# Encrypting the source URL
|
||||
|
||||
If you don't want to reveal your source URLs, you can encrypt them with the AES-CBC algorithm.
|
||||
|
||||
### Configuring source URL encryption
|
||||
|
||||
The only thing needed for source URL encryption is a key:
|
||||
|
||||
* `IMGPROXY_SOURCE_URL_ENCRYPTION_KEY`: hex-encoded key used for source URL encryption. Default: blank
|
||||
|
||||
The key should be either 16, 24, or 32 bytes long for AES-128-CBC, AES-192-CBC, or AES-256-CBC, respectively.
|
||||
|
||||
If you need a random key in a hurry, you can quickly generate one using the following snippet:
|
||||
|
||||
```bash
|
||||
echo $(xxd -g 2 -l 32 -p /dev/random | tr -d '\n')
|
||||
```
|
||||
|
||||
### Encrypting the source URL
|
||||
|
||||
* Pad your source URL using the [PKCS #7](https://en.wikipedia.org/wiki/Padding_(cryptography)#PKCS#5_and_PKCS#7) method so it becomes 16-byte aligned. Some libraries like Ruby's `openssl` do the message padding for you
|
||||
* Generate a 16-byte long initialization vector (IV)
|
||||
* Encrypt the padded source URL with the AES-CBC algorithm using the configured key and the IV generated in the previous step
|
||||
* Create the following string: IV + encrypted URL
|
||||
* Encode the result of the previous step with URL-safe Base64
|
||||
|
||||
#### IV generation
|
||||
|
||||
AES-CBC requires IV to be unique between unencrypted messages (source URLs in our case). Usually, it's recommended to use a counter when generating an IV to be sure it never repeats. However, in our case, this leads to a major drawback: using a unique IV every time you encrypt the same source URL will lead to different cipher texts and thus different imgproxy URLs. And this leads to a situation where requests to imgproxy will never hit the CDNs cache.
|
||||
|
||||
On the other hand, reusing the IV with the same message is safe but ONLY while with this message. Thus, there are some tradeoffs:
|
||||
|
||||
1. Cache IVs. Store IV somewhere so you need to generate it only once for each source URL and extract it if needed. Depending on the level of security you need, you may also want to encrypt stored IVs with a different key so a DB leak won't reveal the message-IV pairs.
|
||||
2. Use a deterministic method of generation. For example, you can calculate an HMAC hash of the plain source URL with a different key and truncate it to the IV size. Though this method doesn't guarantee that it will always generate unique IVs, the chances of generating repeatable IVs with it are considerably rare.
|
||||
|
||||
### Example
|
||||
|
||||
**You can find helpful code snippets in various programming languages in the [examples](https://github.com/imgproxy/imgproxy/tree/master/examples) folder. There's a good chance you'll find a snippet in your favorite programming language that you'll be able to use right away.**
|
||||
|
||||
And here is a step-by-step example of a source URL encryption:
|
||||
|
||||
Before we start, we need an encryption key. We will use the AES-256-CBC algorithm in this example, so we need a 32-byte key. Let's assume we used a random generator and got the following hex-encoded key:
|
||||
|
||||
```
|
||||
1eb5b0e971ad7f45324c1bb15c947cb207c43152fa5c6c7f35c4f36e0c18e0f1
|
||||
```
|
||||
|
||||
Run imgproxy using this encryption key, like so:
|
||||
|
||||
```bash
|
||||
IMGPROXY_SOURCE_URL_ENCRYPTION_KEY="1eb5b0e971ad7f45324c1bb15c947cb207c43152fa5c6c7f35c4f36e0c18e0f1" imgproxy
|
||||
```
|
||||
|
||||
Next, assume that you have the following source URL:
|
||||
|
||||
```
|
||||
http://example.com/images/curiosity.jpg
|
||||
```
|
||||
|
||||
It's 39-byte long, so we should align it to 16 bytes using the PKCS #7 method:
|
||||
|
||||
```
|
||||
http://example.com/images/curiosity.jpg\09\09\09\09\09\09\09\09\09
|
||||
```
|
||||
|
||||
**📝 Note:** From this point on, we'll show unprintable characters in `\NN` format where `NN` is a hex representation of the byte.
|
||||
|
||||
Next, we need an initialization vector (IV). Let's assume we generated the following IV:
|
||||
|
||||
```
|
||||
\A7\95\63\A2\B3\5D\86\CE\E6\45\1C\3C\80\0F\53\5A
|
||||
```
|
||||
|
||||
We'll use our encription key and IV encrypt a 16-byte-aligned source URL with the AES-256-CBC algorithm:
|
||||
|
||||
```
|
||||
\84\65\19\C8\B7\97\59\2E\CE\A3\78\DD\44\25\45\A4\48\43\4A\AD\04\A5\B7\A8\50\01\22\CC\7E\65\1C\FF\71\57\3C\89\54\D8\6E\1B\0D\B3\13\41\2F\50\47\69
|
||||
```
|
||||
|
||||
Add the IV to the beginning:
|
||||
|
||||
```
|
||||
\A7\95\63\A2\B3\5D\86\CE\E6\45\1C\3C\80\0F\53\5A\84\65\19\C8\B7\97\59\2E\CE\A3\78\DD\44\25\45\A4\48\43\4A\AD\04\A5\B7\A8\50\01\22\CC\7E\65\1C\FF\71\57\3C\89\54\D8\6E\1B\0D\B3\13\41\2F\50\47\69
|
||||
```
|
||||
|
||||
And finally, encode the result with URL-safe Base64:
|
||||
|
||||
```
|
||||
p5VjorNdhs7mRRw8gA9TWoRlGci3l1kuzqN43UQlRaRIQ0qtBKW3qFABIsx-ZRz_cVc8iVTYbhsNsxNBL1BHaQ
|
||||
```
|
||||
|
||||
Now you can put this encrypted URL in the imgproxy URL path, prepending it with the `/enc/` segment:
|
||||
|
||||
```
|
||||
/unsafe/rs:fit:300:300/enc/p5VjorNdhs7mRRw8gA9TWoRlGci3l1kuzqN43UQlRaRIQ0qtBKW3qFABIsx-ZRz_cVc8iVTYbhsNsxNBL1BHaQ
|
||||
```
|
||||
|
||||
**📝 Note:** The imgproxy URL in this example is not signed but signing URLs is especially important when using encrypted source URLs to prevent a padding oracle attack.
|
||||
@ -1,978 +0,0 @@
|
||||
# Generating the URL
|
||||
|
||||
The URL should contain the signature, processing options, and source URL, like this:
|
||||
|
||||
```
|
||||
/%signature/%processing_options/plain/%source_url@%extension
|
||||
/%signature/%processing_options/%encoded_source_url.%extension
|
||||
```
|
||||
|
||||
Check out the [example](#example) at the end of this guide.
|
||||
|
||||
## Signature
|
||||
|
||||
**⚠️ Warning:** The signature part should always be present in a URL. If the signature check is disabled (no key/salt pairs are provided), the signature part may contain anything (for example, `unsafe` or `_`).
|
||||
|
||||
A signature protects your URL from being altered by an attacker. It is highly recommended to sign imgproxy URLs when imgproxy is being used in production.
|
||||
|
||||
Once you set up your [URL signature](configuration.md#url-signature), check out the [Signing the URL](signing_the_url.md) guide to find out how to sign your URLs. Otherwise, since the signature still needs to be present, feel free to use any string here.
|
||||
|
||||
## Processing options
|
||||
|
||||
Processing options should be specified as URL parts divided by slashes (`/`). A processing option has the following format:
|
||||
|
||||
```
|
||||
%option_name:%argument1:%argument2:...:argumentN
|
||||
```
|
||||
|
||||
The list of processing options does not define imgproxy's processing pipeline. Instead, imgproxy already comes with a specific, built-in image processing pipeline for maximum performance. Read more about this in the [About processing pipeline](about_processing_pipeline.md) guide.
|
||||
|
||||
imgproxy supports the following processing options:
|
||||
|
||||
### Resize
|
||||
|
||||
```
|
||||
resize:%resizing_type:%width:%height:%enlarge:%extend
|
||||
rs:%resizing_type:%width:%height:%enlarge:%extend
|
||||
```
|
||||
|
||||
This is a meta-option that defines the [resizing type](#resizing-type), [width](#width), [height](#height), [enlarge](#enlarge), and [extend](#extend). All arguments are optional and can be omitted to use their default values.
|
||||
|
||||
### Size
|
||||
|
||||
```
|
||||
size:%width:%height:%enlarge:%extend
|
||||
s:%width:%height:%enlarge:%extend
|
||||
```
|
||||
|
||||
This is a meta-option that defines the [width](#width), [height](#height), [enlarge](#enlarge), and [extend](#extend). All arguments are optional and can be omitted to use their default values.
|
||||
|
||||
### Resizing type
|
||||
|
||||
```
|
||||
resizing_type:%resizing_type
|
||||
rt:%resizing_type
|
||||
```
|
||||
|
||||
Defines how imgproxy will resize the source image. Supported resizing types are:
|
||||
|
||||
* `fit`: resizes the image while keeping aspect ratio to fit a given size.
|
||||
* `fill`: resizes the image while keeping aspect ratio to fill a given size and crops projecting parts.
|
||||
* `fill-down`: the same as `fill`, but if the resized image is smaller than the requested size, imgproxy will crop the result to keep the requested aspect ratio.
|
||||
* `force`: resizes the image without keeping the aspect ratio.
|
||||
* `auto`: if both source and resulting dimensions have the same orientation (portrait or landscape), imgproxy will use `fill`. Otherwise, it will use `fit`.
|
||||
|
||||
Default: `fit`
|
||||
|
||||
### Resizing algorithm :id=resizing-algorithm
|
||||
|
||||
```
|
||||
resizing_algorithm:%algorithm
|
||||
ra:%algorithm
|
||||
```
|
||||
|
||||
Defines the algorithm that imgproxy will use for resizing. Supported algorithms are `nearest`, `linear`, `cubic`, `lanczos2`, and `lanczos3`.
|
||||
|
||||
Default: `lanczos3`
|
||||
|
||||
### Width
|
||||
|
||||
```
|
||||
width:%width
|
||||
w:%width
|
||||
```
|
||||
|
||||
Defines the width of the resulting image. When set to `0`, imgproxy will calculate width using the defined height and source aspect ratio. When set to `0` and resizing type is `force`, imgproxy will keep the original width.
|
||||
|
||||
Default: `0`
|
||||
|
||||
### Height
|
||||
|
||||
```
|
||||
height:%height
|
||||
h:%height
|
||||
```
|
||||
|
||||
Defines the height of the resulting image. When set to `0`, imgproxy will calculate resulting height using the defined width and source aspect ratio. When set to `0` and resizing type is `force`, imgproxy will keep the original height.
|
||||
|
||||
Default: `0`
|
||||
|
||||
### Min width
|
||||
|
||||
```
|
||||
min-width:%width
|
||||
mw:%width
|
||||
```
|
||||
|
||||
Defines the minimum width of the resulting image.
|
||||
|
||||
**⚠️ Warning:** When both `width` and `min-width` are set, the final image will be cropped according to `width`, so use this combination with care.
|
||||
|
||||
Default: `0`
|
||||
|
||||
### Min height
|
||||
|
||||
```
|
||||
min-height:%height
|
||||
mh:%height
|
||||
```
|
||||
|
||||
Defines the minimum height of the resulting image.
|
||||
|
||||
**⚠️ Warning:** When both `height` and `min-height` are set, the final image will be cropped according to `height`, so use this combination with care.
|
||||
|
||||
Default: `0`
|
||||
|
||||
### Zoom
|
||||
|
||||
```
|
||||
zoom:%zoom_x_y
|
||||
z:%zoom_x_y
|
||||
|
||||
zoom:%zoom_x:%zoom_y
|
||||
z:%zoom_x:%zoom_y
|
||||
```
|
||||
|
||||
When set, imgproxy will multiply the image dimensions according to these factors. The values must be greater than 0.
|
||||
|
||||
Can be combined with `width` and `height` options. In this case, imgproxy calculates scale factors for the provided size and then multiplies it with the provided zoom factors.
|
||||
|
||||
**📝 Note:** Unlike the `dpr` option, the `zoom` option doesn't affect gravities offsets, watermark offsets, and paddings.
|
||||
|
||||
Default: `1`
|
||||
|
||||
### Dpr
|
||||
|
||||
```
|
||||
dpr:%dpr
|
||||
```
|
||||
|
||||
When set, imgproxy will multiply the image dimensions according to this factor for HiDPI (Retina) devices. The value must be greater than 0.
|
||||
|
||||
**📝 Note:** The `dpr` option affects gravities offsets, watermark offsets, and paddings to make the resulting image structures with and without the `dpr` option applied match.
|
||||
|
||||
Default: `1`
|
||||
|
||||
### Enlarge
|
||||
|
||||
```
|
||||
enlarge:%enlarge
|
||||
el:%enlarge
|
||||
```
|
||||
|
||||
When set to `1`, `t` or `true`, imgproxy will enlarge the image if it is smaller than the given size.
|
||||
|
||||
Default: `false`
|
||||
|
||||
### Extend
|
||||
|
||||
```
|
||||
extend:%extend:%gravity
|
||||
ex:%extend:%gravity
|
||||
```
|
||||
|
||||
* When `extend` is set to `1`, `t` or `true`, imgproxy will extend the image if it is smaller than the given size.
|
||||
* `gravity` _(optional)_ accepts the same values as the [gravity](#gravity) option, except `sm`. When `gravity` is not set, imgproxy will use `ce` gravity without offsets.
|
||||
|
||||
Default: `false:ce:0:0`
|
||||
|
||||
### Extend aspect ratio
|
||||
|
||||
```
|
||||
extend_aspect_ratio:%extend:%gravity
|
||||
extend_ar:%extend:%gravity
|
||||
exar:%extend:%gravity
|
||||
```
|
||||
|
||||
* When `extend` is set to `1`, `t` or `true`, imgproxy will extend the image to the requested aspect ratio.
|
||||
* `gravity` _(optional)_ accepts the same values as the [gravity](#gravity) option, except `sm`. When `gravity` is not set, imgproxy will use `ce` gravity without offsets.
|
||||
|
||||
Default: `false:ce:0:0`
|
||||
|
||||
### Gravity
|
||||
|
||||
```
|
||||
gravity:%type:%x_offset:%y_offset
|
||||
g:%type:%x_offset:%y_offset
|
||||
```
|
||||
|
||||
When imgproxy needs to cut some parts of the image, it is guided by the gravity option.
|
||||
|
||||
* `type` - specifies the gravity type. Available values:
|
||||
* `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)
|
||||
* `ce`: center
|
||||
* `x_offset`, `y_offset` - (optional) specifies the gravity offset along the X and Y axes.
|
||||
|
||||
Default: `ce:0:0`
|
||||
|
||||
**Special gravities**:
|
||||
|
||||
* `gravity:sm`: smart gravity. `libvips` detects the most "interesting" section of the image and considers it as the center of the resulting image. Offsets are not applicable here.
|
||||
* `gravity:obj:%class_name1:%class_name2:...:%class_nameN`:  object-oriented gravity. imgproxy [detects objects](object_detection.md) of provided classes on the image and calculates the resulting image center using their positions. If class names are omited, imgproxy will use all the detected objects.
|
||||
* `gravity:fp:%x:%y`: the gravity focus point . `x` and `y` are floating point numbers between 0 and 1 that define the coordinates of the center of the resulting image. Treat 0 and 1 as right/left for `x` and top/bottom for `y`.
|
||||
|
||||
### Crop
|
||||
|
||||
```
|
||||
crop:%width:%height:%gravity
|
||||
c:%width:%height:%gravity
|
||||
```
|
||||
|
||||
Defines an area of the image to be processed (crop before resize).
|
||||
|
||||
* `width` and `height` define the size of the area:
|
||||
* When `width` or `height` is greater than or equal to `1`, imgproxy treats it as an absolute value.
|
||||
* When `width` or `height` is less than `1`, imgproxy treats it as a relative value.
|
||||
* When `width` or `height` is set to `0`, imgproxy will use the full width/height of the source image.
|
||||
* `gravity` _(optional)_ accepts the same values as the [gravity](#gravity) option. When `gravity` is not set, imgproxy will use the value of the [gravity](#gravity) option.
|
||||
|
||||
### Trim
|
||||
|
||||
```
|
||||
trim:%threshold:%color:%equal_hor:%equal_ver
|
||||
t:%threshold:%color:%equal_hor:%equal_ver
|
||||
```
|
||||
|
||||
Removes surrounding background.
|
||||
|
||||
* `threshold` - color similarity tolerance.
|
||||
* `color` - _(optional)_ a hex-coded value of the color that needs to be cut off.
|
||||
* `equal_hor` - _(optional)_ set to `1`, `t` or `true`, imgproxy will cut only equal parts from left and right sides. That means that if 10px of background can be cut off from the left and 5px from the right, then 5px will be cut off from both sides. For example, this can be useful if objects on your images are centered but have non-symmetrical shadow.
|
||||
* `equal_ver` - _(optional)_ acts like `equal_hor` but for top/bottom sides.
|
||||
|
||||
**⚠️ Warning:** Trimming requires an image to be fully loaded into memory. This disables scale-on-load and significantly increases memory usage and processing time. Use it carefully with large images.
|
||||
|
||||
**📝 Note:** If you know background color of your images then setting it explicitly via `color` will also save some resources because imgproxy won't need to automatically detect it.
|
||||
|
||||
**📝 Note:** Use a `color` value of `FF00FF` for trimming transparent backgrounds as imgproxy uses magenta as a transparency key.
|
||||
|
||||
**📝 Note:** The trimming of animated images is not supported.
|
||||
|
||||
### Padding
|
||||
|
||||
```
|
||||
padding:%top:%right:%bottom:%left
|
||||
pd:%top:%right:%bottom:%left
|
||||
```
|
||||
|
||||
Defines padding size using CSS-style syntax. All arguments are optional but at least one dimension must be set. Padded space is filled according to the [background](#background) option.
|
||||
|
||||
* `top` - top padding (and for all other sides if they haven't been explicitly st)
|
||||
* `right` - right padding (and left if it hasn't been explicitly set)
|
||||
* `bottom` - bottom padding
|
||||
* `left` - left padding
|
||||
|
||||
**📝 Note:** Padding is applied after all image transformations (except watermarking) and enlarges the generated image. This means that if your resize dimensions were 100x200px and you applied the `padding:10` option, then you will end up with an image with dimensions of 120x220px.
|
||||
|
||||
**📝 Note:** Padding follows the [dpr](#dpr) option so it will also be scaled if you've set it.
|
||||
|
||||
### Auto rotate
|
||||
|
||||
```
|
||||
auto_rotate:%auto_rotate
|
||||
ar:%auto_rotate
|
||||
```
|
||||
|
||||
When set to `1`, `t` or `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. Normally this is controlled by the [IMGPROXY_AUTO_ROTATE](configuration.md#miscellaneous) configuration but this procesing option allows the configuration to be set for each request.
|
||||
|
||||
### Rotate
|
||||
|
||||
```
|
||||
rotate:%angle
|
||||
rot:%angle
|
||||
```
|
||||
|
||||
Rotates the image on the specified angle. The orientation from the image metadata is applied before the rotation unless autorotation is disabled.
|
||||
|
||||
**📝 Note:** Only 0, 90, 180, 270, etc., degree angles are supported.
|
||||
|
||||
Default: 0
|
||||
|
||||
### Background
|
||||
|
||||
```
|
||||
background:%R:%G:%B
|
||||
bg:%R:%G:%B
|
||||
|
||||
background:%hex_color
|
||||
bg:%hex_color
|
||||
```
|
||||
|
||||
When set, imgproxy will fill the resulting image background with the specified color. `R`, `G`, and `B` are the red, green and blue channel values of the background color (0-255). `hex_color` is a hex-coded value of the color. Useful when you convert an image with alpha-channel to JPEG.
|
||||
|
||||
With no arguments provided, disables any background manipulations.
|
||||
|
||||
Default: disabled
|
||||
|
||||
### Background alpha :id=background-alpha
|
||||
|
||||
```
|
||||
background_alpha:%alpha
|
||||
bga:%alpha
|
||||
```
|
||||
|
||||
Adds an alpha channel to `background`. The value of `alpha` is a positive floating point number between `0` and `1`.
|
||||
|
||||
Default: 1
|
||||
|
||||
### Adjust :id=adjust
|
||||
|
||||
```
|
||||
adjust:%brightness:%contrast:%saturation
|
||||
a:%brightness:%contrast:%saturation
|
||||
```
|
||||
|
||||
This is a meta-option that defines the [brightness](#brightness), [contrast](#contrast), and [saturation](#saturation). All arguments are optional and can be omitted to use their default values.
|
||||
|
||||
### Brightness :id=brightness
|
||||
|
||||
```
|
||||
brightness:%brightness
|
||||
br:%brightness
|
||||
```
|
||||
|
||||
When set, imgproxy will adjust brightness of the resulting image. `brightness` is an integer number ranging from `-255` to `255`.
|
||||
|
||||
Default: 0
|
||||
|
||||
### Contrast :id=contrast
|
||||
|
||||
```
|
||||
contrast:%contrast
|
||||
co:%contrast
|
||||
```
|
||||
|
||||
When set, imgproxy will adjust the contrast of the resulting image. `contrast` is a positive floating point number, where a value of `1` leaves the contrast unchanged.
|
||||
|
||||
Default: 1
|
||||
|
||||
### Saturation :id=saturation
|
||||
|
||||
```
|
||||
saturation:%saturation
|
||||
sa:%saturation
|
||||
```
|
||||
|
||||
When set, imgproxy will adjust saturation of the resulting image. `saturation` is a positive floating-point number, where a value of `1` leaves the saturation unchanged.
|
||||
|
||||
Default: 1
|
||||
|
||||
### Blur
|
||||
|
||||
```
|
||||
blur:%sigma
|
||||
bl:%sigma
|
||||
```
|
||||
|
||||
When set, imgproxy will apply a gaussian blur filter to the resulting image. The value of `sigma` defines the size of the mask imgproxy will use.
|
||||
|
||||
Default: disabled
|
||||
|
||||
### Sharpen
|
||||
|
||||
```
|
||||
sharpen:%sigma
|
||||
sh:%sigma
|
||||
```
|
||||
|
||||
When set, imgproxy will apply the sharpen filter to the resulting image. The value of `sigma` defines the size of the mask imgproxy will use.
|
||||
|
||||
As an approximate guideline, use 0.5 sigma for 4 pixels/mm (display resolution), 1.0 for 12 pixels/mm and 1.5 for 16 pixels/mm (300 dpi == 12 pixels/mm).
|
||||
|
||||
Default: disabled
|
||||
|
||||
### Pixelate
|
||||
|
||||
```
|
||||
pixelate:%size
|
||||
pix:%size
|
||||
```
|
||||
|
||||
When set, imgproxy will apply the pixelate filter to the resulting image. The value of `size` defines individual pixel size.
|
||||
|
||||
Default: disabled
|
||||
|
||||
### Unsharp masking :id=unsharp-masking
|
||||
|
||||
```
|
||||
unsharp_masking:%mode:%weight:%divider
|
||||
ush:%mode:%weight:%divider
|
||||
```
|
||||
|
||||
Allows redefining unsharp masking options. All arguments have the same meaning as [Unsharp masking](configuration.md#unsharp-masking) configs. All arguments are optional and can be omitted.
|
||||
|
||||
### Blur detections :id=blur-detections
|
||||
|
||||
```
|
||||
blur_detections:%sigma:%class_name1:%class_name2:...:%class_nameN
|
||||
bd:%sigma:%class_name1:%class_name2:...:%class_nameN
|
||||
```
|
||||
|
||||
imgproxy [detects objects](object_detection.md) of the provided classes and blurs them. If class names are omitted, imgproxy blurs all the detected objects.
|
||||
|
||||
The value of `sigma` defines the size of the mask imgproxy will use.
|
||||
|
||||
### Draw detections :id=draw-detections
|
||||
|
||||
```
|
||||
draw_detections:%draw:%class_name1:%class_name2:...:%class_nameN
|
||||
dd:%draw:%class_name1:%class_name2:...:%class_nameN
|
||||
```
|
||||
|
||||
When `draw` is set to `1`, `t` or `true`, imgproxy [detects objects](object_detection.md) of the provided classes and draws their bounding boxes. If class names are omitted, imgproxy draws the bounding boxes of all the detected objects.
|
||||
|
||||
### Gradient :id=gradient
|
||||
|
||||
```
|
||||
gradient:%opacity:%color:%direction:%start%stop
|
||||
gr:%opacity:%color:%direction:%start%stop
|
||||
```
|
||||
|
||||
Places a gradient on the processed image. The placed gradient transitions from transparency to the specified color.
|
||||
|
||||
* `opacity`: specifies gradient opacity. When set to `0`, gradient is not applied.
|
||||
* `color`: _(optional)_ a hex-coded value of the gradient color. Default: `000` (black).
|
||||
* `direction`: _(optional)_ specifies the direction of the gradient. Available values:
|
||||
* `down`: _(default)_ the top side of the gradient is transparrent, the bottom side is opaque
|
||||
* `up`: the bottom side of the gradient is transparrent, the top side is opaque
|
||||
* `right`: the left side of the gradient is transparrent, the right side is opaque
|
||||
* `left`: the right side of the gradient is transparrent, the left side is opaque
|
||||
* `start`, `stop`: floating point numbers that define relative positions of where the gradient starts and where it ends. Default values are `0.0` and `1.0` respectively.
|
||||
|
||||
### Watermark
|
||||
|
||||
```
|
||||
watermark:%opacity:%position:%x_offset:%y_offset:%scale
|
||||
wm:%opacity:%position:%x_offset:%y_offset:%scale
|
||||
```
|
||||
|
||||
Places a watermark on the processed image.
|
||||
|
||||
* `opacity`: watermark opacity modifier. Final opacity is calculated like `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 resultant image size. When set to `0` or when omitted, the watermark size won't be changed.
|
||||
|
||||
Default: disabled
|
||||
|
||||
### Watermark URL :id=watermark-url
|
||||
|
||||
```
|
||||
watermark_url:%url
|
||||
wmu:%url
|
||||
```
|
||||
|
||||
When set, imgproxy will use the image from the specified URL as a watermark. `url` is the URL-safe Base64-encoded URL of the custom watermark.
|
||||
|
||||
Default: blank
|
||||
|
||||
### Watermark text :id=watermark-text
|
||||
|
||||
```
|
||||
watermark_text:%text
|
||||
wmt:%text
|
||||
```
|
||||
|
||||
When set, imgproxy will generate an image from the provided text and use it as a watermark. `text` is 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.
|
||||
|
||||
Default: blank
|
||||
|
||||
### Watermark size :id=watermark-size
|
||||
|
||||
```
|
||||
watermark_size:%width:%height
|
||||
wms:%width:%height
|
||||
```
|
||||
|
||||
Defines the desired width and height of the watermark. imgproxy always uses `fit` resizing type when resizing watermarks and enlarges them when needed.
|
||||
|
||||
When `%width` is set to `0`, imgproxy will calculate the width using the defined height and watermark's aspect ratio.
|
||||
|
||||
When `%height` is set to `0`, imgproxy will calculate the height using the defined width and watermark's aspect ratio.
|
||||
|
||||
**📝 Note:** This processing option takes effect only when the `scale` argument of the `watermark` option is set to zero.
|
||||
|
||||
Default: `0:0`
|
||||
|
||||
### Watermark shadow :id=watermark-shadow
|
||||
|
||||
```
|
||||
watermark_shadow:%sigma
|
||||
wmsh:%sigma
|
||||
```
|
||||
When set, imgproxy will add a shadow to the watermark. The value of `sigma` defines the size of the mask imgproxy will use to blur the shadow.
|
||||
|
||||
Default: disabled
|
||||
|
||||
### Style :id=style
|
||||
|
||||
```
|
||||
style:%style
|
||||
st:%style
|
||||
```
|
||||
|
||||
When set, imgproxy will prepend a `<style>` node with the provided content to the `<svg>` node of a source SVG image. `%style` is URL-safe Base64-encoded CSS-styles.
|
||||
|
||||
Default: blank
|
||||
|
||||
### Strip metadata
|
||||
|
||||
```
|
||||
strip_metadata:%strip_metadata
|
||||
sm:%strip_metadata
|
||||
```
|
||||
|
||||
When set to `1`, `t` or `true`, imgproxy will strip the metadata (EXIF, IPTC, etc.) on JPEG and WebP output images. This is normally controlled by the [IMGPROXY_STRIP_METADATA](configuration.md#miscellaneous) configuration but this procesing option allows the configuration to be set for each request.
|
||||
|
||||
### Keep copyright
|
||||
|
||||
```
|
||||
keep_copyright:%keep_copyright
|
||||
kcr:%keep_copyright
|
||||
```
|
||||
|
||||
When set to `1`, `t` or `true`, imgproxy will not remove copyright info while stripping metadata. This is normally controlled by the [IMGPROXY_KEEP_COPYRIGHT](configuration.md#miscellaneous) configuration but this procesing option allows the configuration to be set for each request.
|
||||
|
||||
### DPI :id=dpi
|
||||
|
||||
```
|
||||
dpi:%dpi
|
||||
```
|
||||
|
||||
When set, imgproxy will replace the image's DPI metadata with the provided value. When set to `0`, imgproxy won't change the image's DPI or will reset it to the default value if the image's metadata should be stripped.
|
||||
|
||||
**📝 Note:** This processing option takes effect whether imgproxy should strip the image's metadata or not.
|
||||
|
||||
Default: `0`
|
||||
|
||||
### Strip color profile
|
||||
|
||||
```
|
||||
strip_color_profile:%strip_color_profile
|
||||
scp:%strip_color_profile
|
||||
```
|
||||
|
||||
When set to `1`, `t` or `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. This is normally controlled by the [IMGPROXY_STRIP_COLOR_PROFILE](configuration.md#miscellaneous) configuration but this procesing option allows the configuration to be set for each request.
|
||||
|
||||
### Enforce thumbnail
|
||||
|
||||
```
|
||||
enforce_thumbnail:%enforce_thumbnail
|
||||
eth:%enforce_thumbnail
|
||||
```
|
||||
|
||||
When set to `1`, `t` or `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. This is normally controlled by the [IMGPROXY_ENFORCE_THUMBNAIL](configuration.md#miscellaneous) configuration but this procesing option allows the configuration to be set for each request.
|
||||
|
||||
### Quality
|
||||
|
||||
```
|
||||
quality:%quality
|
||||
q:%quality
|
||||
```
|
||||
|
||||
Redefines quality of the resulting image, as a percentage. When set to `0`, quality is assumed based on `IMGPROXY_QUALITY` and [format_quality](#format-quality).
|
||||
|
||||
Default: 0.
|
||||
|
||||
### Format quality
|
||||
|
||||
```
|
||||
format_quality:%format1:%quality1:%format2:%quality2:...:%formatN:%qualityN
|
||||
fq:%format1:%quality1:%format2:%quality2:...:%formatN:%qualityN
|
||||
```
|
||||
|
||||
Adds or redefines `IMGPROXY_FORMAT_QUALITY` values.
|
||||
|
||||
### Autoquality :id=autoquality
|
||||
|
||||
```
|
||||
autoquality:%method:%target:%min_quality:%max_quality:%allowed_error
|
||||
aq:%method:%target:%min_quality:%max_quality:%allowed_error
|
||||
```
|
||||
|
||||
Redefines autoquality settings. All arguments have the same meaning as [Autoquality](configuration.md#autoquality) configs. All arguments are optional and can be omitted.
|
||||
|
||||
**⚠️ Warning:** Autoquality requires the image to be saved several times. Use it only when you prefer the resulting size and quality over the speed.
|
||||
|
||||
### Max bytes
|
||||
|
||||
```
|
||||
max_bytes:%bytes
|
||||
mb:%bytes
|
||||
```
|
||||
|
||||
When set, imgproxy automatically degrades the quality of the image until the image size is under the specified amount of bytes.
|
||||
|
||||
**📝 Note:** Applicable only to `jpg`, `webp`, `heic`, and `tiff`.
|
||||
|
||||
**⚠️ Warning:** When `max_bytes` is set, imgproxy saves image multiple times to achieve the specified image size.
|
||||
|
||||
Default: 0
|
||||
|
||||
### JPEG options :id=jpeg-options
|
||||
|
||||
```
|
||||
jpeg_options:%progressive:%no_subsample:%trellis_quant:%overshoot_deringing:%optimize_scans:%quant_table
|
||||
jpgo:%progressive:%no_subsample:%trellis_quant:%overshoot_deringing:%optimize_scans:%quant_table
|
||||
```
|
||||
|
||||
Allows redefining JPEG saving options. All arguments have the same meaning as the [Advanced JPEG compression](configuration.md#advanced-jpeg-compression) configs. All arguments are optional and can be omitted.
|
||||
|
||||
### PNG options :id=png-options
|
||||
|
||||
```
|
||||
png_options:%interlaced:%quantize:%quantization_colors
|
||||
pngo:%interlaced:%quantize:%quantization_colors
|
||||
```
|
||||
|
||||
Allows redefining PNG saving options. All arguments have the same meaning as with the [Advanced PNG compression](configuration.md#advanced-png-compression) configs. All arguments are optional and can be omitted.
|
||||
|
||||
<!-- ### GIF options :id=gif-options
|
||||
|
||||
```
|
||||
gif_options:%optimize_frames:%optimize_transparency
|
||||
gifo:%optimize_frames:%optimize_transparency
|
||||
```
|
||||
|
||||
Allows redefining GIF saving options. All arguments have the same meaning as with the [Advanced GIF compression](configuration.md#advanced-gif-compression) configs. All arguments are optional and can be omitted. -->
|
||||
|
||||
### WebP options :id=webp-options
|
||||
|
||||
```
|
||||
webp_options:%compression
|
||||
webpo:%compression
|
||||
```
|
||||
|
||||
Allows redefining WebP saving options. All arguments have the same meaning as with the [Advanced WebP compression](configuration.md#advanced-webp-compression) configs. All arguments are optional and can be omitted.
|
||||
|
||||
### Format
|
||||
|
||||
```
|
||||
format:%extension
|
||||
f:%extension
|
||||
ext:%extension
|
||||
```
|
||||
|
||||
Specifies the resulting image format. Alias for the [extension](#extension) part of the URL.
|
||||
|
||||
Default: `jpg`
|
||||
|
||||
### Page :id=page
|
||||
|
||||
```
|
||||
page:%page
|
||||
pg:%page
|
||||
```
|
||||
|
||||
When a source image supports pagination (PDF, TIFF) or animation (GIF, WebP), this option allows specifying the page to use. Page numeration starts from zero.
|
||||
|
||||
**📝 Note:** If both the source and the resulting image formats supoprt animation, imgproxy will ignore this option and use all the source image pages. Use the [disable_animation](#disable-animation) option to make imgproxy treat all images as not animated.
|
||||
|
||||
Default: 0
|
||||
|
||||
### Pages :id=pages
|
||||
|
||||
```
|
||||
pages:%pages
|
||||
pgs:%pages
|
||||
```
|
||||
|
||||
When a source image supports pagination (PDF, TIFF) or animation (GIF, WebP), this option allows specifying the number of pages to use. The pages will be stacked vertically and left-aligned.
|
||||
|
||||
**📝 Note:** If both the source and the resulting image formats supoprt animation, imgproxy will ignore this option and use all the source image pages. Use the [disable_animation](#disable-animation) option to make imgproxy treat all images as not animated.
|
||||
|
||||
Default: 1
|
||||
|
||||
### Disable animation :id=disable-animation
|
||||
|
||||
```
|
||||
disable_animation:%disable
|
||||
da:%disable
|
||||
```
|
||||
|
||||
When set to `1`, `t` or `true`, imgproxy will treat all images as not animated. Use the [page](#page) and the [pages](#pages) options to specify which frames imgproxy should use.
|
||||
|
||||
Default: `false`
|
||||
|
||||
### Video thumbnail second :id=video-thumbnail-second
|
||||
|
||||
```
|
||||
video_thumbnail_second:%second
|
||||
vts:%second
|
||||
```
|
||||
|
||||
Allows redefining `IMGPROXY_VIDEO_THUMBNAIL_SECOND` config.
|
||||
|
||||
### Video thumbnail keyframes :id=video-thumbnail-keyframes
|
||||
|
||||
```
|
||||
video_thumbnail_keyframes:%keyframes
|
||||
vts:%keyframes
|
||||
```
|
||||
|
||||
Allows redefining `IMGPROXY_VIDEO_THUMBNAIL_KEYFRAMES` config.
|
||||
|
||||
### Video thumbnail tile :id=video-thumbnail-tile
|
||||
|
||||
```
|
||||
video_thumbnail_tile:%step:%columns:%rows:%tile_width:%tile_height:%extend_tile:%trim
|
||||
vtt:%step:%columns:%rows:%tile_width:%tile_height:%extend_tile:%trim
|
||||
```
|
||||
|
||||
When `step` is larger than `0`, imgproxy will generate a tiled sprite using the source video frames.
|
||||
|
||||
* `step`: the step of timestamp (in seconds) between video frames that should be used for the sprite generation
|
||||
* `columns`: the number of columns in the sprite
|
||||
* `rows`: the number of rows in the sprite
|
||||
* `tile_width`, `tile_height`: the width and height of each tile in the sprite. imgproxy will resize each used frame to fit the provided size
|
||||
* `extend_tile`: _(optional)_ when set to `1`, `t` or `true`, imgproxy will extend each tile to the requested size using a black background
|
||||
* `trim`: _(optional)_ when set to `1`, `t` or `true`, imgproxy will trim the unused space from the sprite
|
||||
|
||||
The timestamp of the first frame can be set using the `IMGPROXY_VIDEO_THUMBNAIL_SECOND` config or the [video_thumbnail_second](#video-thumbnail-keyframes) option.
|
||||
|
||||
You can make imgproxy use only keyframes with the `IMGPROXY_VIDEO_THUMBNAIL_KEYFRAMES` config or the [video_thumbnail_keyframes](#video-thumbnail-keyframes) option.
|
||||
|
||||
Default: `0:0:0:0:0`
|
||||
|
||||
### Fallback image URL :id=fallback-image-url
|
||||
|
||||
You can use a custom fallback image by specifying its URL with the `fallback_image_url` processing option:
|
||||
|
||||
```
|
||||
fallback_image_url:%url
|
||||
fiu:%url
|
||||
```
|
||||
|
||||
The value of `url` is the URL-safe Base64-encoded URL of the custom fallback image.
|
||||
|
||||
Default: blank
|
||||
|
||||
### Skip processing
|
||||
|
||||
```
|
||||
skip_processing:%extension1:%extension2:...:%extensionN
|
||||
skp:%extension1:%extension2:...:%extensionN
|
||||
```
|
||||
|
||||
When set, imgproxy will skip the processing of the listed formats. Also available as the [IMGPROXY_SKIP_PROCESSING_FORMATS](configuration.md#skip-processing) configuration.
|
||||
|
||||
**📝 Note:** Processing can only be skipped when the requested format is the same as the source format.
|
||||
|
||||
**📝 Note:** Video thumbnail processing can't be skipped.
|
||||
|
||||
Default: empty
|
||||
|
||||
### Raw
|
||||
|
||||
```
|
||||
raw:%raw
|
||||
```
|
||||
|
||||
When set to `1`, `t` or `true`, imgproxy will respond with a raw unprocessed, and unchecked source image. There are some differences between `raw` and `skip_processing` options:
|
||||
|
||||
* While the `skip_processing` option has some conditions to skip the processing, the `raw` option allows to skip processing no matter what
|
||||
* With the `raw` option set, imgproxy doesn't check the source image's type, resolution, and file size. Basically, the `raw` option allows streaming of any file type
|
||||
* With the `raw` option set, imgproxy won't download the whole image to the memory. Instead, it will stream the source image directly to the response lowering memory usage
|
||||
* The requests with the `raw` option set are not limited by the `IMGPROXY_WORKERS` config
|
||||
|
||||
Default: `false`
|
||||
|
||||
### Cache buster
|
||||
|
||||
```
|
||||
cachebuster:%string
|
||||
cb:%string
|
||||
```
|
||||
|
||||
Cache buster doesn't affect image processing but its changing allows for bypassing the CDN, proxy server and browser cache. Useful when you have changed some things that are not reflected in the URL, like image quality settings, presets, or watermark data.
|
||||
|
||||
It's highly recommended to prefer the `cachebuster` option over a URL query string because that option can be properly signed.
|
||||
|
||||
Default: empty
|
||||
|
||||
### Expires
|
||||
|
||||
```
|
||||
expires:%timestamp
|
||||
exp:%timestamp
|
||||
```
|
||||
|
||||
When set, imgproxy will check the provided unix timestamp and return 404 when expired.
|
||||
|
||||
Default: empty
|
||||
|
||||
### Filename
|
||||
|
||||
```
|
||||
filename:%filename:%encoded
|
||||
fn:%filename:%encoded
|
||||
```
|
||||
|
||||
Defines a filename for the `Content-Disposition` header. When not specified, imgproxy will get the filename from the source URL.
|
||||
|
||||
* `filename`: escaped or URL-safe Base64-encoded filename to be used in the `Content-Disposition` header
|
||||
* `encoded`: _(optionsl)_ identifies if `filename` is Base64-encoded. Set it to `1`, `t`, or `true` if you encoded the `filename` value with URL-safe Base64 encoding.
|
||||
|
||||
Default: empty
|
||||
|
||||
### Return attachment
|
||||
|
||||
```
|
||||
return_attachment:%return_attachment
|
||||
att:%return_attachment
|
||||
```
|
||||
|
||||
When set to `1`, `t` or `true`, imgproxy will return `attachment` in the `Content-Disposition` header, and the browser will open a 'Save as' dialog. This is normally controlled by the [IMGPROXY_RETURN_ATTACHMENT](configuration.md#miscellaneous) configuration but this procesing option allows the configuration to be set for each request.
|
||||
|
||||
### Preset
|
||||
|
||||
```
|
||||
preset:%preset_name1:%preset_name2:...:%preset_nameN
|
||||
pr:%preset_name1:%preset_name2:...:%preset_nameN
|
||||
```
|
||||
|
||||
Defines a list of presets to be used by imgproxy. Feel free to use as many presets in a single URL as you need.
|
||||
|
||||
Read more about presets in the [Presets](presets.md) guide.
|
||||
|
||||
Default: empty
|
||||
|
||||
### Max src resolution
|
||||
|
||||
```
|
||||
max_src_resolution:%resolution
|
||||
msr:%resolution
|
||||
```
|
||||
|
||||
Allows redefining `IMGPROXY_MAX_SRC_RESOLUTION` config.
|
||||
|
||||
**⚠️ Warning:** Since this option allows redefining a security restriction, its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to `true`.
|
||||
|
||||
### Max src file size
|
||||
|
||||
```
|
||||
max_src_file_size:%size
|
||||
msfs:%size
|
||||
```
|
||||
|
||||
Allows redefining `IMGPROXY_MAX_SRC_FILE_SIZE` config.
|
||||
|
||||
**⚠️ Warning:** Since this option allows redefining a security restriction, its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to `true`.
|
||||
|
||||
### Max animation frames
|
||||
|
||||
```
|
||||
max_animation_frames:%size
|
||||
maf:%size
|
||||
```
|
||||
|
||||
Allows redefining `IMGPROXY_MAX_ANIMATION_FRAMES` config.
|
||||
|
||||
**⚠️ Warning:** Since this option allows redefining a security restriction, its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to `true`.
|
||||
|
||||
### Max animation frame resolution
|
||||
|
||||
```
|
||||
max_animation_frame_resolution:%size
|
||||
mafr:%size
|
||||
```
|
||||
|
||||
Allows redefining `IMGPROXY_MAX_ANIMATION_FRAME_RESOLUTION` config.
|
||||
|
||||
**⚠️ Warning:** Since this option allows redefining a security restriction, its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to `true`.
|
||||
|
||||
## Source URL
|
||||
### Plain
|
||||
|
||||
The source URL can be provided as is, prepended by the `/plain/` segment:
|
||||
|
||||
```
|
||||
/plain/http://example.com/images/curiosity.jpg
|
||||
```
|
||||
|
||||
**📝 Note:** If the source URL contains a query string or `@`, you'll need to escape it.
|
||||
|
||||
When using a plain source URL, you can specify the [extension](#extension) after `@`:
|
||||
|
||||
```
|
||||
/plain/http://example.com/images/curiosity.jpg@png
|
||||
```
|
||||
|
||||
### Base64 encoded
|
||||
|
||||
The source URL can be encoded with URL-safe Base64. The encoded URL can be split with `/` as desired:
|
||||
|
||||
```
|
||||
/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn
|
||||
```
|
||||
|
||||
When using an encoded source URL, you can specify the [extension](#extension) after `.`:
|
||||
|
||||
```
|
||||
/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png
|
||||
```
|
||||
|
||||
### Encrypted with AES-CBC :id=encrypted-with-aes-cbc
|
||||
|
||||
The source URL can be encrypted with the AES-CBC algorithm, prepended by the `/enc/` segment. The encrypted URL can be split with `/` as desired:
|
||||
|
||||
```
|
||||
/enc/jwV3wUD9r4VBIzgv/ang3Hbh0vPpcm5cc/VO5rHxzonpvZjppG/2VhDnX2aariBYegH/jlhw_-dqjXDMm4af/ZDU6y5sBog
|
||||
```
|
||||
|
||||
When using an encrypted source URL, you can specify the [extension](#extension) after `.`:
|
||||
|
||||
```
|
||||
/enc/jwV3wUD9r4VBIzgv/ang3Hbh0vPpcm5cc/VO5rHxzonpvZjppG/2VhDnX2aariBYegH/jlhw_-dqjXDMm4af/ZDU6y5sBog.png
|
||||
```
|
||||
|
||||
## Extension
|
||||
|
||||
Extension specifies the format of the resulting image. Read more about image formats support [here](image_formats_support.md).
|
||||
|
||||
The extension can be omitted. In this case, imgproxy will use the source image format as resulting one. If the source image format is not supported as the resulting image, imgproxy will use `jpg`. You also can [enable WebP support detection](configuration.md#avifwebp-support-detection) to use it as the default resulting format when possible.
|
||||
|
||||
### Best format
|
||||
|
||||
You can use the `best` value for the [format](generating_the_url.md#format) option or the [extension](generating_the_url.md#extension) to make imgproxy pick the best format for the resultant image. Check out the [Best format](best_format.md) guide to learn more.
|
||||
|
||||
## Example
|
||||
|
||||
A signed imgproxy URL that uses the `sharp` preset, resizes `http://example.com/images/curiosity.jpg` to fill a `300x400` area using smart gravity without enlarging, and then converts the image to `png`:
|
||||
|
||||
```
|
||||
http://imgproxy.example.com/AfrOrF3gWeDA6VOlDG4TzxMv39O7MXnF4CXpKUwGqRM/preset:sharp/resize:fill:300:400:0/gravity:sm/plain/http://example.com/images/curiosity.jpg@png
|
||||
```
|
||||
|
||||
The same URL with shortcuts will look like this:
|
||||
|
||||
```
|
||||
http://imgproxy.example.com/AfrOrF3gWeDA6VOlDG4TzxMv39O7MXnF4CXpKUwGqRM/pr:sharp/rs:fill:300:400:0/g:sm/plain/http://example.com/images/curiosity.jpg@png
|
||||
```
|
||||
|
||||
The same URL with a Base64-encoded source URL will look like this:
|
||||
|
||||
```
|
||||
http://imgproxy.example.com/AfrOrF3gWeDA6VOlDG4TzxMv39O7MXnF4CXpKUwGqRM/pr:sharp/rs:fill:300:400:0/g:sm/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png
|
||||
```
|
||||
@ -1,515 +0,0 @@
|
||||
# Getting the image info
|
||||
|
||||
imgproxy can fetch and return a source image info without downloading the whole image.
|
||||
|
||||
## URL format
|
||||
|
||||
To get the image info, use the following URL format:
|
||||
|
||||
```
|
||||
/info/%signature/%info_options/plain/%source_url
|
||||
/info/%signature/%info_options/%encoded_source_url
|
||||
```
|
||||
|
||||
## Signature
|
||||
|
||||
**⚠️ Warning:** The signature part should always be present in a URL. If the signature check is disabled (no key/salt pairs are provided), the signature part may contain anything (for example, `unsafe` or `_`).
|
||||
|
||||
A signature protects your URL from being modified by an attacker. It is highly recommended to sign imgproxy URLs in a production environment.
|
||||
|
||||
Once you set up your [URL signature](configuration.md#url-signature), check out the [Signing the URL](signing_the_url.md) guide to learn about how to sign your URLs. Otherwise, since the signature is required, feel free to use any string here.
|
||||
|
||||
## Info options
|
||||
|
||||
Info options should be specified as URL parts divided by slashes (`/`). An info option has the following format:
|
||||
|
||||
```
|
||||
%option_name:%argument1:%argument2:...:argumentN
|
||||
```
|
||||
|
||||
### Size
|
||||
|
||||
```
|
||||
size:%size
|
||||
s:%size
|
||||
```
|
||||
|
||||
When set to `1`, `t`, or `true`, imgproxy will return the size of the image file. If the source URL is an HTTP(s) URL, imgproxy will determine the file size based on the `Content-Length` HTTP header.
|
||||
|
||||
Default: `true`.
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"size": 123456
|
||||
}
|
||||
```
|
||||
|
||||
### Format
|
||||
|
||||
```
|
||||
format:%format
|
||||
f:%format
|
||||
```
|
||||
|
||||
When set to `1`, `t`, or `true`, imgproxy will return the image format.
|
||||
|
||||
**📝 Note:** For video files, imgproxy returns a list of predicted formats divided by comma.
|
||||
|
||||
Default: `true`.
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"format": "jpeg"
|
||||
}
|
||||
```
|
||||
|
||||
### Dimensions
|
||||
|
||||
```
|
||||
dimensions:%dimensions
|
||||
d:%dimensions
|
||||
```
|
||||
|
||||
When set to `1`, `t`, or `true`, imgproxy will return the image dimensions.
|
||||
|
||||
Default: `true`.
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"width": 7360,
|
||||
"height": 4912
|
||||
}
|
||||
```
|
||||
|
||||
### EXIF
|
||||
|
||||
```
|
||||
exif:%exif
|
||||
```
|
||||
|
||||
When set to `1`, `t`, or `true`, imgproxy will return the image's EXIF metadata.
|
||||
|
||||
Default: `true`.
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"exif": {
|
||||
"Aperture": "8.00 EV (f/16.0)",
|
||||
"Contrast": "Normal",
|
||||
"Date and Time": "2016:09:11 22:15:03",
|
||||
"Model": "NIKON D810",
|
||||
"Software": "Adobe Photoshop Lightroom 6.1 (Windows)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### IPTC
|
||||
|
||||
```
|
||||
iptc:%iptc
|
||||
```
|
||||
|
||||
When set to `1`, `t`, or `true`, imgproxy will return the image's IPTC (IPTC-IIM) metadata and Photoshop metadata (currently, only the resolution data).
|
||||
|
||||
Default: `true`.
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"iptc": {
|
||||
"Name": "Spider-Man",
|
||||
"Caption": "Spider-Man swings on the web",
|
||||
"Copyright Notice": "Daily Bugle",
|
||||
"Keywords": ["spider-man", "menance", "offender"]
|
||||
},
|
||||
"photoshop": {
|
||||
"resolution": {
|
||||
"XResolution": 240,
|
||||
"XResolutionUnit": "inches",
|
||||
"WidthUnit": "inches",
|
||||
"YResolution": 240,
|
||||
"YResolutionUnit": "inches",
|
||||
"HeightUnit": "inches"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### XMP
|
||||
|
||||
```
|
||||
xmp:%xmp
|
||||
```
|
||||
|
||||
When set to `1`, `t`, or `true`, imgproxy will return the image's XMP metadata.
|
||||
|
||||
Default: `true`.
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"xmp": {
|
||||
"aux": {
|
||||
"ApproximateFocusDistance": "4294967295/1",
|
||||
"ImageNumber": "16604",
|
||||
"Lens": "16.0-35.0 mm f/4.0",
|
||||
"LensID": "163",
|
||||
"LensInfo": "160/10 350/10 40/10 40/10",
|
||||
"SerialNumber": "12345678"
|
||||
},
|
||||
"dc": {
|
||||
"creator": ["Peter B. Parker"],
|
||||
"publisher": ["Daily Bugle"],
|
||||
"subject": ["spider-man", "menance", "offender"],
|
||||
"format": "image/jpeg"
|
||||
},
|
||||
"photoshop": {
|
||||
"DateCreated": "2016-09-11T18:44:50.003"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Video meta
|
||||
|
||||
```
|
||||
video_meta:%video_meta
|
||||
vm:%video_meta
|
||||
```
|
||||
|
||||
When set to `1`, `t`, or `true`, imgproxy will return the video metadata and video streams info.
|
||||
|
||||
Default: `true`.
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"video_meta": {
|
||||
"com.android.version": "9",
|
||||
"compatible_brands": "isommp42",
|
||||
"creation_time": "2022-01-12T15:04:10.000000Z",
|
||||
"location": "+46.4845+030.6848/",
|
||||
"location-eng": "+46.4845+030.6848/",
|
||||
"major_brand": "mp42",
|
||||
"minor_version": "0"
|
||||
},
|
||||
"video_streams": [
|
||||
{
|
||||
"type": "video",
|
||||
"codec": "h264",
|
||||
"bps": 16910024,
|
||||
"fps": 24,
|
||||
"language": "eng"
|
||||
},
|
||||
{
|
||||
"type": "audio",
|
||||
"codec": "eac3",
|
||||
"bps": 768000,
|
||||
"frequency": 48000,
|
||||
"layout": "5.1(side)",
|
||||
"language": "eng"
|
||||
},
|
||||
{
|
||||
"type": "subtitle",
|
||||
"codec": "subrip",
|
||||
"language": "eng"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Detect objects
|
||||
|
||||
**⏳ Slow:** This option requires the image to be fully downloaded and processed.
|
||||
|
||||
```
|
||||
detect_objects:%detect_objects
|
||||
do:%detect_objects
|
||||
```
|
||||
|
||||
When set to `1`, `t`, or `true`, imgproxy will return the info about the objects found in the image. Read the [object detection](object_detection.md) manual to learn how to configure object detection.
|
||||
|
||||
**📝 Note:** imgproxy returns the relative coordinates of the found objects.
|
||||
|
||||
Default: `false`.
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"objects": [
|
||||
{
|
||||
"class_id": 0,
|
||||
"class_name": "face",
|
||||
"confidence": 0.985792,
|
||||
"left": 0.6602726057171822,
|
||||
"top": 0.23434072732925415,
|
||||
"width": 0.11385439336299896,
|
||||
"height": 0.18671900033950806
|
||||
},
|
||||
{
|
||||
"class_id": 0,
|
||||
"class_name": "face",
|
||||
"confidence": 0.9810329,
|
||||
"left": 0.4354642778635025,
|
||||
"top": 0.3503067269921303,
|
||||
"width": 0.10691609978675842,
|
||||
"height": 0.18357203900814056
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Crop coordinates :id=crop
|
||||
|
||||
**⏳ Slow:** This option requires the image to be fully downloaded and processed.
|
||||
|
||||
```
|
||||
crop:%width:%height:%gravity
|
||||
c:%width:%height:%gravity
|
||||
```
|
||||
|
||||
When `width` and `height` are greater than zero, imgproxy will return the _relative_ crop coordinates for the defined crop parameters.
|
||||
|
||||
This option takes the same arguments as the [crop](generating_the_url.md#crop) processiong option.
|
||||
|
||||
Default: `0:0:ce`.
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"crop": {
|
||||
"left": 0.383203125,
|
||||
"top": 0.2603861907548274,
|
||||
"width": 0.1953125,
|
||||
"height": 0.3510825043885313
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Palette
|
||||
|
||||
**⏳ Slow:** This option requires the image to be fully downloaded and processed.
|
||||
|
||||
```
|
||||
palette:%colors
|
||||
p:%colors
|
||||
```
|
||||
|
||||
When `colors` is greater than zero, imgproxy will build and return the image's RGBA palette containing maximum `colors` colors.
|
||||
|
||||
**📝 Note:** When `colors` is greater than zero, its value should be between `2` and `256`.
|
||||
|
||||
Default: `0`.
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"palette": [
|
||||
{ "R": 189, "G": 178, "B": 169, "A": 255 },
|
||||
{ "R": 83, "G": 79, "B": 67, "A": 255 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Average color :id=average
|
||||
|
||||
**⏳ Slow:** This option requires the image to be fully downloaded and processed.
|
||||
|
||||
```
|
||||
average:%average:%ignore_transparent
|
||||
avg:%average:%ignore_transparent
|
||||
```
|
||||
|
||||
* `average` – when set to `1`, `t`, or `true`, imgproxy will calculate and return the image's average color. Default: `false`
|
||||
* `ignore_transparent` – _(optional)_ when set to `1`, `t`, or `true`, imgproxy will ignore fully transparent pixels. Default: `true`
|
||||
|
||||
Default: `false:true`
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"average": { "R": 139, "G": 132, "B": 121, "A": 255 }
|
||||
}
|
||||
```
|
||||
|
||||
### Dominant colors
|
||||
|
||||
**⏳ Slow:** This option requires the image to be fully downloaded and processed.
|
||||
|
||||
```
|
||||
dominant_colors:%dominant_colors:%build_missed
|
||||
dc:%dominant_colors:%build_missed
|
||||
```
|
||||
|
||||
* `dominant_colors` – when set to `1`, `t`, or `true`, imgproxy will calculate and return the image's dominant colors (vibrant, light vibrant, dark vibrant, muted, light muted, and dark muted). Default: `false`
|
||||
* `build_missed` – _(optional)_ when set to `1`, `t`, or `true`, imgproxy will build colors that were not found in the image based on the found ones. Default: `false`
|
||||
|
||||
Default: `false:false`
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"dominant_colors": {
|
||||
"dark_muted": { "R": 75, "G": 70, "B": 57 },
|
||||
"dark_vibrant": { "R": 90, "G": 78, "B": 43 },
|
||||
"light_muted": { "R": 167, "G": 156, "B": 130 },
|
||||
"light_vibrant": { "R": 212, "G": 198, "B": 165 },
|
||||
"muted": { "R": 155, "G": 146, "B": 120 },
|
||||
"vibrant": { "R": 172, "G": 146, "B": 83 }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### BlurHash
|
||||
|
||||
**⏳ Slow:** This option requires the image to be fully downloaded and processed.
|
||||
|
||||
```
|
||||
blurhash:%x_components:%y_components
|
||||
bh:%x_components:%y_components
|
||||
```
|
||||
|
||||
When `x_components` and `y_components` are greater than zero, imgproxy will calculate and return the image's [BlurHash](https://blurha.sh/). `x_components` and `y_components` is the numbers of horizontal and vertical components of BlurHash. The larger the numbers the more "detailed" will be the BlurHash.
|
||||
|
||||
The maximum value for `x_components` and `y_components` is `9`.
|
||||
|
||||
Default: `0:0`
|
||||
|
||||
**Response example:**
|
||||
|
||||
```json
|
||||
{
|
||||
"blurhash": "LLH-}fox0fRQ%Do}9as9_3%2M{S2"
|
||||
}
|
||||
```
|
||||
|
||||
### Page
|
||||
|
||||
```
|
||||
page:%page
|
||||
pg:%page
|
||||
```
|
||||
|
||||
When a source image supports pagination (PDF, TIFF) or animation (GIF, WebP), this option allows specifying the page to use. Page numeration starts from zero.
|
||||
|
||||
Default: 0
|
||||
|
||||
### Video thumbnail second
|
||||
|
||||
```
|
||||
video_thumbnail_second:%second
|
||||
vts:%second
|
||||
```
|
||||
|
||||
Allows redefining `IMGPROXY_VIDEO_THUMBNAIL_SECOND` config.
|
||||
|
||||
### Video thumbnail keyframes :id=video-thumbnail-keyframes
|
||||
|
||||
```
|
||||
video_thumbnail_keyframes:%keyframes
|
||||
vts:%keyframes
|
||||
```
|
||||
|
||||
Allows redefining `IMGPROXY_VIDEO_THUMBNAIL_KEYFRAMES` config.
|
||||
|
||||
### Cache buster
|
||||
|
||||
```
|
||||
cachebuster:%string
|
||||
cb:%string
|
||||
```
|
||||
|
||||
Cache buster doesn't affect image processing but its changing allows for bypassing the CDN, proxy server and browser cache. Useful when you have changed some things that are not reflected in the URL, like image quality settings, presets, or watermark data.
|
||||
|
||||
It's highly recommended to prefer the `cachebuster` option over a URL query string because that option can be properly signed.
|
||||
|
||||
Default: empty
|
||||
|
||||
### Expires
|
||||
|
||||
```
|
||||
expires:%timestamp
|
||||
exp:%timestamp
|
||||
```
|
||||
|
||||
When set, imgproxy will check the provided unix timestamp and return 404 when expired.
|
||||
|
||||
Default: empty
|
||||
|
||||
### Preset
|
||||
|
||||
```
|
||||
preset:%preset_name1:%preset_name2:...:%preset_nameN
|
||||
pr:%preset_name1:%preset_name2:...:%preset_nameN
|
||||
```
|
||||
|
||||
Defines a list of presets to be used by imgproxy. Feel free to use as many presets in a single URL as you need.
|
||||
|
||||
Read more about presets in the [Presets](presets.md) guide.
|
||||
|
||||
Default: empty
|
||||
|
||||
### Max src resolution
|
||||
|
||||
```
|
||||
max_src_resolution:%resolution
|
||||
msr:%resolution
|
||||
```
|
||||
|
||||
Allows redefining `IMGPROXY_MAX_SRC_RESOLUTION` config.
|
||||
|
||||
**⚠️ Warning:** Since this option allows redefining a security restriction, its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to `true`.
|
||||
|
||||
### Max src file size
|
||||
|
||||
```
|
||||
max_src_file_size:%size
|
||||
msfs:%size
|
||||
```
|
||||
|
||||
Allows redefining `IMGPROXY_MAX_SRC_FILE_SIZE` config.
|
||||
|
||||
**⚠️ Warning:** Since this option allows redefining a security restriction, its usage is not allowed unless the `IMGPROXY_ALLOW_SECURITY_OPTIONS` config is set to `true`.
|
||||
|
||||
## Source URL
|
||||
### Plain
|
||||
|
||||
The source URL can be provided as is, prepended by `/plain/` part:
|
||||
|
||||
```
|
||||
/plain/http://example.com/images/curiosity.jpg
|
||||
```
|
||||
|
||||
**📝 Note:** If the source URL contains a query string or `@`, you'll need to escape it.
|
||||
|
||||
### Base64 encoded
|
||||
|
||||
The source URL can be encoded with URL-safe Base64. The encoded URL can be split with `/` as desired:
|
||||
|
||||
```
|
||||
/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn
|
||||
```
|
||||
|
||||
### Encrypted with AES-CBC :id=encrypted-with-aes-cbc
|
||||
|
||||
The source URL can be encrypted with the AES-CBC algorithm, prepended by the `/enc/` segment. The encrypted URL can be split with `/` as desired:
|
||||
|
||||
```
|
||||
/enc/jwV3wUD9r4VBIzgv/ang3Hbh0vPpcm5cc/VO5rHxzonpvZjppG/2VhDnX2aariBYegH/jlhw_-dqjXDMm4af/ZDU6y5sBog
|
||||
```
|
||||
@ -1,19 +0,0 @@
|
||||
# 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` and `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
|
||||
```
|
||||
@ -1,52 +0,0 @@
|
||||
# Image formats support
|
||||
|
||||
At the moment, imgproxy supports only the most popular image formats:
|
||||
|
||||
| Format | Extension | Source | Result |
|
||||
| -------|-----------|--------|--------|
|
||||
| PNG | `png` | Yes | Yes |
|
||||
| JPEG | `jpg` | Yes | Yes |
|
||||
| WebP | `webp` | Yes | Yes |
|
||||
| AVIF | `avif` | Yes | Yes |
|
||||
| GIF | `gif` | Yes | Yes |
|
||||
| ICO | `ico` | Yes | Yes |
|
||||
| SVG | `svg` | Yes | [See notes](#svg-support) |
|
||||
| HEIC | `heic` | Yes | No |
|
||||
| BMP | `bmp` | Yes | Yes |
|
||||
| TIFF | `tiff` | Yes | Yes |
|
||||
| PDF  | `pdf` | Yes | No |
|
||||
| MP4 (h264)  | `mp4` | [See notes](#video-thumbnails) | Yes |
|
||||
| Other video formats  | | [See notes](#video-thumbnails) | No |
|
||||
|
||||
## 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.
|
||||
|
||||
imgproxy reads some amount of bytes to check if the source image is SVG. By default it reads a maximum of 32KB, but you can change this:
|
||||
|
||||
* `IMGPROXY_MAX_SVG_CHECK_BYTES`: the maximum number of bytes imgproxy will read to recognize SVG. If imgproxy can't recognize your SVG, try to increase this number. Default: `32768` (32KB)
|
||||
|
||||
## Animated images support
|
||||
|
||||
Since the processing of animated images is a pretty heavy process, only one frame is processed by default. You can increase the maximum of animation frames to process with the following variable:
|
||||
|
||||
* `IMGPROXY_MAX_ANIMATION_FRAMES`: the maximum of animated image frames to be processed. Default: `1`.
|
||||
|
||||
**📝 Note:** imgproxy summarizes all frames resolutions while the checking source image resolution.
|
||||
|
||||
## Converting animated images to MP4 :id=converting-animated-images-to-mp4
|
||||
|
||||
Animated image results can be converted to MP4 by specifying the `mp4` extension.
|
||||
|
||||
Since MP4 requires use of a `<video>` tag instead of `<img>`, automatic conversion to MP4 is not provided.
|
||||
|
||||
## Video thumbnails :id=video-thumbnails
|
||||
|
||||
If you provide a video as a source, imgproxy takes a specific frame to create a thumbnail. To do this, imgproxy downloads only the amount of data required to reach the needed frame.
|
||||
|
||||
Since this still requires more data to be downloaded, video thumbnail generation is disabled by default and should be enabled with `IMGPROXY_ENABLE_VIDEO_THUMBNAILS` config option.
|
||||
|
||||
* `IMGPROXY_ENABLE_VIDEO_THUMBNAILS`: when true, enables video thumbnail generation. Default: `false`
|
||||
* `IMGPROXY_VIDEO_THUMBNAIL_SECOND`: the timestamp of the frame (in seconds) that will be used for the thumbnail. Default: 1.
|
||||
@ -1,65 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- Google Tag Manager -->
|
||||
<script async
|
||||
src="https://www.googletagmanager.com/gtag/js?id=G-4ME3KE3EJC"></script>
|
||||
<script>
|
||||
window.dataLayer = window.dataLayer || [];
|
||||
function gtag() { dataLayer.push(arguments); }
|
||||
gtag('js', new Date());
|
||||
|
||||
gtag('config', 'G-4ME3KE3EJC');
|
||||
</script>
|
||||
<!-- End Google Tag Manager -->
|
||||
<meta charset="UTF-8">
|
||||
<title>imgproxy documentation</title>
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
|
||||
<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
|
||||
<meta name="description" content="Fast and secure standalone server for resizing and converting remote images" />
|
||||
<meta itemprop="name" content="imgproxy documentation" />
|
||||
<meta itemprop="description" content="Fast and secure standalone server for resizing and converting remote images" />
|
||||
<meta property="og:title" content="imgproxy documentation" />
|
||||
<meta property="og:description" content="Fast and secure standalone server for resizing and converting remote images" />
|
||||
<meta property="og:site_name" content="imgproxy documentation" />
|
||||
<meta name="keywords" content="image, resize-images, crop-image, microservice, docker, jpeg, png, libvips" />
|
||||
<meta name="theme-color" content="#000000" />
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link rel="icon" type="image/png" href="/assets/favicon-196x196.png" sizes="196x196">
|
||||
<link rel="icon" type="image/png" href="/assets/favicon-128x128.png" sizes="128x128">
|
||||
<link rel="icon" type="image/png" href="/assets/favicon-96x96.png" sizes="96x96">
|
||||
<link rel="icon" type="image/png" href="/assets/favicon-32x32.png" sizes="32x32">
|
||||
<link rel="icon" type="image/png" href="/assets/favicon-16x16.png" sizes="16x16">
|
||||
<link rel="stylesheet" href="/assets/theme.css">
|
||||
<link rel="stylesheet" href="/assets/style.css">
|
||||
</head>
|
||||
<body>
|
||||
<div id="app">
|
||||
<div class="loading">
|
||||
<div class="loading__spinner"></div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<script type="application/javascript">
|
||||
window.DOCSIFY_DEFER = true;
|
||||
window.$docsify = { plugins: [] };
|
||||
</script>
|
||||
|
||||
<!-- <script src="//unpkg.com/docsify/lib/docsify.min.js"></script> -->
|
||||
<script src="/assets/docsify.min.20230513.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/docsify-themeable@0"></script>
|
||||
<!-- <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script> -->
|
||||
<script src="/assets/docsify.search.min.20230513.js"></script>
|
||||
<script src="//unpkg.com/docsify-namespaced@0.1.1/dist/docsify-namespaced.min.js"></script>
|
||||
<script src="//unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
|
||||
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
|
||||
|
||||
<script src="/assets/docsify-init.js"></script>
|
||||
|
||||
<link
|
||||
href="https://fonts.googleapis.com/css2?family=Martian+Mono:wght@300&family=Roboto+Condensed:wght@700&family=Roboto:wght@400;700&display=swap"
|
||||
rel="stylesheet">
|
||||
</body>
|
||||
</html>
|
||||
@ -1,129 +0,0 @@
|
||||
# Installation
|
||||
|
||||
There are four ways you can install imgproxy:
|
||||
|
||||
## Docker
|
||||
|
||||
imgproxy can (and this is highly recommended) be used as a standalone application inside a Docker container. Just pull the official image from Docker Hub:
|
||||
|
||||
```bash
|
||||
docker pull darthsim/imgproxy:latest
|
||||
docker run -p 8080:8080 -it darthsim/imgproxy
|
||||
```
|
||||
|
||||
You can also build your own image. imgproxy is ready to be dockerized out of the box:
|
||||
|
||||
```bash
|
||||
docker build -f docker/Dockerfile -t imgproxy .
|
||||
docker run -p 8080:8080 -it imgproxy
|
||||
```
|
||||
|
||||
## Helm
|
||||
|
||||
imgproxy can be easily deployed to your Kubernetes cluster using Helm and our official Helm chart:
|
||||
|
||||
```bash
|
||||
helm repo add imgproxy https://helm.imgproxy.net/
|
||||
|
||||
# With Helm 3
|
||||
helm upgrade -i imgproxy imgproxy/imgproxy
|
||||
|
||||
# With Helm 2
|
||||
helm upgrade -i --name imgproxy imgproxy/imgproxy
|
||||
```
|
||||
|
||||
Check out the [chart's README](https://github.com/imgproxy/imgproxy-helm) for more info.
|
||||
|
||||
## Heroku
|
||||
|
||||
imgproxy can be deployed to Heroku with the click of a button:
|
||||
|
||||
[](https://heroku.com/deploy?template=https://github.com/imgproxy/imgproxy)
|
||||
|
||||
That being said, you can also do it manually in just a few steps:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/imgproxy/imgproxy.git && cd imgproxy
|
||||
heroku create your-application
|
||||
heroku stack:set container
|
||||
git push heroku master
|
||||
```
|
||||
|
||||
## Packages
|
||||
|
||||
### Arch Linux and derivatives
|
||||
|
||||
[imgproxy](https://aur.archlinux.org/packages/imgproxy/) package is available from AUR.
|
||||
|
||||
### macOS + Homebrew
|
||||
|
||||
[imgproxy](https://formulae.brew.sh/formula/imgproxy) is available from Homebrew:
|
||||
```bash
|
||||
brew install imgproxy
|
||||
```
|
||||
|
||||
## From the source
|
||||
|
||||
You can get the imgproxy source code by cloning the GitHub repo:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/imgproxy/imgproxy.git
|
||||
cd imgproxy
|
||||
```
|
||||
|
||||
...or by downloading the source tarball:
|
||||
|
||||
```bash
|
||||
mkdir imgproxy
|
||||
cd imgproxy
|
||||
curl -Ls https://github.com/imgproxy/imgproxy/archive/master.tar.gz \
|
||||
| tar -xz --strip-components 1 -C .
|
||||
```
|
||||
|
||||
You can also download a specific version:
|
||||
|
||||
```bash
|
||||
mkdir imgproxy
|
||||
cd imgproxy
|
||||
curl -Ls https://github.com/imgproxy/imgproxy/archive/v2.13.1.tar.gz \
|
||||
| tar -xz --strip-components 1 -C .
|
||||
```
|
||||
|
||||
### Ubuntu
|
||||
|
||||
First, install [libvips](https://github.com/libvips/libvips).
|
||||
|
||||
The Ubuntu apt repository contains a pretty old version of libvips. You can use PPA to access a more recent version of libvips:
|
||||
|
||||
```bash
|
||||
sudo add-apt-repository ppa:dhor/myway
|
||||
sudo apt-get update
|
||||
sudo apt-get install libvips-dev
|
||||
```
|
||||
|
||||
But if you want to use all the features of imgproxy, it's recommended to build libvips from the source: [https://github.com/libvips/ libvips/wiki/Build-for-Ubuntu](https://github.com/libvips/libvips/wiki/Build-for-Ubuntu)
|
||||
|
||||
Next, install the latest version of Go:
|
||||
|
||||
```bash
|
||||
sudo add-apt-repository ppa:longsleep/golang-backports
|
||||
sudo apt-get update
|
||||
sudo apt-get install golang-go
|
||||
```
|
||||
|
||||
And finally, install imgproxy itself:
|
||||
|
||||
```bash
|
||||
CGO_LDFLAGS_ALLOW="-s|-w" \
|
||||
go build -o /usr/local/bin/imgproxy
|
||||
```
|
||||
|
||||
### macOS + Homebrew
|
||||
|
||||
```bash
|
||||
brew install vips go
|
||||
PKG_CONFIG_PATH="$(brew --prefix libffi)/lib/pkgconfig" \
|
||||
CGO_LDFLAGS_ALLOW="-s|-w" \
|
||||
CGO_CFLAGS_ALLOW="-Xpreprocessor" \
|
||||
go build -o /usr/local/bin/imgproxy
|
||||
```
|
||||
@ -1,160 +0,0 @@
|
||||
# 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
|
||||
|
||||
**📝 Note:** 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 darthsim/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 darthsim/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).
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
@ -1,58 +0,0 @@
|
||||
# Memory usage tweaks
|
||||
|
||||
There are some imgproxy options that can help you optimize memory usage and decrease memory fragmentation.
|
||||
|
||||
**⚠️ Warning:** This is an advanced part. Please make sure that you know what you're doing before changing anything.
|
||||
|
||||
### IMGPROXY_DOWNLOAD_BUFFER_SIZE
|
||||
|
||||
imgproxy uses memory buffers to download source images. While these buffers are empty at the beginning by default, they can grow to a required size when imgproxy downloads an image. Allocating new memory to grow the buffers can cause memory fragmentation. Allocating the required memory at the beginning can eliminate much of memory fragmentation since the buffers won't grow. Setting `IMGPROXY_DOWNLOAD_BUFFER_SIZE` will tell imgproxy to initialize download buffers with _at least_ the specified size. It's recommended to use the estimated 95 percentile of your image sizes as the initial download buffers size.
|
||||
|
||||
### IMGPROXY_FREE_MEMORY_INTERVAL
|
||||
|
||||
Working with a large amount of data can result in allocating some memory that is generally not used. That's why imgproxy enforces Go's garbage collector to free as much memory as possible and return it to the OS. The default interval of this action is 10 seconds, but you can change it by setting `IMGPROXY_FREE_MEMORY_INTERVAL`. Decreasing the interval can smooth out the memory usage graph but it can also slow down imgproxy a little. Increasing it has the opposite effect.
|
||||
|
||||
### IMGPROXY_BUFFER_POOL_CALIBRATION_THRESHOLD
|
||||
|
||||
Buffer pools in imgproxy do self-calibration time by time. imgproxy collects stats about the sizes of the buffers returned to a pool and calculates the default buffer size and the maximum size of a buffer that can be returned to the pool. This allows dropping buffers that are too big for most of the images and helps save some memory. By default, imgproxy starts calibration after 1024 buffers have been returned to a pool. You can change this number with the `IMGPROXY_BUFFER_POOL_CALIBRATION_THRESHOLD` variable. Increasing the number will give you rarer but more accurate calibration.
|
||||
|
||||
### MALLOC_ARENA_MAX
|
||||
|
||||
`libvips` uses GLib for memory management, and it brings with it GLib memory fragmentation issues to heavily multi-threaded programs. And imgproxy is definitely one of these. First thing you can try if you noticed constantly growing RSS usage without Go's sys memory growth is set `MALLOC_ARENA_MAX`:
|
||||
|
||||
```
|
||||
MALLOC_ARENA_MAX=2 imgproxy
|
||||
```
|
||||
|
||||
This will reduce GLib memory appetites by reducing the number of malloc arenas that it can create. By default GLib creates one are per thread, and this would follow to a memory fragmentation.
|
||||
|
||||
|
||||
### Using alternative malloc implementations
|
||||
|
||||
If setting `MALLOC_ARENA_MAX` doesn't show you satisfying results, it's time to try alternative malloc implementations.
|
||||
|
||||
#### jemalloc
|
||||
|
||||
> jemalloc is a general purpose malloc(3) implementation that emphasizes fragmentation avoidance and scalable concurrency support.
|
||||
|
||||
Most Linux distributives provide their jemalloc packages. Using jemalloc doesn't require rebuilding imgproxy or it's dependencies and can be enabled by the `LD_PRELOAD` environment variable. See the example with Debian below. Note that jemalloc library path may vary on your system.
|
||||
|
||||
```
|
||||
sudo apt-get install libjemalloc2
|
||||
LD_PRELOAD='/usr/lib/x86_64-linux-gnu/libjemalloc.so.2' imgproxy
|
||||
```
|
||||
|
||||
Official imgproxy Docker images starting `v3.17.0` have jemalloc preinstalled. Its usage can be enabled by setting the `IMGPROXY_MALLOC` environment variable to `jemalloc`.
|
||||
|
||||
#### TCMalloc
|
||||
|
||||
> TCMalloc is Google's customized implementation of C's malloc() and C++'s operator new used for memory allocation within our C and C++ code. TCMalloc is a fast, multi-threaded malloc implementation.
|
||||
|
||||
Most Linux distributives provide their TCMalloc packages. Using TCMalloc doesn't require rebuilding imgproxy or it's dependencies and can be enabled by the `LD_PRELOAD` environment variable. See the example with Debian below. Note that TCMalloc library path may vary on your system.
|
||||
|
||||
```
|
||||
sudo apt-get install libtcmalloc-minimal4
|
||||
LD_PRELOAD='/usr/lib/x86_64-linux-gnu/libtcmalloc_minimal.so.4' imgproxy
|
||||
```
|
||||
|
||||
Official imgproxy Docker images starting `v3.17.0` have TCMalloc preinstalled. Its usage can be enabled by setting the `IMGPROXY_MALLOC` environment variable to `tcmalloc`.
|
||||
@ -1,28 +0,0 @@
|
||||
# New Relic
|
||||
|
||||
imgproxy can send its metrics to New Relic. To use this feature, do the following:
|
||||
|
||||
1. Register at New Relic and get a license key.
|
||||
2. Set the `IMGPROXY_NEW_RELIC_KEY` environment variable to the license key.
|
||||
3. _(optional)_ Set the `IMGPROXY_NEW_RELIC_APP_NAME` environment variable to be the desired application name.
|
||||
4. _(optional)_ Set the `IMGPROXY_NEW_RELIC_LABELS` environment variable to be the desired list of labels. Example: `label1=value1;label2=value2`.
|
||||
|
||||
imgproxy will send the following info to New Relic:
|
||||
|
||||
* CPU and memory usage
|
||||
* Response time
|
||||
* Queue time
|
||||
* Image downloading time
|
||||
* Image processing time
|
||||
* Errors that occurred while downloading and processing an image
|
||||
|
||||
Additionally, imgproxy sends the following metrics over [Metrics API](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/):
|
||||
|
||||
* `imgproxy.requests_in_progress`: the number of requests currently in progress
|
||||
* `imgproxy.images_in_progress`: the number of images currently in progress
|
||||
* `imgproxy.buffer.size`: a summary of the download buffers sizes (in bytes)
|
||||
* `imgproxy.buffer.default_size`: calibrated default buffer size (in bytes)
|
||||
* `imgproxy.buffer.max_size`: calibrated maximum buffer size (in bytes)
|
||||
* `imgproxy.vips.memory`: libvips memory usage (in bytes)
|
||||
* `imgproxy.vips.max_memory`: libvips maximum memory usage (in bytes)
|
||||
* `imgproxy.vips.allocs`: the number of active vips allocations
|
||||
@ -1,49 +0,0 @@
|
||||
# Object detection
|
||||
|
||||
imgproxy can detect objects on the image and use them for smart cropping, bluring the detections, or drawing the detections. You can also [fetch the detected objects info](getting_the_image_info.md#detect-objects).
|
||||
|
||||
For object detection purposes, imgproxy uses the [Darknet YOLO](https://github.com/AlexeyAB/darknet) model. We provide Docker images with a model trained for face detection, but you can use any Darknet YOLO model found in the [zoo](https://github.com/AlexeyAB/darknet/wiki/YOLOv4-model-zoo) or you can train your own model by following this [guide](https://github.com/AlexeyAB/darknet#how-to-train-to-detect-your-custom-objects).
|
||||
|
||||
## Configuration
|
||||
|
||||
You need to define four config variables to enable object detection:
|
||||
|
||||
* `IMGPROXY_OBJECT_DETECTION_CONFIG`: a path to the neural network config
|
||||
* `IMGPROXY_OBJECT_DETECTION_WEIGHTS`: a path to the neural network weights
|
||||
* `IMGPROXY_OBJECT_DETECTION_CLASSES`: a path to the text file with the classes names, one per line
|
||||
* `IMGPROXY_OBJECT_DETECTION_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: 416
|
||||
|
||||
Read the [configuration guide](configuration.md#object-detection) for more config values info.
|
||||
|
||||
## Usage examples
|
||||
### Object-oriented crop
|
||||
|
||||
You can [crop](https://docs.imgproxy.net/generating_the_url?id=crop) your images and keep objects of desired classes in frame:
|
||||
|
||||
```
|
||||
.../crop:256:256/g:obj:face/...
|
||||
```
|
||||
|
||||
### Bluring detections
|
||||
|
||||
You can [blur objects](https://docs.imgproxy.net/generating_the_url?id=blur-detections) of desired classes, thus making anonymization or hiding NSFW content possible:
|
||||
|
||||
```
|
||||
.../blur_detections:7:face/...
|
||||
```
|
||||
|
||||
### Draw detections
|
||||
|
||||
You can make imgproxy [draw bounding boxes](https://docs.imgproxy.net/generating_the_url?id=draw-detections) for the detected objects of the desired classes (this is handy for testing your models):
|
||||
|
||||
```
|
||||
.../draw_detections:1:face/...
|
||||
```
|
||||
|
||||
### Fetch the detected objects info
|
||||
|
||||
You can [fetch the detected objects info](getting_the_image_info.md#detect-objects) using the `/info` endpoint:
|
||||
|
||||
```
|
||||
.../info/detect_objects:1/...
|
||||
```
|
||||
@ -1,54 +0,0 @@
|
||||
# OpenTelemetry
|
||||
|
||||
imgproxy can send request traces to an OpenTelemetry collector. To use this feature, do the following:
|
||||
|
||||
1. Install & configure the [OpenTelemetry collector](https://opentelemetry.io/docs/collector/).
|
||||
2. Specify the collector endpoint (`host:port`) with `IMGPROXY_OPEN_TELEMETRY_ENDPOINT` and the collector protocol with `IMGPROXY_OPEN_TELEMETRY_PROTOCOL`. Supported protocols are:
|
||||
* `grpc` _(default)_
|
||||
* `https`
|
||||
* `http`.
|
||||
3. _(optional)_ Set the `IMGPROXY_OPEN_TELEMETRY_SERVICE_NAME` environment variable to be the desired service name.
|
||||
4. _(optional)_ Set the `IMGPROXY_OPEN_TELEMETRY_PROPAGATORS` environment variable to be the desired list of text map propagators. Supported propagators are:
|
||||
* `tracecontext`: [W3C Trace Context](https://www.w3.org/TR/trace-context/)
|
||||
* `baggage`: [W3C Baggage](https://www.w3.org/TR/baggage/)
|
||||
* `b3`: [B3 Single](https://opentelemetry.io/docs/reference/specification/context/api-propagators/#configuration)
|
||||
* `b3multi`: [B3 Multi](https://opentelemetry.io/docs/reference/specification/context/api-propagators/#configuration)
|
||||
* `jaeger`: [Jaeger](https://www.jaegertracing.io/docs/1.21/client-libraries/#propagation-format)
|
||||
* `xray`: [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader)
|
||||
* `ottrace`: [OT Trace](https://github.com/opentracing?q=basic&type=&language=)
|
||||
5. _(optional)_ [Set up TLS certificates](#tls-configuration) or set `IMGPROXY_OPEN_TELEMETRY_GRPC_INSECURE` to `false` to use secure connection without TLS certificates set.
|
||||
6. _(optional)_ Set `IMGPROXY_OPEN_TELEMETRY_ENABLE_METRICS` to `true` to enable sending metrics via OpenTelemetry Metrics API.
|
||||
7. _(optional)_ Set `IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR` to environment variable to be the desired trace ID generator. Supported values are:
|
||||
* `xray`: _(default)_ Amazon X-Ray compatible trace ID generator
|
||||
* `random`: random trace ID generator
|
||||
|
||||
imgproxy will send the following info to the collector:
|
||||
|
||||
* Response time
|
||||
* Queue time
|
||||
* Image downloading time
|
||||
* Image processing time
|
||||
* Errors that occurred while downloading and processing an image
|
||||
|
||||
If `IMGPROXY_OPEN_TELEMETRY_ENABLE_METRICS` is set to `true`, imgproxy will also send the following metrics to the collector:
|
||||
|
||||
* `requests_in_progress`: the number of requests currently in progress
|
||||
* `images_in_progress`: the number of images currently in progress
|
||||
* `buffer_size_bytes`: a histogram of buffer sizes (in bytes)
|
||||
* `buffer_default_size_bytes`: calibrated default buffer size (in bytes)
|
||||
* `buffer_max_size_bytes`: calibrated maximum buffer size (in bytes)
|
||||
* `vips_memory_bytes`: libvips memory usage
|
||||
* `vips_max_memory_bytes`: libvips maximum memory usage
|
||||
* `vips_allocs`: the number of active vips allocations
|
||||
* Some useful Go metrics like memstats and goroutines count
|
||||
|
||||
## TLS Configuration
|
||||
|
||||
If your OpenTelemetry collector is secured with TLS, you may need to specify the collector's certificate on the imgproxy side:
|
||||
|
||||
* `IMGPROXY_OPEN_TELEMETRY_SERVER_CERT`: OpenTelemetry collector TLS certificate, PEM-encoded (you can replace line breaks with `\n`). Default: blank
|
||||
|
||||
If your collector uses mTLS for mutual authentication, you'll also need to specify the client's certificate/key pair:
|
||||
|
||||
* `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
|
||||
@ -1,33 +0,0 @@
|
||||
# Presets
|
||||
|
||||
An imgproxy preset is a named set of processing or info options. Presets can be used in [processing URLs](generating_the_url.md#preset) or [info URLs](getting_the_image_info.md#preset) to make them shorter and more human-readable.
|
||||
|
||||
## Presets definition
|
||||
|
||||
A preset definition looks like this:
|
||||
|
||||
```
|
||||
%preset_name=%options
|
||||
```
|
||||
|
||||
Options should be defined in the same way they are defined in [processing URLs](generating_the_url.md#processing-options) and [info URLs](getting_the_image_info.md#processing-options). For example, here's a preset named `awesome` that sets the resizing type to `fill` and the resulting format to `jpg`:
|
||||
|
||||
```
|
||||
awesome=resizing_type:fill/format:jpg
|
||||
```
|
||||
|
||||
Read how to specify your presets with imgproxy in the [Configuration](configuration.md#presets) guide.
|
||||
|
||||
## Default preset
|
||||
|
||||
A preset named `default` will be applied to each image. This is useful when you want your default processing options to be different from the default imgproxy options.
|
||||
|
||||
## Only presets
|
||||
|
||||
Setting `IMGPROXY_ONLY_PRESETS` to `true` switches imgproxy into presets-only mode. In this mode, imgproxy accepts a presets list as processing options just like you'd specify them for the `preset` option:
|
||||
|
||||
```
|
||||
http://imgproxy.example.com/unsafe/thumbnail:blurry:watermarked/plain/http://example.com/images/curiosity.jpg@png
|
||||
```
|
||||
|
||||
You can enable or disable the presets-only mode for the [info](getting_the_image_info.md) endpoint using the `IMGPROXY_INFO_ONLY_PRESETS` config. If `IMGPROXY_INFO_ONLY_PRESETS` is not set, the info endpoint respects the `IMGPROXY_ONLY_PRESETS` value.
|
||||
@ -1,31 +0,0 @@
|
||||
# Prometheus
|
||||
|
||||
imgproxy can collect metrics for Prometheus. To use this feature, do the following:
|
||||
|
||||
1. Set the `IMGPROXY_PROMETHEUS_BIND` environment variable to the address and port that will be listened to by the Prometheus server. Note that you can't bind the main server and Prometheus to the same port.
|
||||
2. _(optional)_ Set the `IMGPROXY_PROMETHEUS_NAMESPACE` to prepend prefix to the names of metrics, i.e. with `IMGPROXY_PROMETHEUS_NAMESPACE=imgproxy` names will appear like `imgproxy_requests_total`.
|
||||
3. Collect the metrics from any path on the specified binding.
|
||||
|
||||
imgproxy will collect the following metrics:
|
||||
|
||||
* `requests_total`: a counter with the total number of HTTP requests imgproxy has processed
|
||||
* `errors_total`: a counter of the occurred errors separated by type (timeout, downloading, processing)
|
||||
* `request_duration_seconds`: a histogram of the request latency (in seconds)
|
||||
* `request_span_duration_seconds`: a histogram of the request latency (in seconds) separated by span (queue, downloading, processing)
|
||||
* `requests_in_progress`: the number of requests currently in progress
|
||||
* `images_in_progress`: the number of images currently in progress
|
||||
* `buffer_size_bytes`: a histogram of the download buffers sizes (in bytes)
|
||||
* `buffer_default_size_bytes`: calibrated default buffer size (in bytes)
|
||||
* `buffer_max_size_bytes`: calibrated maximum buffer size (in bytes)
|
||||
* `vips_memory_bytes`: libvips memory usage
|
||||
* `vips_max_memory_bytes`: libvips maximum memory usage
|
||||
* `vips_allocs`: the number of active vips allocations
|
||||
* Some useful Go metrics like memstats and goroutines count
|
||||
|
||||
### Deprecated metrics
|
||||
|
||||
The following metrics are deprecated and can be removed in future versions. Use `request_span_duration_seconds` instead.
|
||||
|
||||
* `download_duration_seconds`: a histogram of the source image downloading latency (in seconds)
|
||||
* `processing_duration_seconds`: a histogram of the image processing latency (in seconds)
|
||||
|
||||
@ -1,2 +0,0 @@
|
||||
User-agent: *
|
||||
Allow: /
|
||||
@ -1,44 +0,0 @@
|
||||
# Serving files from Azure Blob Storage
|
||||
|
||||
imgproxy can process images from Azure Blob Storage containers. To use this feature, do the following:
|
||||
|
||||
1. Set `IMGPROXY_USE_ABS` environment variable to `true`
|
||||
2. Set `IMGPROXY_ABS_NAME` to your Azure account name
|
||||
3. [Set up the necessary credentials](#set-up-credentials)
|
||||
4. _(optional)_ Specify the Azure Blob Storage endpoint with `IMGPROXY_ABS_ENDPOINT`
|
||||
5. Use `abs://%bucket_name/%file_key` as the source image URL
|
||||
|
||||
## Set up credentials
|
||||
|
||||
### Leverage Azure Managed Identity or Service Principal
|
||||
|
||||
Microsoft encourages the use of a Managed Identity or Service Principal when accessing resources on an Azure Storage Account.
|
||||
Both of these authentication pathways are supported out of the box.
|
||||
|
||||
#### Managed Identity
|
||||
|
||||
There is no additional configuration required so long as the resource that imgproxy is running on has a Managed Identity assigned to it.
|
||||
|
||||
#### Service Principal
|
||||
|
||||
Please, refer to the [following documentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal) on the creation of a service principal before proceeding.
|
||||
|
||||
Once that step is completed, the following environment variables must be configured depending on which option was chosen.
|
||||
|
||||
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_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.
|
||||
@ -1,20 +0,0 @@
|
||||
# Serving files from Google Cloud Storage
|
||||
|
||||
imgproxy can process images from Google Cloud Storage buckets. To use this feature, do the following:
|
||||
|
||||
1. Set the `IMGPROXY_USE_GCS` environment variable to `true`.
|
||||
2. [Set up credentials](#setup-credentials) to grant access to your bucket.
|
||||
3. _(optional)_ Specify the Google Cloud Storage endpoint with `IMGPROXY_GCS_ENDPOINT`.
|
||||
4. Use `gs://%bucket_name/%file_key` as the source image URL.
|
||||
|
||||
If you need to specify generation of the source object, you can use the query string of the source URL:
|
||||
|
||||
```
|
||||
gs://%bucket_name/%file_key?%generation
|
||||
```
|
||||
|
||||
### Setup credentials
|
||||
|
||||
If you run imgproxy inside Google Cloud infrastructure (Compute Engine, Kubernetes Engine, App Engine, and Cloud Functions, etc), and you have granted access to your 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 `IMGPROXY_GCS_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).
|
||||
@ -1,14 +0,0 @@
|
||||
# Serving files from OpenStack Object Storage ("Swift")
|
||||
|
||||
imgproxy can process images from OpenStack Object Storage, also known as Swift. To use this feature, do the following:
|
||||
|
||||
1. Set the `IMGPROXY_USE_SWIFT` environment variable to `true`
|
||||
2. Configure Swift authentication with the following environment variables
|
||||
* `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
|
||||
|
||||
3. Use `swift://%{container}/%{object_path}` as the source image URL, e.g. an original object storage URL in the format of `/v1/{account}/{container}/{object_path}`, such as `http://127.0.0.1:8080/v1/AUTH_test/images/flowers/rose.jpg`, should be converted to `swift://images/flowers/rose.jpg`.
|
||||
@ -1,69 +0,0 @@
|
||||
# Serving files from S3
|
||||
|
||||
imgproxy can process images from S3 buckets. To use this feature, do the following:
|
||||
|
||||
1. Set the `IMGPROXY_USE_S3` environment variable to be `true`.
|
||||
2. [Set up the necessary credentials](#set-up-credentials) to grant access to your bucket.
|
||||
3. _(optional)_ Specify the AWS region with `IMGPROXY_S3_REGION` or `AWS_REGION`. Default: `us-west-1`
|
||||
4. _(optional)_ Specify the S3 endpoint with `IMGPROXY_S3_ENDPOINT`.
|
||||
5. _(optional)_ Set the `IMGPROXY_S3_MULTI_REGION` environment variable to be `true`.
|
||||
6. _(optional)_ Specify the AWS IAM Role to Assume with `IMGPROXY_S3_ASSUME_ROLE_ARN`
|
||||
7. Use `s3://%bucket_name/%file_key` as the source image URL.
|
||||
|
||||
If you need to specify the version of the source object, you can use the query string of the source URL:
|
||||
|
||||
```
|
||||
s3://%bucket_name/%file_key?%version_id
|
||||
```
|
||||
|
||||
### Set up credentials
|
||||
|
||||
There are three ways to specify your AWS credentials. The credentials need to have read rights for all of the buckets given in the source URLs:
|
||||
|
||||
#### 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 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 darthsim/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
|
||||
|
||||
S3 access credentials may be acquired by assuming a role using STS. To do so specify the IAM Role arn with the `IMGPROXY_S3_ASSUME_ROLE_ARN` 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 provided ARN.
|
||||
|
||||
## Multi-Region mode
|
||||
|
||||
By default, imgproxy allows using S3 buckets located in a single region specified with `IMGPROXY_S3_REGION` or `AWS_REGION`. If your buckets are located in different regions, set `IMGPROXY_S3_MULTI_REGION` environment variable to be `true` to enable multi-region mode. In this mode, imgproxy will make an additional request to determine the bucket's region when the bucket is accessed for the first time.
|
||||
|
||||
In this mode, imgroxy uses a region specified with `IMGPROXY_S3_REGION` or `AWS_REGION` to determine the endpoint to which it should send the bucket's region determination request. Thus, it's a good idea to use one of these variables to specify a region closest to the imgproxy instance.
|
||||
|
||||
## MinIO
|
||||
|
||||
[MinIO](https://github.com/minio/minio) is an object storage server released under Apache License v2.0. It is compatible with Amazon S3, so it can be used with imgproxy.
|
||||
|
||||
To use MinIO as source images provider, do the following:
|
||||
|
||||
* Set up Amazon S3 support as usual using environment variables or a shared config file.
|
||||
* Specify an endpoint with `IMGPROXY_S3_ENDPOINT`. Use the `http://...` endpoint to disable SSL.
|
||||
@ -1,26 +0,0 @@
|
||||
# Serving local files
|
||||
|
||||
imgproxy can be configured to process files from your local filesystem. To use this feature, do the following:
|
||||
|
||||
1. Set `IMGPROXY_LOCAL_FILESYSTEM_ROOT` environment variable to your local images directory path.
|
||||
2. Use `local:///path/to/image.jpg` as the source image URL.
|
||||
|
||||
### Example
|
||||
|
||||
Assume you want to process an image that is stored locally at `/path/to/project/images/logos/evil_martians.png`. Run imgproxy with `IMGPROXY_LOCAL_FILESYSTEM_ROOT` set to your images directory:
|
||||
|
||||
```bash
|
||||
IMGPROXY_LOCAL_FILESYSTEM_ROOT=/path/to/project/images imgproxy
|
||||
```
|
||||
|
||||
Then, use the path inside this directory as the source URL:
|
||||
|
||||
```
|
||||
local:///logos/evil_martians.png
|
||||
```
|
||||
|
||||
The URL for resizing this image to fit 300x200 will look like this:
|
||||
|
||||
```
|
||||
http://imgproxy.example.com/insecure/rs:fit:300:200:no:0/plain/local:///logos/evil_martians.png@jpg
|
||||
```
|
||||
@ -1,70 +0,0 @@
|
||||
# Signing the URL
|
||||
|
||||
imgproxy allows you to sign your URLs with a key and salt, so an attacker won’t be able to perform a denial-of-service attack by requesting multiple different image resizes.
|
||||
|
||||
### Configuring URL signature
|
||||
|
||||
URL signature checking is disabled by default, but it is highly recommended to enable it in a production environment. To do so, define a key/salt pair by setting the following environment variables:
|
||||
|
||||
* `IMGPROXY_KEY`: hex-encoded key
|
||||
* `IMGPROXY_SALT`: hex-encoded salt
|
||||
|
||||
Read our [Configuration](configuration.md#url-signature) guide to learn more ways of setting keys and salts.
|
||||
|
||||
If you need a random key/salt pair in a hurry, you can quickly generate one using the following snippet:
|
||||
|
||||
```bash
|
||||
echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n')
|
||||
```
|
||||
|
||||
### Calculating URL signature
|
||||
|
||||
A signature is a URL-safe Base64-encoded HMAC digest of the rest of the path, including the leading `/`. Here’s how it’s calculated:
|
||||
|
||||
|
||||
* Take the part of the path after the signature:
|
||||
* For [processing URLs](generating_the_url.md): `/%processing_options/%encoded_url.%extension`, `/%processing_options/plain/%plain_url@%extension`, or `/%processing_options/enc/%encrypted_url.%extension`
|
||||
* For [info URLs](getting_the_image_info.md): `/%encoded_url`, `/plain/%plain_url`, or `/enc/%encrypted_url`
|
||||
* Add a salt to the beginning.
|
||||
* Calculate the HMAC digest using SHA256.
|
||||
* Encode the result with URL-safe Base64.
|
||||
|
||||
### Example
|
||||
|
||||
**You can find helpful code snippets in various programming languages the [examples](https://github.com/imgproxy/imgproxy/tree/master/examples) folder. There's a good chance you'll find a snippet in your favorite programming language that you'll be able to use right away.**
|
||||
|
||||
And here is a step-by-step example of URL signature creation:
|
||||
|
||||
Assume that you have the following unsigned URL:
|
||||
|
||||
```
|
||||
http://imgproxy.example.com/insecure/rs:fill:300:400:0/g:sm/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png
|
||||
```
|
||||
|
||||
To sign it, you need to configure imgproxy to use your key/salt pair. Let's say, your key and salt are `secret` and `hello`, respectively — that translates to `736563726574` and `68656C6C6F` in hex encoding. This key/salt pair is quite weak for production purposes but will do for this example. Run imgproxy using this key/salt pair, like so:
|
||||
|
||||
```bash
|
||||
IMGPROXY_KEY=736563726574 IMGPROXY_SALT=68656C6C6F imgproxy
|
||||
```
|
||||
|
||||
Note that all your unsigned URL will stop working since imgproxy now checks all URL signatures.
|
||||
|
||||
First, you need to take the path after the signature and add the salt to the beginning:
|
||||
|
||||
```
|
||||
hello/rs:fill:300:400:0/g:sm/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png
|
||||
```
|
||||
|
||||
Then calculate the HMAC digest of this string using SHA256 and encode it with URL-safe Base64:
|
||||
|
||||
```
|
||||
oKfUtW34Dvo2BGQehJFR4Nr0_rIjOtdtzJ3QFsUcXH8
|
||||
```
|
||||
|
||||
And finally, add the signature to your URL:
|
||||
|
||||
```
|
||||
http://imgproxy.example.com/oKfUtW34Dvo2BGQehJFR4Nr0_rIjOtdtzJ3QFsUcXH8/rs:fill:300:400:0/g:sm/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png
|
||||
```
|
||||
|
||||
Now you have a URL that you can use to securely resize the image.
|
||||
@ -1,58 +0,0 @@
|
||||
# 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 `IMGPROXY_WATERMARK_OPACITY`.
|
||||
|
||||
**📝 Note:** 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` processing option to put a watermark on a processed image:
|
||||
|
||||
```
|
||||
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 :id=custom-watermarks
|
||||
|
||||
You can use a custom watermark by specifying its URL with the `watermark_url` processing 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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user