Docs

README.md

@@ -47,211 +47,39 @@ Massive processing of remote images is a potentially dangerous thing, security-w
 
 * imgproxy supports authorization by an HTTP header. That prevents using imgproxy directly by an attacker but allows to use it through a CDN or a caching server — just by adding a header to a proxy or CDN config.
 
-## Installation
-
-There are two ways you can install imgproxy:
-
-#### From the source
-
-1. First, install [libvips](https://github.com/jcupitt/libvips).
-
-  ```bash
-  # macOS
-  $ brew tap homebrew/science
-  $ brew install vips
-
-  # Ubuntu
-  # Ubuntu apt repository contains a pretty old version of libvips.
-  # It's recommended to use PPA with an up to date version.
-  $ sudo add-apt-repository ppa:dhor/myway
-  $ sudo apt-get install libvips-dev
-  ```
-
-  **Note:** Most libvips packages come with WebP support. If you want libvips to support WebP on macOS, you need to install it this way:
-
-  ```bash
-  $ brew tap homebrew/science
-  $ brew install vips --with-webp
-  ```
-
-2. Next, install imgproxy itself:
-
-  ```bash
-  $ go get -f -u github.com/DarthSim/imgproxy
-  ```
-
-#### Docker
-
-imgproxy can (and should) be used as a standalone application inside a Docker container. It is ready to be dockerized, plug and play:
-
-```bash
-$ docker build -t imgproxy .
-$ docker run -e IMGPROXY_KEY=$YOUR_KEY -e IMGPROXY_SALT=$YOUR_SALT -p 8080:8080 -t imgproxy
-```
-
-You can also pull the image from Docker Hub:
-
-```bash
-$ docker pull darthsim/imgproxy:latest
-$ docker run -e IMGPROXY_KEY=$YOUR_KEY -e IMGPROXY_SALT=$YOUR_SALT -p 8080:8080 -t darthsim/imgproxy
-```
-
-#### Heroku
-
-imgproxy can be deployed to Heroku with the click of the button:
-
-[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)
-
-However, you can do it manually with a few steps:
-
-```bash
-$ git clone https://github.com/DarthSim/imgproxy.git && cd imgproxy
-$ heroku create your-application
-$ heroku buildpacks:add https://github.com/heroku/heroku-buildpack-apt
-$ heroku buildpacks:add https://github.com/heroku/heroku-buildpack-go
-$ heroku config:set IMGPROXY_KEY=$YOUR_KEY IMGPROXY_SALT=$YOUR_SALT
-$ git push heroku master
-```
-
-## Configuration
-
-imgproxy is [Twelve-Factor-App](https://12factor.net/)-ready and can be configured using `ENV` variables.
-
-#### URL signature
-
-imgproxy requires all URLs to be signed with a key and 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):
-
-```bash
-$ imgproxy -keypath /path/to/file/with/key -saltpath /path/to/file/with/salt
-```
-
-If you need a random key/salt pair real fast, you can quickly generate it using, for example, the following snippet:
-
-```bash
-$ 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_LOCAL_FILESYSTEM_ROOT` — root of the local filesystem. See [Serving local files](#serving-local-files). Keep empty to disable serving of local files.
-
-#### 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`;
-
-You can also specify a secret to enable authorization with the HTTP `Authorization` header:
-
-* `IMGPROXY_SECRET` — the authorization token. If specified, request should contain the `Authorization: Bearer %secret%` header;
-
-imgproxy doesn't send CORS headers by default. To enable CORS headers, specify allowed origin:
-
-* `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:
-
-* `IMGPROXY_IGNORE_SSL_VERIFICATION` - when true, disables SSL verification, so imgproxy can be used in development 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;
-
-#### Miscellaneous
-
-* `IMGPROXY_BASE_URL` - base URL part which will be added to every requestsd 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.
-
-## Generating the URL
-
-The URL should contain the signature and resize parameters, like this:
-
-```
-/%signature/%resizing_type/%width/%height/%gravity/%enlarge/%encoded_url.%extension
-```
-
-#### 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.
-
-#### 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.
-
-#### 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.
-
-#### 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.
-
-#### Encoded URL
-
-The source URL should be encoded with URL-safe Base64. The encoded URL can be split with `/` for your needs.
-
-#### 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.
-
-#### 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:
-
-* Take the path after the signature — `/%resizing_type/%width/%height/%gravity/%enlarge/%encoded_url.%extension`;
-* Add salt to the beginning;
-* Calculate the HMAC digest using SHA256;
-* Encode the result with URL-safe Base64.
-
-You can find helpful code snippets in the `examples` folder.
-
-## Serving local files
-
-imgproxy can process files from your local filesystem. To use this feature do the following:
-
-1. Set `IMGPROXY_LOCAL_FILESYSTEM_ROOT` to your images directory path.
-2. Use `local:///path/to/image.jpg` as the source image url.
-
-## Source image formats support
-
-imgproxy supports only the most popular image formats of the moment: PNG, JPEG, GIF and WebP.
-
-## Deployment
-
-There is a special endpoint `/health`, which returns HTTP Status `200 OK` after server successfully starts. This can be used to check container readiness.
+## Documentation
+
+1. [Getting started](./docs/GETTING_STARTED.md)
+2. [Installation](./docs/installation.md)
+   * [Docker](./docs/installation.md#docker)
+   * [Heroku](./docs/installation.md#heroku)
+   * [From the source](./docs/installation.md#from-the-source)
+3. [Configuration](./docs/configuration.md)
+   * [URL signature](./docs/configuration.md#url-signature)
+   * [Server](./docs/configuration.md#server)
+   * [Security](./docs/configuration.md#security)
+   * [Compression](./docs/configuration.md#compression)
+   * [WebP support detection](./docs/configuration.md#webp-support-detection)
+   * [Presets](./docs/configuration.md#presets)
+   * [Serving local files](./docs/configuration.md#serving-local-files)
+   * [Miscellaneous](./docs/configuration.md#miscellaneous)
+4. [Generating the URL](./docs/generating_the_url_basic.md)
+   * [Basic](./docs/generating_the_url_basic.md)
+   * [Advanced](./docs/generating_the_url_advanced.md)
+   * [Signing the URL](./docs/signing_the_url.md)
+5. [Presets](./docs/presets.md)
+6. [Serving local files](./docs/serving_local_files.md)
+7. [Source image formats support](./docs/source_image_formats_support.md)
+8. [About processing pipeline](./docs/about_processing_pipeline.md)
+9. [Health check](./docs/healthcheck.md)
 
 ## Author
 
-Sergey "DarthSim" Aleksandrovich
+Sergey "DarthSim" Alexandrovich
+
+Many thanks to [Roman Shamin](https://github.com/romashamin) for the awesome logo.
 
-Many thanks to @romashamin for the awesome logo.
+Great bunch of kudos goes to [John Cupitt](https://github.com/jcupitt) who develops [libvips](https://github.com/libvips/libvips) and helps me to optimize its usage under the hood of imgproxy.
 
 ## License
 

docs/GETTING_STARTED.md

@@ -0,0 +1,33 @@
+# Getting started
+
+This guide will show you how to quickly get you first image resized with imgproxy.
+
+## Install
+
+Let's assume you have Docker installed on your machine. Then you can just pull official imgproxy 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.
+
+[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)
+
+Check out our [installation guide](../docs/installation.md) for more details and instructions.
+
+That's it! No further configuration is needed, but if you want to unleash the full power of imgproxy, read our [configuration guide](../docs/configuration.md).
+
+## 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):
+[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.
+
+Get more info about generation imgproxy URLs in the [Generating the URL](../docs/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](../docs/signing_the_url.md) guide to know how to secure your imgproxy from attackers.

docs/about_processing_pipeline.md

@@ -0,0 +1,15 @@
+# About 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:
+
+* 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.
+
+This pipeline with using a sequential access to source image data allows to highly reduce memory and CPU usage, that makes imgproxy so awesome.

docs/configuration.md

@@ -0,0 +1,110 @@
+# 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 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_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):
+
+```bash
+$ imgproxy -keypath /path/to/file/with/key -saltpath /path/to/file/with/salt
+```
+
+If you need a random key/salt pair real fast, you can quickly generate it using, for example, the following snippet:
+
+```bash
+$ 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;
+
+### 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`;
+
+You can also specify a secret to enable authorization with the HTTP `Authorization` header:
+
+* `IMGPROXY_SECRET` — the authorization token. If specified, a request should contain the `Authorization: Bearer %secret%` header;
+
+imgproxy doesn't 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.
+
+When you use imgproxy in development, it would 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.
+
+### 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;
+
+## 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_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.
+
+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.
+
+### Presets
+
+Read about presets in the [Presets](../docs/presets.md) guide.
+
+There are two ways to define presets:
+
+##### Using 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.
+
+##### Using 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:
+
+```
+default=resize_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
+```
+
+### 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 empty to disable serving of local files.
+
+Check out [Serving local files](../docs/serving_local_files.md) guide to get more info.
+
+### 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.
+

docs/generating_the_url_advanced.md

@@ -0,0 +1,182 @@
+# Generating the URL (Advanced)
+
+This guide describes the advanced URL format that supports all the imgproxy features. Read our [Generating the URL (Basic)](../docs/generating_the_url_basic.md) guide to get info about basic URL format that is compatible with the first version of imgproxy.
+
+### Format definition
+
+The advanced URL should contain the signature, processing options, and encoded source URL, like this:
+
+```
+/%signature/%processing_options/%encoded_url.%extension
+```
+
+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.
+
+If you set up [URL signature](../docs/configuration.md#url-signature), check out [Signing the URL](../docs/signing_the_url.md) guide to know how to sign your URLs. Otherwise, use any string here.
+
+#### Processing options
+
+Processing options should be specified as URL parts divided by slashes (`/`). Processing option has the following format:
+
+```
+%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](../docs/about_processing_pipeline.md) guide.
+
+imgproxy supports the following processing options:
+
+##### Resize
+
+`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.
+
+##### 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.
+
+##### 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 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`
+
+##### Width
+
+`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.
+
+Default: `0`
+
+##### Height
+
+`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.
+
+Default: `0`
+
+##### Enlarge
+
+`enlarge:%enlarge`
+`el:%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.
+
+Default: `0`
+
+##### Gravity
+
+`gravity:%gravity`
+`g:%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 defines coordinates of the center of the resulting image. Trait 0 and 1 as right/left for `x` and top/bottom for `y`.
+
+Default: `ce`
+
+##### 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 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 no arguments is provided, disables background.
+
+Default: disabled
+
+##### Blur
+
+`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.
+
+Default: disabled
+
+##### Sharpen
+
+`sharpen:%sigma`
+`sh:%sigma`
+
+When set, imgproxy will apply sharpen filter to the resulting image. `sigma` defines how large 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).
+
+Default: disabled
+
+##### Preset
+
+`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.
+
+Read more about presets in our [Presets](../docs/presets.md) guide.
+
+Default: empty
+
+##### Format
+
+`format:%extension`
+`f:%extension`
+`ext:%extension`
+
+Specifies resulting image format. Alias for [extension](#extension) URL part.
+
+Default: `jpg`
+
+#### Encoded URL
+
+The source URL should be encoded with URL-safe Base64. The encoded URL can be split with `/` for your needs.
+
+#### 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.
+
+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](../docs/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:
+
+```
+http://imgproxy.example.com/AfrOrF3gWeDA6VOlDG4TzxMv39O7MXnF4CXpKUwGqRM/preset:sharp/resize:fill:300:400:0/gravity:sm/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png
+```
+
+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
+```

docs/generating_the_url_basic.md

@@ -0,0 +1,65 @@
+# 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)](../docs/generating_the_url_advanced.md) guide to get info about advanced URL format.
+
+### Format definition
+
+The basic URL should contain the signature, resize parameters, and encoded source URL, like this:
+
+```
+/%signature/%resizing_type/%width/%height/%gravity/%enlarge/%encoded_url.%extension
+```
+
+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.
+
+If you set up [URL signature](../docs/configuration.md#url-signature), check out [Signing the URL](../docs/signing_the_url.md) guide to know 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.
+
+#### 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.
+
+#### 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`.
+
+#### 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.
+
+#### Encoded URL
+
+The source URL should be encoded with URL-safe Base64. The encoded URL can be split with `/` for your needs.
+
+#### 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.
+
+The extension part can be omitted. In this case, imgproxy will use `jpg` by default. You also can [enable WebP support detection](../docs/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:
+
+```
+http://imgproxy.example.com/AfrOrF3gWeDA6VOlDG4TzxMv39O7MXnF4CXpKUwGqRM/fill/300/400/sm/0/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png
+```

docs/healthcheck.md

@@ -0,0 +1,3 @@
+# 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.

docs/installation.md

@@ -0,0 +1,64 @@
+# Installation
+
+There are three ways you can install imgproxy:
+
+### Docker
+
+imgproxy can (and should) 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 you own image. imgproxy is ready to be dockerized, plug and play:
+
+```bash
+$ docker build -t imgproxy .
+$ docker run -p 8080:8080 -it imgproxy
+```
+
+### Heroku
+
+imgproxy can be deployed to Heroku with the click of the button:
+
+[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)
+
+However, you can do it manually with a few steps:
+
+```bash
+$ git clone https://github.com/DarthSim/imgproxy.git && cd imgproxy
+$ heroku create your-application
+$ heroku stack:set container
+$ git push heroku master
+```
+
+### From the source
+
+1. First, install [libvips](https://github.com/libvips/libvips).
+
+  ```bash
+  # macOS
+  $ brew tap homebrew/science
+  $ brew install vips
+
+  # Ubuntu
+  # Ubuntu apt repository contains a pretty old version of libvips.
+  # It's recommended to use PPA with an up to date version.
+  $ sudo add-apt-repository ppa:dhor/myway
+  $ sudo apt-get install libvips-dev
+  ```
+
+  **Note:** Most libvips packages come with WebP support. If you want libvips to support WebP on macOS, you need to install it this way:
+
+  ```bash
+  $ brew tap homebrew/science
+  $ brew install vips --with-webp
+  ```
+
+2. Next, install imgproxy itself:
+
+  ```bash
+  $ go get -f -u github.com/DarthSim/imgproxy
+  ```
+

docs/presets.md

@@ -0,0 +1,23 @@
+# Presets
+
+Preset is named set of processing options. Presets can be used in [advanced URL format](../docs/generating_the_url_advanced.md#preset) to get shorter and more readable URLs.
+
+### Presets definition
+
+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](../docs/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:
+
+```
+awesome=resizing_type:fill/format:jpg
+```
+
+Read how to specify your presets to imgproxy in [Configuration](../docs/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.

docs/serving_local_files.md

@@ -0,0 +1,26 @@
+# Serving local files
+
+imgproxy can 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.
+
+### 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:
+
+```bash
+$ IMGPROXY_LOCAL_FILESYSTEM_ROOT=/path/to/project/images imgproxy
+```
+
+Then use path inside this directory as 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/fit/300/200/no/0/bG9jYWw6Ly8vbG9n/b3MvZXZpbF9tYXJ0/aWFucy5wbmc.jpg
+```

docs/signing_the_url.md

@@ -0,0 +1,67 @@
+# 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.
+
+### 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:
+
+* `IMGPROXY_KEY` — hex-encoded key;
+* `IMGPROXY_SALT` — hex-encoded salt;
+
+Read our [Configuration](../docs/configuration.md#url-signature) guide to find more ways to set key and salt.
+
+If you need a random key/salt pair real fast, you can quickly generate it using, for example, the following snippet:
+
+```bash
+$ 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:
+
+* Take the path after the signature:
+  * For [basic URL format](../docs/generating_the_url_basic.md) - `/%resizing_type/%width/%height/%gravity/%enlarge/%encoded_url.%extension`;
+  * For [advanced URL format](../docs/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:
+
+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:
+
+```bash
+$ IMGPROXY_KEY=736563726574 IMGPROXY_SALT=68656C6C6F imgproxy
+```
+
+Note that your unsigned URL will stop work because imgproxy now checks signatures of all URLs.
+
+First, you need to take the path after the signature and add the salt to the beginning:
+
+```
+hello/fill/300/400/sm/0/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png
+```
+
+Then calculate the HMAC digest of this string using SHA256 and encode it with URL-safe Base64:
+
+```
+AfrOrF3gWeDA6VOlDG4TzxMv39O7MXnF4CXpKUwGqRM
+```
+
+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.

docs/source_image_formats_support.md

@@ -0,0 +1,3 @@
+# Source image formats support
+
+imgproxy supports only the most popular image formats of the moment: PNG, JPEG, GIF and WebP.