Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@DarthSim
DarthSim committed Oct 8, 2018
1 parent 7b9a32d commit 1851da0
Show file tree
Hide file tree
Showing 12 changed files with 148 additions and 139 deletions.
12 changes: 6 additions & 6 deletions docs/GETTING_STARTED.md
View file
@@ -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
Expand All @@ -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.
24 changes: 12 additions & 12 deletions docs/about_processing_pipeline.md
View file
@@ -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.
80 changes: 40 additions & 40 deletions docs/configuration.md
View file
Expand Up @@ -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):

Expand All @@ -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
Expand All @@ -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.

0 comments on commit 1851da0

Please sign in to comment.