mirror of
https://github.com/imgproxy/imgproxy.git
synced 2025-02-02 11:34:20 +02:00
Update docs
This commit is contained in:
DarthSim
parent
7b9a32d700
commit
1851da0ad5
@ -1,10 +1,10 @@
|
||||
# Getting started
|
||||
|
||||
This guide will show you how to quickly get you first image resized with imgproxy.
|
||||
This guide will show you how to get your first image resized with imgproxy quickly.
|
||||
|
||||
## Install
|
||||
|
||||
Let's assume you have Docker installed on your machine. Then you can just pull official imgproxy image, and you're done!
|
||||
Let's assume you have Docker installed on your machine. Then you can pull an official imgproxy image, and you're done!
|
||||
|
||||
```bash
|
||||
$ docker pull darthsim/imgproxy:latest
|
||||
@ -21,13 +21,13 @@ That's it! No further configuration is needed, but if you want to unleash the fu
|
||||
|
||||
## Resize an image
|
||||
|
||||
After you installed imgproxy, you can use the following URL to get the resized image of Matt Damon from "The Martian" movie (replace `localhost:8080` with your domain if you installed imgproxy on a remote server):
|
||||
After you've successfully installed imgproxy, you might want to see if it is working correctly. To check that, you can use the following URL to get the resized image of Matt Damon from "The Martian" movie (replace `localhost:8080` with your domain if you installed imgproxy on a remote server):
|
||||
[http://localhost:8080/insecure/fill/300/400/sm/0/aHR0cHM6Ly9tLm1l/ZGlhLWFtYXpvbi5j/b20vaW1hZ2VzL00v/TVY1Qk1tUTNabVk0/TnpZdFkyVm1ZaTAw/WkRSbUxUZ3lPREF0/WldZelpqaGxOemsx/TnpVMlhrRXlYa0Zx/Y0dkZVFYVnlOVGMz/TWpVek5USUAuanBn.jpg](http://localhost:8080/insecure/fill/300/400/sm/0/aHR0cHM6Ly9tLm1l/ZGlhLWFtYXpvbi5j/b20vaW1hZ2VzL00v/TVY1Qk1tUTNabVk0/TnpZdFkyVm1ZaTAw/WkRSbUxUZ3lPREF0/WldZelpqaGxOemsx/TnpVMlhrRXlYa0Zx/Y0dkZVFYVnlOVGMz/TWpVek5USUAuanBn.jpg)
|
||||
|
||||
[The original image](https://m.media-amazon.com/images/M/MV5BMmQ3ZmY4NzYtY2VmYi00ZDRmLTgyODAtZWYzZjhlNzk1NzU2XkEyXkFqcGdeQXVyNTc3MjUzNTI@.jpg) is resized to fill `300x400` with smart gravity. `libvips` chose the most interesting part of the image.
|
||||
Here's [the original image](https://m.media-amazon.com/images/M/MV5BMmQ3ZmY4NzYtY2VmYi00ZDRmLTgyODAtZWYzZjhlNzk1NzU2XkEyXkFqcGdeQXVyNTc3MjUzNTI@.jpg), just for reference. Using the URL above, imgproxy is told to resize it to fill the area of `300x400` size with "smart" gravity. "Smart" means that the `libvips` library chooses the most "interesting" part of the image.
|
||||
|
||||
Get more info about generation imgproxy URLs in the [Generating the URL](./generating_the_url_basic.md) guide.
|
||||
Learn more on how to generate imgproxy URLs in the [Generating the URL](./generating_the_url_basic.md) guide.
|
||||
|
||||
## Security
|
||||
|
||||
Note that this URL is not signed. It's highly recommended to sign URLs in production. Read our [Signing the URL](./signing_the_url.md) guide to know how to secure your imgproxy from attackers.
|
||||
Note that the URL in the above example is not signed. It is highly recommended to sign URLs in production. Read our [Signing the URL](./signing_the_url.md) guide to know how to secure your imgproxy installation from attackers.
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
# About processing pipeline
|
||||
# About the processing pipeline
|
||||
|
||||
imgproxy has a fixed processing pipeline that tuned for maximum performance. When you process an image with imgproxy, it does the following things:
|
||||
imgproxy has a specific processing pipeline tuned for maximum performance. When you process an image with imgproxy, it does the following:
|
||||
|
||||
* If source image format allows shrink-on-load, imgproxy uses it to quickly resize image to the size closest to desired;
|
||||
* If it's needed to resize an image with alpha-channel, imgproxy premultiplies one to handle alpha correctly;
|
||||
* Resize image to desired size;
|
||||
* If image colorspace need to be fixed, imgproxy does this;
|
||||
* Rotate/flip image according to EXIF metadata;
|
||||
* Crop image using specified gravity;
|
||||
* Fill image background if some background color was specified;
|
||||
* Apply gaussian blur and sharpen filters;
|
||||
* And finally save the image to the desired format.
|
||||
* 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 specified gravity;
|
||||
* imgproxy fills the image background if the background color was specified;
|
||||
* imgproxy applies gaussian blur and sharpen filters;
|
||||
* And finally, imgproxy saves the image to the desired format.
|
||||
|
||||
This pipeline with using a sequential access to source image data allows to highly reduce memory and CPU usage, that makes imgproxy so awesome.
|
||||
This pipeline with using sequential access to source image data allows to significantly reduce memory and CPU usage — one of the reasons imgproxy is so performant.
|
||||
|
||||
@ -4,10 +4,10 @@ imgproxy is [Twelve-Factor-App](https://12factor.net/)-ready and can be configur
|
||||
|
||||
### URL signature
|
||||
|
||||
imgproxy allows URLs to be signed with a key and salt. This feature is disabled by default, but it's highly recommended to enable it in production. To enable URL signature checking, define key/salt pair:
|
||||
imgproxy allows URLs to be signed with a key and salt. This feature is disabled by default, but it is _highly_ recommended to enable it in production. To enable URL signature checking, define the key/salt pair:
|
||||
|
||||
* `IMGPROXY_KEY` — hex-encoded key;
|
||||
* `IMGPROXY_SALT` — hex-encoded salt;
|
||||
* `IMGPROXY_KEY`: hex-encoded key;
|
||||
* `IMGPROXY_SALT`: hex-encoded salt;
|
||||
|
||||
You can also specify paths to files with a hex-encoded key and salt (useful in a development environment):
|
||||
|
||||
@ -23,68 +23,69 @@ $ echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n')
|
||||
|
||||
### Server
|
||||
|
||||
* `IMGPROXY_BIND` — TCP address to listen on. Default: `:8080`;
|
||||
* `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_DOWNLOAD_TIMEOUT` — the maximum duration (in seconds) for downloading the source image. Default: `5`;
|
||||
* `IMGPROXY_CONCURRENCY` — the maximum number of image requests to be processed simultaneously. Default: double number of CPU cores;
|
||||
* `IMGPROXY_MAX_CLIENTS` — the maximum number of simultaneous active connections. Default: `IMGPROXY_CONCURRENCY * 10`;
|
||||
* `IMGPROXY_TTL` — duration in seconds sent in `Expires` and `Cache-Control: max-age` headers. Default: `3600` (1 hour);
|
||||
* `IMGPROXY_USE_ETAG` — when `true`, enables using [ETag](https://en.wikipedia.org/wiki/HTTP_ETag) header for the cache control. Default: false;
|
||||
* `IMGPROXY_BIND`: TCP address and port to listen on. Default: `:8080`;
|
||||
* `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_DOWNLOAD_TIMEOUT`: the maximum duration (in seconds) for downloading the source image. Default: `5`;
|
||||
* `IMGPROXY_CONCURRENCY`: the maximum number of image requests to be processed simultaneously. Default: number of CPU cores times two;
|
||||
* `IMGPROXY_MAX_CLIENTS`: the maximum number of simultaneous active connections. Default: `IMGPROXY_CONCURRENCY * 10`;
|
||||
* `IMGPROXY_TTL`: duration (in seconds) sent in `Expires` and `Cache-Control: max-age` HTTP headers. Default: `3600` (1 hour);
|
||||
* `IMGPROXY_USE_ETAG`: when `true`, enables using [ETag](https://en.wikipedia.org/wiki/HTTP_ETag) HTTP header for HTTP cache control. Default: false;
|
||||
|
||||
### Security
|
||||
|
||||
imgproxy protects you from so-called image bombs. Here is how you can specify maximum image dimensions and resolution which you consider reasonable:
|
||||
|
||||
* `IMGPROXY_MAX_SRC_DIMENSION` — the maximum dimensions of the source image, in pixels, for both width and height. Images with larger real size will be rejected. Default: `8192`;
|
||||
* `IMGPROXY_MAX_SRC_RESOLUTION` — the maximum resolution of the source image, in megapixels. Images with larger real size will be rejected. Default: `16.8`;
|
||||
* `IMGPROXY_MAX_SRC_DIMENSION`: the maximum dimensions of the source image, in pixels, for both width and height. Images with larger actual size will be rejected. Default: `8192`;
|
||||
* `IMGPROXY_MAX_SRC_RESOLUTION`: the maximum resolution of the source image, in megapixels. Images with larger actual size will be rejected. Default: `16.8`;
|
||||
|
||||
You can also specify a secret to enable authorization with the HTTP `Authorization` header:
|
||||
You can also specify a secret to enable authorization with the HTTP `Authorization` header for use in production environments:
|
||||
|
||||
* `IMGPROXY_SECRET` — the authorization token. If specified, a request should contain the `Authorization: Bearer %secret%` header;
|
||||
* `IMGPROXY_SECRET`: the authorization token. If specified, the HTTP request should contain the `Authorization: Bearer %secret%` header;
|
||||
|
||||
imgproxy doesn't send CORS headers by default. Specify allowed origin to enable CORS headers:
|
||||
imgproxy does not send CORS headers by default. Specify allowed origin to enable CORS headers:
|
||||
|
||||
* `IMGPROXY_ALLOW_ORIGIN` - when set, enables CORS headers with provided origin. CORS headers are disabled by default.
|
||||
* `IMGPROXY_ALLOW_ORIGIN`: when set, enables CORS headers with provided origin. CORS headers are disabled by default.
|
||||
|
||||
When you use imgproxy in development, it would be useful to ignore SSL verification:
|
||||
When you use 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 development with self-signed SSL certificates.
|
||||
* `IMGPROXY_IGNORE_SSL_VERIFICATION`: when true, disables SSL verification, so imgproxy can be used in a development environment with self-signed SSL certificates.
|
||||
|
||||
### Compression
|
||||
|
||||
* `IMGPROXY_QUALITY` — quality of the resulting image, percentage. Default: `80`;
|
||||
* `IMGPROXY_GZIP_COMPRESSION` — GZip compression level. Default: `5`;
|
||||
* `IMGPROXY_JPEG_PROGRESSIVE` — when true, enables progressive compression of JPEG. Default: false;
|
||||
* `IMGPROXY_PNG_INTERLACED` — when true, enables interlaced compression of PNG. Default: false;
|
||||
* `IMGPROXY_QUALITY`: quality of the resulting image, percentage. Default: `80`;
|
||||
* `IMGPROXY_GZIP_COMPRESSION`: GZip compression level. Default: `5`;
|
||||
* `IMGPROXY_JPEG_PROGRESSIVE` : when true, enables progressive JPEG compression. Default: false;
|
||||
* `IMGPROXY_PNG_INTERLACED`: when true, enables interlaced PNG compression. Default: false;
|
||||
|
||||
## WebP support detection
|
||||
|
||||
Imgproxy can use `Accept` header to detect if browser supports WebP and use it as the default format. This feature is disabled by default and can be enabled by the following options:
|
||||
imgproxy can use the `Accept` HTTP header to detect if the browser supports 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 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_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.
|
||||
|
||||
When WebP support detection is enabled, take care to configure your CDN or caching proxy to consider the `Accept` header while caching.
|
||||
**Warning**: Headers can't be signed. This means that attacker can bypass your CDN cache by changing the `Accept` header. Take this in mind while configuring CDN/caching proxy.
|
||||
When 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 header. Have this in mind when configuring your production caching setup.
|
||||
|
||||
### Presets
|
||||
|
||||
Read about presets in the [Presets](./presets.md) guide.
|
||||
Read about imgproxy presets in the [Presets](./presets.md) guide.
|
||||
|
||||
There are two ways to define presets:
|
||||
|
||||
##### Using environment variable
|
||||
##### Using an environment variable
|
||||
|
||||
* `IMGPROXY_PRESETS` - set of presets definitions divided by comma. Example: `default=resize_type:fill/enlarge:1,sharp=sharpen:0.7,blurry=blur:2`. Default: blank.
|
||||
* `IMGPROXY_PRESETS`: set of preset definitions, comma-divided. Example: `default=resize_type:fill/enlarge:1,sharp=sharpen:0.7,blurry=blur:2`. Default: blank.
|
||||
|
||||
##### Using command line argument
|
||||
##### Using a command line argument
|
||||
|
||||
```bash
|
||||
$ imgproxy -presets /path/to/file/with/presets
|
||||
```
|
||||
|
||||
The file should contain presets definitions one by line. Lines starting with `#` are treated as comments. Example:
|
||||
The file should contain preset definitions, one per line. Lines starting with `#` are treated as comments. Example:
|
||||
|
||||
```
|
||||
default=resize_type:fill/enlarge:1
|
||||
@ -100,19 +101,18 @@ blurry=blur:2
|
||||
|
||||
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 empty to disable serving of local files.
|
||||
* `IMGPROXY_LOCAL_FILESYSTEM_ROOT`: the root of the local filesystem. Keep empty to disable serving of local files.
|
||||
|
||||
Check out [Serving local files](./serving_local_files.md) guide to get more info.
|
||||
Check out the [Serving local files](./serving_local_files.md) guide to learn more.
|
||||
|
||||
### 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` as `true`:
|
||||
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 fetching the images from Amazon S3 buckets. Default: false.
|
||||
* `IMGPROXY_USE_S3`: when `true`, enables image fetching from Amazon S3 buckets. Default: false.
|
||||
|
||||
Check out [Serving files from S3](./serving_files_from_s3.md) guide to get more info.
|
||||
Check out the [Serving files from S3](./serving_files_from_s3.md) guide to learn more.
|
||||
|
||||
### Miscellaneous
|
||||
|
||||
* `IMGPROXY_BASE_URL` - base URL part which will be added to every requested image URL. For example, if base URL is `http://example.com/images` and `/path/to/image.png` is requested, imgproxy will download the image from `http://example.com/images/path/to/image.png`. Default: blank.
|
||||
|
||||
* `IMGPROXY_BASE_URL`: base URL prefix that will be added to every requested 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`. Default: blank.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Generating the URL (Advanced)
|
||||
|
||||
This guide describes the advanced URL format that supports all the imgproxy features. Read our [Generating the URL (Basic)](./generating_the_url_basic.md) guide to get info about basic URL format that is compatible with the first version of imgproxy.
|
||||
This guide describes the advanced URL format that allows the use of all the imgproxy features. Read our [Generating the URL (Basic)](./generating_the_url_basic.md) guide to learn about the _basic_ URL format that is compatible with imgproxy 1.x.
|
||||
|
||||
### Format definition
|
||||
|
||||
@ -14,9 +14,9 @@ Check out the [example](#example) at the end of this guide.
|
||||
|
||||
#### Signature
|
||||
|
||||
Signature protects your URL from being changed by an attacker. It's highly recommended to sign imgproxy URLs in production.
|
||||
Signature protects your URL from being altered by an attacker. It is highly recommended to sign imgproxy URLs in production.
|
||||
|
||||
If you set up [URL signature](./configuration.md#url-signature), check out [Signing the URL](./signing_the_url.md) guide to know how to sign your URLs. Otherwise, use any string here.
|
||||
Once you set up your [URL signature](./configuration.md#url-signature), check out the [Signing the URL](./signing_the_url.md) guide to know how to sign your URLs. Otherwise, use any string here.
|
||||
|
||||
#### Processing options
|
||||
|
||||
@ -26,7 +26,7 @@ Processing options should be specified as URL parts divided by slashes (`/`). Pr
|
||||
%option_name:%argument1:%argument2:...:argumentN
|
||||
```
|
||||
|
||||
Processing options should not be treated as a processing pipeline. Processing pipeline of imgproxy is fixed to provide you a maximum performance. Read more about it in [About processing pipeline](./about_processing_pipeline.md) guide.
|
||||
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 the maximum performance. Read more about it in the [About processing pipeline](./about_processing_pipeline.md) guide.
|
||||
|
||||
imgproxy supports the following processing options:
|
||||
|
||||
@ -35,14 +35,14 @@ imgproxy supports the following processing options:
|
||||
`resize:%resizing_type:%width:%height:%enlarge`
|
||||
`rs:%resizing_type:%width:%height:%enlarge`
|
||||
|
||||
Meta-option that defines [resizing type](#resizing-type), [width](#width), [height](#height), and [enlarge](#enlarge). All arguments are optional and can be omited to use their default values.
|
||||
Meta-option that defines the [resizing type](#resizing-type), [width](#width), [height](#height), and [enlarge](#enlarge). All arguments are optional and can be omited to use their default values.
|
||||
|
||||
##### Size
|
||||
|
||||
`size:%width:%height:%enlarge`
|
||||
`s:%width:%height:%enlarge`
|
||||
|
||||
Meta-option that defines [width](#width), [height](#height), and [enlarge](#enlarge). All arguments are optional and can be omited to use their default values.
|
||||
Meta-option that defines the [width](#width), [height](#height), and [enlarge](#enlarge). All arguments are optional and can be omited to use their default values.
|
||||
|
||||
##### Resizing type
|
||||
|
||||
@ -51,9 +51,9 @@ Meta-option that defines [width](#width), [height](#height), and [enlarge](#enla
|
||||
|
||||
Defines how imgproxy will resize the source image. Supported resizing types are:
|
||||
|
||||
* `fit` — resizes the image while keeping aspect ratio to fit given size;
|
||||
* `fill` — resizes the image while keeping aspect ratio to fill given size and cropping projecting parts;
|
||||
* `crop` — crops the image to a given size.
|
||||
* `fit`: resizes the image while keeping aspect ratio to fit given size;
|
||||
* `fill`: resizes the image while keeping aspect ratio to fill given size and cropping projecting parts;
|
||||
* `crop`: crops the image to a given size.
|
||||
|
||||
Default: `fit`
|
||||
|
||||
@ -62,7 +62,7 @@ Default: `fit`
|
||||
`width:%width`
|
||||
`w:%width`
|
||||
|
||||
Defines the width of the resulting image. When set to `0`, imgproxy will calculate resulting width by defined height and source aspect ratio. When set to `0` and `crop` resizing type is used, imgproxy will use the full width of the source image.
|
||||
Defines the width of the resulting image. When set to `0`, imgproxy will calculate the resulting width using the defined height and source aspect ratio. When set to `0` and the `crop` resizing type is used, imgproxy will use the full width of the source image.
|
||||
|
||||
Default: `0`
|
||||
|
||||
@ -71,7 +71,7 @@ Default: `0`
|
||||
`height:%height`
|
||||
`h:%height`
|
||||
|
||||
Defines the height of the resulting image. When set to `0`, imgproxy will calculate resulting height by defined width and source aspect ratio. When set to `0` and `crop` resizing type is used, imgproxy will use the full height of the source image.
|
||||
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 `crop` resizing type is used, imgproxy will use the full height of the source image.
|
||||
|
||||
Default: `0`
|
||||
|
||||
@ -91,13 +91,13 @@ Default: `0`
|
||||
|
||||
When imgproxy needs to cut some parts of the image, it is guided by the gravity. The following values are supported:
|
||||
|
||||
* `no` — north (top edge);
|
||||
* `so` — south (bottom edge);
|
||||
* `ea` — east (right edge);
|
||||
* `we` — west (left edge);
|
||||
* `ce` — center;
|
||||
* `sm` — smart. `libvips` detects the most "interesting" section of the image and considers it as the center of the resulting image;
|
||||
* `fp:%x:%y` - focus point. `x` and `y` are floating point numbers between 0 and 1 that defines coordinates of the center of the resulting image. Trait 0 and 1 as right/left for `x` and top/bottom for `y`.
|
||||
* `no`: north (top edge);
|
||||
* `so`: south (bottom edge);
|
||||
* `ea`: east (right edge);
|
||||
* `we`: west (left edge);
|
||||
* `ce`: center;
|
||||
* `sm`: smart. `libvips` detects the most "interesting" section of the image and considers it as the center of the resulting image;
|
||||
* `fp:%x:%y`: 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`.
|
||||
|
||||
Default: `ce`
|
||||
|
||||
@ -109,9 +109,9 @@ Default: `ce`
|
||||
`background:%hex_color`
|
||||
`bg:%hex_color`
|
||||
|
||||
When set, imgproxy will fill the resulting image background with specified color. `R`, `G`, and `B` are red, green and blue channel values of background color (0-255). `hex_color` is hex-coded color. Useful when you convert an image with alpha-channel to JPEG.
|
||||
When set, imgproxy will fill the resulting image background with the specified color. `R`, `G`, and `B` are 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.
|
||||
|
||||
When no arguments is provided, disables background.
|
||||
With no arguments provided, disables any background manipulations.
|
||||
|
||||
Default: disabled
|
||||
|
||||
@ -120,7 +120,7 @@ Default: disabled
|
||||
`blur:%sigma`
|
||||
`bl:%sigma`
|
||||
|
||||
When set, imgproxy will apply gaussian blur filter to the resulting image. `sigma` defines how large a mask imgproxy will use.
|
||||
When set, imgproxy will apply the gaussian blur filter to the resulting image. `sigma` defines the size of a mask imgproxy will use.
|
||||
|
||||
Default: disabled
|
||||
|
||||
@ -129,7 +129,7 @@ Default: disabled
|
||||
`sharpen:%sigma`
|
||||
`sh:%sigma`
|
||||
|
||||
When set, imgproxy will apply sharpen filter to the resulting image. `sigma` defines how large a mask imgproxy will use.
|
||||
When set, imgproxy will apply the sharpen filter to the resulting image. `sigma` the size of a 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).
|
||||
|
||||
@ -140,9 +140,9 @@ Default: disabled
|
||||
`preset:%preset_name1:%preset_name2:...:%preset_nameN`
|
||||
`pr:%preset_name1:%preset_name2:...:%preset_nameN`
|
||||
|
||||
Defines presets to be used by imgproxy. Feel free to use as many presets in a single URL as you need.
|
||||
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 our [Presets](./presets.md) guide.
|
||||
Read more about presets in the [Presets](./presets.md) guide.
|
||||
|
||||
Default: empty
|
||||
|
||||
@ -152,7 +152,7 @@ Default: empty
|
||||
`f:%extension`
|
||||
`ext:%extension`
|
||||
|
||||
Specifies resulting image format. Alias for [extension](#extension) URL part.
|
||||
Specifies the resulting image format. Alias for [extension](#extension) URL part.
|
||||
|
||||
Default: `jpg`
|
||||
|
||||
@ -162,13 +162,13 @@ The source URL should be encoded with URL-safe Base64. The encoded URL can be sp
|
||||
|
||||
#### Extension
|
||||
|
||||
Extension specifies the format of the resulting image. At the moment, imgproxy supports only `jpg`, `png` and `webp`, them being the most popular and useful web image formats.
|
||||
Extension specifies the format of the resulting image. At the moment, imgproxy supports only `jpg`, `png` and `webp`, them being the most popular and useful image formats on the Web.
|
||||
|
||||
The extension part can be omitted. In this case, if the format is not defined by processing options, imgproxy will use `jpg` by default. You also can [enable WebP support detection](./configuration.md#webp-support-detection) to use it as default resulting format when possible.
|
||||
The extension part can be omitted. In this case, if the format is not defined by processing options, imgproxy will use `jpg` by default. You can also [enable WebP support detection](./configuration.md#webp-support-detection) to use it as default resulting format when possible.
|
||||
|
||||
### Example
|
||||
|
||||
Signed imgproxy URL that uses `sharp` preset, resizes `http://example.com/images/curiosity.jpg` to fill `300x400` area with smart gravity without enlarging, and converts the image to `png` will look like this:
|
||||
Signed imgproxy URL that uses `sharp` preset, resizes `http://example.com/images/curiosity.jpg` to fill `300x400` area with 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/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png
|
||||
@ -176,7 +176,6 @@ http://imgproxy.example.com/AfrOrF3gWeDA6VOlDG4TzxMv39O7MXnF4CXpKUwGqRM/preset:s
|
||||
|
||||
The same URL with shortcuts will look like this:
|
||||
|
||||
|
||||
```
|
||||
http://imgproxy.example.com/AfrOrF3gWeDA6VOlDG4TzxMv39O7MXnF4CXpKUwGqRM/pr:sharp/rs:fill:300:400:0/g:sm/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png
|
||||
```
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Generating the URL (Basic)
|
||||
|
||||
This guide describes the simple URL format that is easy to use but doesn't support the whole range of imgproxy features. This URL format is mostly backward-compatible with the first version of imgproxy. Read our [Generating the URL (Advanced)](./generating_the_url_advanced.md) guide to get info about advanced URL format.
|
||||
This guide describes the simple URL format that is easy to use but doesn't support the whole range of imgproxy features. This URL format is mostly supported for backwards compatibility with imgproxy 1.x. Please read our [Generating the URL (Advanced)](./generating_the_url_advanced.md) guide to learn about the advanced URL format.
|
||||
|
||||
### Format definition
|
||||
|
||||
@ -14,37 +14,37 @@ Check out the [example](#example) at the end of this guide.
|
||||
|
||||
#### Signature
|
||||
|
||||
Signature protects your URL from being changed by an attacker. It's highly recommended to sign imgproxy URLs in production.
|
||||
Signature protects your URL from being modified by an attacker. It is highly recommended to sign imgproxy URLs in a production environment.
|
||||
|
||||
If you set up [URL signature](./configuration.md#url-signature), check out [Signing the URL](./signing_the_url.md) guide to know how to sign your URLs. Otherwise, use any string here.
|
||||
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, use any string here.
|
||||
|
||||
#### Resizing types
|
||||
|
||||
imgproxy supports the following resizing types:
|
||||
|
||||
* `fit` — resizes the image while keeping aspect ratio to fit given size;
|
||||
* `fill` — resizes the image while keeping aspect ratio to fill given size and cropping projecting parts;
|
||||
* `crop` — crops the image to a given size.
|
||||
* `fit`: resizes the image while keeping aspect ratio to fit given size;
|
||||
* `fill`: resizes the image while keeping aspect ratio to fill given size and cropping projecting parts;
|
||||
* `crop`: crops the image to a given size.
|
||||
|
||||
#### Width and height
|
||||
|
||||
Width and height parameters define the size of the resulting image. Depending on the resizing type applied, the dimensions may differ from the requested ones.
|
||||
Width and height parameters define the size of the resulting image in pixels. Depending on the resizing type applied, the dimensions may differ from the requested ones.
|
||||
|
||||
#### Gravity
|
||||
|
||||
When imgproxy needs to cut some parts of the image, it is guided by the gravity. The following values are supported:
|
||||
|
||||
* `no` — north (top edge);
|
||||
* `so` — south (bottom edge);
|
||||
* `ea` — east (right edge);
|
||||
* `we` — west (left edge);
|
||||
* `ce` — center;
|
||||
* `sm` — smart. `libvips` detects the most "interesting" section of the image and considers it as the center of the resulting image;
|
||||
* `fp:%x:%y` - focus point. `x` and `y` are floating point numbers between 0 and 1 that describe coordinates of the center of the resulting image. Trait 0 and 1 as right/left for `x` and top/bottom for `y`.
|
||||
* `no`: north (top edge);
|
||||
* `so`: south (bottom edge);
|
||||
* `ea`: east (right edge);
|
||||
* `we`: west (left edge);
|
||||
* `ce`: center;
|
||||
* `sm`: smart. `libvips` detects the most "interesting" section of the image and considers it as the center of the resulting image;
|
||||
* `fp:%x:%y` - focus point. `x` and `y` are floating point numbers between 0 and 1 that describe the coordinates of the center of the resulting image. Treat 0 and 1 as right/left for `x` and top/bottom for `y`.
|
||||
|
||||
#### Enlarge
|
||||
|
||||
If set to `0`, imgproxy will not enlarge the image if it is smaller than the given size. With any other value, imgproxy will enlarge the image.
|
||||
When set to `0`, imgproxy will not enlarge the image if it is smaller than the given size. With any other value, imgproxy will enlarge the image.
|
||||
|
||||
#### Encoded URL
|
||||
|
||||
@ -52,13 +52,13 @@ The source URL should be encoded with URL-safe Base64. The encoded URL can be sp
|
||||
|
||||
#### Extension
|
||||
|
||||
Extension specifies the format of the resulting image. At the moment, imgproxy supports only `jpg`, `png` and `webp`, them being the most popular and useful web image formats.
|
||||
Extension specifies the format of the resulting image. At the moment, imgproxy supports only `jpg`, `png` and `webp`, them being the most popular and useful image formats on the Web.
|
||||
|
||||
The extension part can be omitted. In this case, imgproxy will use `jpg` by default. You also can [enable WebP support detection](./configuration.md#webp-support-detection) to use it as default resulting format when possible.
|
||||
|
||||
### Example
|
||||
|
||||
Signed imgproxy URL that resizes `http://example.com/images/curiosity.jpg` to fill `300x400` area with smart gravity without enlarging, and converts the image to `png` will look like this:
|
||||
Signed imgproxy URL that resizes `http://example.com/images/curiosity.jpg` to fill `300x400` area with smart gravity without enlarging, and converts the image to `png`:
|
||||
|
||||
```
|
||||
http://imgproxy.example.com/AfrOrF3gWeDA6VOlDG4TzxMv39O7MXnF4CXpKUwGqRM/fill/300/400/sm/0/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png
|
||||
|
||||
@ -1,3 +1,7 @@
|
||||
# Health check
|
||||
|
||||
There is a special endpoint `/health`, which returns HTTP Status `200 OK` after the server successfully starts. This can be used for readiness/liveness probe in your containers system such as Kubernetes.
|
||||
imgproxy comes with a built-in health check HTTP endpoint at `/health`.
|
||||
|
||||
`GET /health` returns HTTP Status `200 OK` if the server is started successfully.
|
||||
|
||||
You can use this for readiness/liveness probe in when deploying with a container orchestration system such as Kubernetes.
|
||||
|
||||
@ -11,7 +11,7 @@ $ docker pull darthsim/imgproxy:latest
|
||||
$ docker run -p 8080:8080 -it darthsim/imgproxy
|
||||
```
|
||||
|
||||
You can also build you own image. imgproxy is ready to be dockerized, plug and play:
|
||||
You can also build your own image. imgproxy is ready to be dockerized, plug and play:
|
||||
|
||||
```bash
|
||||
$ docker build -t imgproxy .
|
||||
@ -20,7 +20,7 @@ $ docker run -p 8080:8080 -it imgproxy
|
||||
|
||||
### Heroku
|
||||
|
||||
imgproxy can be deployed to Heroku with the click of the button:
|
||||
imgproxy can be deployed to Heroku with a click of a button:
|
||||
|
||||
[](https://heroku.com/deploy)
|
||||
|
||||
@ -61,4 +61,3 @@ $ git push heroku master
|
||||
```bash
|
||||
$ go get -f -u github.com/DarthSim/imgproxy
|
||||
```
|
||||
|
||||
|
||||
@ -1,23 +1,23 @@
|
||||
# Presets
|
||||
|
||||
Preset is named set of processing options. Presets can be used in [advanced URL format](./generating_the_url_advanced.md#preset) to get shorter and more readable URLs.
|
||||
imgproxy preset is a named set of processing options. Presets can be used in [advanced URL format](./generating_the_url_advanced.md#preset) to get shorter and somewhat readable URLs.
|
||||
|
||||
### Presets definition
|
||||
|
||||
Preset definition looks like this:
|
||||
The preset definition looks like this:
|
||||
|
||||
```
|
||||
%preset_name=%processing_options
|
||||
```
|
||||
|
||||
Processing options should be defined the same way as you define them in the [advanced URL format](./generating_the_url_advanced.md#preset). For example, preset named `awesome` that sets the resizing type to `fill` and resulting format to `jpg` will look like this:
|
||||
Processing options should be defined in the same way as you define them in the [advanced URL format](./generating_the_url_advanced.md#preset). For example, here is a preset named `awesome` that sets the resizing type to `fill` and resulting format to `jpg`:
|
||||
|
||||
```
|
||||
awesome=resizing_type:fill/format:jpg
|
||||
```
|
||||
|
||||
Read how to specify your presets to imgproxy in [Configuration](./configuration.md) guide.
|
||||
Read how to specify your presets with imgproxy in the [Configuration](./configuration.md) guide.
|
||||
|
||||
### Default preset
|
||||
|
||||
Preset named `default` will be applied to each image. This is useful when you want your default processing options to be different from imgproxy default ones.
|
||||
A preset named `default` will be applied to each image. Useful in case you want your default processing options to be different from the imgproxy default ones.
|
||||
|
||||
@ -1,18 +1,18 @@
|
||||
# Serving files from S3
|
||||
|
||||
imgproxy can process files from S3 buckets. To use this feature do the following:
|
||||
imgproxy can process images from S3 buckets. To use this feature, do the following:
|
||||
|
||||
1. Set `IMGPROXY_USE_S3` environment variable as `true`;
|
||||
2. [Setup credentials](#setup-credentials) to grant access to your bucket;
|
||||
3. Use `s3://%bucket_name/%file_key` as the source image url.
|
||||
3. Use `s3://%bucket_name/%file_key` as the source image URL.
|
||||
|
||||
### Setup credentials
|
||||
|
||||
There are three ways to specify your AWS credentials. The credentials need to be able to read from any of the buckets given in the source URLs.
|
||||
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.
|
||||
|
||||
#### Environment variables
|
||||
|
||||
You can specify AWS Acces Key ID and Secret Access Key by setting `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables.
|
||||
You can specify AWS Acces Key ID and 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
|
||||
@ -21,11 +21,11 @@ $ AWS_ACCESS_KEY_ID=my_access_key AWS_SECRET_ACCESS_KEY=my_secret_key imgproxy
|
||||
docker run -e AWS_ACCESS_KEY_ID=my_access_key -e AWS_SECRET_ACCESS_KEY=my_secret_key -it darthsim/imgproxy
|
||||
```
|
||||
|
||||
It's recommended to use this way when you run dockerized imgproxy.
|
||||
It is the recommended way to use with dockerized imgproxy.
|
||||
|
||||
#### Shared credentials file
|
||||
|
||||
Create `.aws/credentials` file in your home directory with the following content:
|
||||
Otherwise, you can create the `.aws/credentials` file in your home directory with the following content:
|
||||
|
||||
```ini
|
||||
[default]
|
||||
@ -35,6 +35,6 @@ aws_secret_access_key = %secret_access_key
|
||||
|
||||
#### IAM Roles for Amazon EC2 Instances
|
||||
|
||||
If you are running imgproxy on an Amazon EC2 instance, you can use the instance's [IAM role](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) to get security credentials to make calls to AWS.
|
||||
If you are running imgproxy on an Amazon EC2 instance, you can use the instance's [IAM role](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) to get security credentials to make calls to AWS S3.
|
||||
|
||||
You can get more info about credentials in the [Configuring the AWS SDK for Go](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html) guide.
|
||||
You can learn about credentials in the [Configuring the AWS SDK for Go](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html) guide.
|
||||
|
||||
@ -1,19 +1,19 @@
|
||||
# Serving local files
|
||||
|
||||
imgproxy can process files from your local filesystem. To use this feature do the following:
|
||||
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 images directory path.
|
||||
2. Use `local:///path/to/image.jpg` as the source image url.
|
||||
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 image that stored on your disc at `/path/to/project/images/logos/evil_martians.png`. Run imgproxy with `IMGPROXY_LOCAL_FILESYSTEM_ROOT` set to your images directory:
|
||||
Assume you want to process an image that 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 path inside this directory as source url:
|
||||
Then use path inside this directory as the source URL:
|
||||
|
||||
```
|
||||
local:///logos/evil_martians.png
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
# Signing the URL
|
||||
|
||||
imgproxy allows you to sign your URLs with key and salt, so an attacker won't be able to cause a denial-of-service attack by requesting multiple image resizes.
|
||||
imgproxy allows you to sign your URLs with key and salt, so an attacker won't be able to cause a denial-of-service attack by requesting multiple different image resizes.
|
||||
|
||||
### Configuring URL signature
|
||||
|
||||
URL signature checking is disabled by default, but it's highly recommended to enable it in production. To do so, define key/salt pair by setting the environment variables:
|
||||
URL signature checking is disabled by default, but it is highly recommended to enable it in a production environment. To do so, the define key/salt pair by setting the following environment variables:
|
||||
|
||||
* `IMGPROXY_KEY` — hex-encoded key;
|
||||
* `IMGPROXY_SALT` — hex-encoded salt;
|
||||
* `IMGPROXY_KEY`: hex-encoded key;
|
||||
* `IMGPROXY_SALT`: hex-encoded salt;
|
||||
|
||||
Read our [Configuration](./configuration.md#url-signature) guide to find more ways to set key and salt.
|
||||
|
||||
@ -19,18 +19,20 @@ $ echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n')
|
||||
|
||||
### Calculating URL signature
|
||||
|
||||
Signature is a URL-safe Base64-encoded HMAC digest of the rest of the path including the leading `/`. Here's how it is calculated:
|
||||
Signature is an URL-safe Base64-encoded HMAC digest of the rest of the path, including the leading `/`. Here is how it is calculated:
|
||||
|
||||
* Take the path after the signature:
|
||||
* For [basic URL format](./generating_the_url_basic.md) - `/%resizing_type/%width/%height/%gravity/%enlarge/%encoded_url.%extension`;
|
||||
* For [advanced URL format](./generating_the_url_advanced.md) - `/%processing_options/%encoded_url.%extension`;
|
||||
* Take the path part after the signature:
|
||||
* For [basic URL format](./generating_the_url_basic.md): `/%resizing_type/%width/%height/%gravity/%enlarge/%encoded_url.%extension`;
|
||||
* For [advanced URL format](./generating_the_url_advanced.md): `/%processing_options/%encoded_url.%extension`;
|
||||
* Add 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 the [examples](../examples) folder. And here is a step-by-step example of calculating URL signature:
|
||||
**You can find helpful code snippets in various programming languages the [examples](../examples) folder. There is a good chance you will find a snippet in your favorite programming language that you can use right away.**
|
||||
|
||||
And here is a step-by-step example of calculating the URL signature:
|
||||
|
||||
Assume that you have the following unsigned URL:
|
||||
|
||||
@ -38,13 +40,13 @@ Assume that you have the following unsigned URL:
|
||||
http://imgproxy.example.com/insecure/fill/300/400/sm/0/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` that will be `736563726574` and `68656C6C6F` in hex encoding. This key/salt pair is obviously weak for production but ok for this example. Run your imgproxy using this key and salt:
|
||||
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` — that translates to `736563726574` and `68656C6C6F` in hex encoding. This key/salt pair is quite weak for production use but will do for this example. Run your imgproxy using this key/salt pair:
|
||||
|
||||
```bash
|
||||
$ IMGPROXY_KEY=736563726574 IMGPROXY_SALT=68656C6C6F imgproxy
|
||||
```
|
||||
|
||||
Note that your unsigned URL will stop work because imgproxy now checks signatures of all URLs.
|
||||
Note that all your unsigned URL will stop working since imgproxy now checks signatures of all URLs.
|
||||
|
||||
First, you need to take the path after the signature and add the salt to the beginning:
|
||||
|
||||
@ -64,4 +66,4 @@ And finally put the signature to your URL:
|
||||
http://imgproxy.example.com/AfrOrF3gWeDA6VOlDG4TzxMv39O7MXnF4CXpKUwGqRM/fill/300/400/sm/0/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png
|
||||
```
|
||||
|
||||
Now you got the URL that you can use to securely resize the image.
|
||||
Now you got the URL that you can use to resize the image securely.
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
# Source image formats support
|
||||
|
||||
imgproxy supports only the most popular image formats of the moment: PNG, JPEG, GIF and WebP.
|
||||
At the moment, imgproxy supports only the most popular Web image formats:
|
||||
|
||||
* PNG;
|
||||
* JPEG;
|
||||
* GIF;
|
||||
* WebP.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user