go/imgproxy
1
0
Fork 0
mirror of https://github.com/imgproxy/imgproxy.git synced 2024-11-24 08:12:38 +02:00
Code Releases Activity

Docs

Browse Source
This commit is contained in:
DarthSim 2018-10-04 18:59:57 +06:00
parent 9ca64ce25a
commit 25712e5d71
12 changed files with 620 additions and 201 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

230
README.md
View File

@ -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 @romashamin for the awesome logo.
Many thanks to [Roman Shamin](https://github.com/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

33
docs/GETTING_STARTED.md Normal file
View File

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

15
docs/about_processing_pipeline.md Normal file
View File

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

110
docs/configuration.md Normal file
View File

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

182
docs/generating_the_url_advanced.md Normal file
View File

@ -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
```

65
docs/generating_the_url_basic.md Normal file
View File

@ -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
```

3
docs/healthcheck.md Normal file
View File

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

64
docs/installation.md Normal file
View File

@ -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
```

23
docs/presets.md Normal file
View File

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

26
docs/serving_local_files.md Normal file
View File

@ -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
```

67
docs/signing_the_url.md Normal file
View File

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

3
docs/source_image_formats_support.md Normal file
View File

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