mirror of
https://github.com/imgproxy/imgproxy.git
synced 2025-02-02 11:34:20 +02:00
Docs site with docsify
This commit is contained in:
DarthSim
parent
33cc10ba31
commit
5da21a9c43
0
docs/.nojekyll
Normal file
0
docs/.nojekyll
Normal file
@ -15,9 +15,9 @@ If you don't have docker, you can use Heroku for a quick start.
|
||||
|
||||
[](https://heroku.com/deploy?template=https://github.com/DarthSim/imgproxy)
|
||||
|
||||
Check out our [installation guide](./installation.md) for more details and instructions.
|
||||
Check out our [installation guide](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](./configuration.md).
|
||||
That's it! No further configuration is needed, but if you want to unleash the full power of imgproxy, read our [configuration guide](configuration.md).
|
||||
|
||||
## Resize an image
|
||||
|
||||
@ -26,8 +26,8 @@ After you've successfully installed imgproxy, you might want to see if it is wor
|
||||
|
||||
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.
|
||||
|
||||
Learn more on how to generate 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 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.
|
||||
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.
|
||||
|
||||
58
docs/README.md
Normal file
58
docs/README.md
Normal file
@ -0,0 +1,58 @@
|
||||
# imgproxy
|
||||
|
||||
imgproxy is a fast and secure standalone server for resizing and converting remote images. The main principles of imgproxy are simplicity, speed, and security.
|
||||
|
||||
imgproxy can be used to provide a fast and secure way to replace all the image resizing code of your web application (like calling ImageMagick or GraphicsMagick, or using libraries), while also being able to resize everything on the fly, fast and easy. imgproxy is also indispensable when handling lots of image resizing, especially when images come from a remote source.
|
||||
|
||||
imgproxy does one thing — resizing remote images — and does it well. It works great when you need to resize multiple images on the fly to make them match your application design without preparing a ton of cached resized images or re-doing it every time the design changes.
|
||||
|
||||
imgproxy is a Go application, ready to be installed and used in any Unix environment — also ready to be containerized using Docker.
|
||||
|
||||
See this article for a good intro and all the juicy details! [imgproxy:
|
||||
Resize your images instantly and securely](https://evilmartians.com/chronicles/introducing-imgproxy)
|
||||
|
||||
<a href="https://evilmartians.com/?utm_source=imgproxy">
|
||||
<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54">
|
||||
</a>
|
||||
|
||||
#### Simplicity
|
||||
|
||||
> "No code is better than no code."
|
||||
|
||||
imgproxy only includes the must-have features for image processing, fine-tuning and security. Specifically,
|
||||
|
||||
* It would be great to be able to rotate, flip and apply masks to images, but in most of the cases, it is possible — and is much easier — to do that using CSS3.
|
||||
* It may be great to have built-in HTTP caching of some kind, but it is way better to use a Content-Delivery Network or a caching proxy server for this, as you will have to do this sooner or later in the production environment.
|
||||
* It might be useful to have everything built in — such as HTTPS support — but an easy way to solve that would be just to use a proxying HTTP server such as nginx.
|
||||
|
||||
#### Speed
|
||||
|
||||
imgproxy uses probably the most efficient image processing library there is, called `libvips`. It is screaming fast and has a very low memory footprint; with it, we can handle the processing for a massive amount of images on the fly.
|
||||
|
||||
imgproxy also uses native Go's `net/http` routing for the best HTTP networking support.
|
||||
|
||||
You can see benchmarking results and comparison with some well-known alternatives in our [benchmark report](https://github.com/imgproxy/imgproxy/blob/master/BENCHMARK.md).
|
||||
|
||||
#### Security
|
||||
|
||||
Massive processing of remote images is a potentially dangerous thing, security-wise. There are many attack vectors, so it is a good idea to consider attack prevention measures first. Here is how imgproxy can help:
|
||||
|
||||
* imgproxy checks image type _and_ "real" dimensions when downloading, so the image will not be fully downloaded if it has an unknown format or the dimensions are too big (there is a setting for that). That is how imgproxy protects you from so called "image bombs" like those described at https://www.bamsoftware.com/hacks/deflate.html.
|
||||
|
||||
* imgproxy protects image URLs with a signature, so an attacker cannot cause a denial-of-service attack by requesting multiple image resizes.
|
||||
|
||||
* 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.
|
||||
|
||||
## Author
|
||||
|
||||
Sergey "DarthSim" Alexandrovich
|
||||
|
||||
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
|
||||
|
||||
imgproxy is licensed under the MIT license.
|
||||
|
||||
See [LICENSE](https://github.com/imgproxy/imgproxy/blob/master/LICENSE.md) for the full license text.
|
||||
17
docs/_sidebar.md
Normal file
17
docs/_sidebar.md
Normal file
@ -0,0 +1,17 @@
|
||||
* [Getting started](GETTING_STARTED)
|
||||
* [Installation](installation)
|
||||
* [Configuration](configuration)
|
||||
* [Generating the URL (Basic)](generating_the_url_basic)
|
||||
* [Generating the URL (Advanced)](generating_the_url_advanced)
|
||||
* [Signing the URL](signing_the_url)
|
||||
* [Watermark](watermark)
|
||||
* [Presets](presets)
|
||||
* [Serving local files](serving_local_files)
|
||||
* [Serving files from Amazon S3](serving_files_from_s3)
|
||||
* [Serving files from Google Cloud Storage](serving_files_from_google_cloud_storage)
|
||||
* [New Relic](new_relic)
|
||||
* [Prometheus](prometheus)
|
||||
* [Image formats support](image_formats_support)
|
||||
* [About processing pipeline](about_processing_pipeline)
|
||||
* [Health check](healthcheck)
|
||||
* [Memory usage tweaks](memory_usage_tweaks)
|
||||
1
docs/assets/pattern.svg
Normal file
1
docs/assets/pattern.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg height="47" viewBox="0 0 47 47" width="47" xmlns="http://www.w3.org/2000/svg"><path d="m23 23v-3h1v3h3v1h-3v3h-1v-3h-3v-1z" fill="#56575b" fill-rule="evenodd"/></svg>
|
||||
|
After Width: | Height: | Size: 171 B |
60
docs/assets/style.css
Normal file
60
docs/assets/style.css
Normal file
@ -0,0 +1,60 @@
|
||||
@import url('https://fonts.googleapis.com/css?family=Roboto&display=swap');
|
||||
|
||||
:root {
|
||||
--mono-hue: var(--theme-hue);
|
||||
--mono-saturation: 10%;
|
||||
|
||||
--mono-shade4: hsl(var(--mono-hue), var(--mono-saturation), 10%);
|
||||
|
||||
--theme-hue : 208;
|
||||
--theme-saturation: 80.3%;
|
||||
--theme-lightness : 45.9%;
|
||||
|
||||
--base-background-color: rgb(13, 15, 21);
|
||||
--base-background-color-trans: rgba(13, 15, 21, 0);
|
||||
--base-font-family: "Roboto",sans-serif;
|
||||
|
||||
--code-inline-background: var(--mono-tint1);
|
||||
|
||||
--link-color: var(--theme-color);
|
||||
|
||||
--sidebar-background: var(--mono-shade4);
|
||||
--sidebar-border-color: hsla(0,0%,100%,.4);
|
||||
}
|
||||
|
||||
.content {
|
||||
background: linear-gradient(
|
||||
180deg,
|
||||
var(--base-background-color-trans),
|
||||
var(--base-background-color) 500px
|
||||
), url('/assets/pattern.svg');
|
||||
}
|
||||
|
||||
.loading {
|
||||
margin: 150px auto 0;
|
||||
position: relative;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.loading__spinner {
|
||||
--spinner-size: 50px;
|
||||
|
||||
box-sizing: border-box;
|
||||
width: var(--spinner-size);
|
||||
height: var(--spinner-size);
|
||||
margin: 0 auto;
|
||||
border: 1px solid rgba(255, 255, 255, 0.7);
|
||||
border-right-color: transparent;
|
||||
border-radius: 50%;
|
||||
animation: spinner 1s linear infinite;
|
||||
}
|
||||
|
||||
@keyframes spinner {
|
||||
0% {
|
||||
transform: rotate(0deg);
|
||||
}
|
||||
|
||||
100% {
|
||||
transform: rotate(360deg);
|
||||
}
|
||||
}
|
||||
2
docs/assets/theme.css
Normal file
2
docs/assets/theme.css
Normal file
File diff suppressed because one or more lines are too long
@ -2,7 +2,7 @@
|
||||
|
||||
imgproxy is [Twelve-Factor-App](https://12factor.net/)-ready and can be configured using `ENV` variables.
|
||||
|
||||
### URL signature
|
||||
## URL signature
|
||||
|
||||
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:
|
||||
|
||||
@ -24,7 +24,7 @@ If you need a random key/salt pair real fast, you can quickly generate it using,
|
||||
$ echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n')
|
||||
```
|
||||
|
||||
### Server
|
||||
## Server
|
||||
|
||||
* `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`;
|
||||
@ -38,7 +38,7 @@ $ echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n')
|
||||
* `IMGPROXY_USER_AGENT`: User-Agent header that will be sent with source image request. Default: `imgproxy/%current_version`;
|
||||
* `IMGPROXY_USE_ETAG`: when `true`, enables using [ETag](https://en.wikipedia.org/wiki/HTTP_ETag) HTTP header for HTTP cache control. Default: false;
|
||||
|
||||
### Security
|
||||
## Security
|
||||
|
||||
imgproxy protects you from so-called image bombs. Here is how you can specify maximum image resolution which you consider reasonable:
|
||||
|
||||
@ -67,7 +67,7 @@ Also you may want imgproxy to respond with the same error message that it writes
|
||||
|
||||
* `IMGPROXY_DEVELOPMENT_ERRORS_MODE`: when true, imgproxy will respond with detailed error messages. Not recommended for production because some errors may contain stack trace.
|
||||
|
||||
### Compression
|
||||
## Compression
|
||||
|
||||
* `IMGPROXY_QUALITY`: default quality of the resulting image, percentage. Default: `80`;
|
||||
* `IMGPROXY_GZIP_COMPRESSION`: GZip compression level. Default: `5`;
|
||||
@ -95,26 +95,26 @@ imgproxy can use the `Width`, `Viewport-Width` or `DPR` HTTP headers to determin
|
||||
|
||||
**Warning**: Headers cannot be signed. This means that an attacker can bypass your CDN cache by changing the `Width`, `Viewport-Width` or `DPR` HTTP headers. Have this in mind when configuring your production caching setup.
|
||||
|
||||
### Watermark
|
||||
## Watermark
|
||||
|
||||
* `IMGPROXY_WATERMARK_DATA`: Base64-encoded image data. You can easily calculate it with `base64 tmp/watermark.png | tr -d '\n'`;
|
||||
* `IMGPROXY_WATERMARK_PATH`: path to the locally stored image;
|
||||
* `IMGPROXY_WATERMARK_URL`: watermark image URL;
|
||||
* `IMGPROXY_WATERMARK_OPACITY`: watermark base opacity.
|
||||
|
||||
Read more about watermarks in the [Watermark](./watermark.md) guide.
|
||||
Read more about watermarks in the [Watermark](watermark.md) guide.
|
||||
|
||||
### Presets
|
||||
## Presets
|
||||
|
||||
Read about imgproxy 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 an environment variable
|
||||
#### Using an environment variable
|
||||
|
||||
* `IMGPROXY_PRESETS`: set of preset definitions, comma-divided. Example: `default=resizing_type:fill/enlarge:1,sharp=sharpen:0.7,blurry=blur:2`. Default: blank.
|
||||
|
||||
##### Using a command line argument
|
||||
#### Using a command line argument
|
||||
|
||||
```bash
|
||||
$ imgproxy -presets /path/to/file/with/presets
|
||||
@ -132,55 +132,55 @@ sharp=sharpen:0.7
|
||||
blurry=blur:2
|
||||
```
|
||||
|
||||
#### Using only presets
|
||||
### Using only presets
|
||||
|
||||
imgproxy can be switched into "presets-only mode". In this mode, imgproxy accepts only `preset` option arguments as processing options. Example: `http://imgproxy.example.com/unsafe/thumbnail:blurry:watermarked/plain/http://example.com/images/curiosity.jpg@png`
|
||||
|
||||
* `IMGPROXY_ONLY_PRESETS`: disable all URL formats and enable presets-only mode.
|
||||
|
||||
### Serving local files
|
||||
## 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 the [Serving local files](./serving_local_files.md) guide to learn more.
|
||||
Check out the [Serving local files](serving_local_files.md) guide to learn more.
|
||||
|
||||
### Serving files from Amazon S3
|
||||
## Serving files from Amazon S3
|
||||
|
||||
imgproxy can process files from Amazon S3 buckets, but this feature is disabled by default. To enable it, set `IMGPROXY_USE_S3` to `true`:
|
||||
|
||||
* `IMGPROXY_USE_S3`: when `true`, enables image fetching from Amazon S3 buckets. Default: false;
|
||||
* `IMGPROXY_S3_ENDPOINT`: custom S3 endpoint to being used by imgproxy.
|
||||
|
||||
Check out the [Serving files from S3](./serving_files_from_s3.md) guide to learn more.
|
||||
Check out the [Serving files from S3](serving_files_from_s3.md) guide to learn more.
|
||||
|
||||
### Serving files from Google Cloud Storage
|
||||
## Serving files from Google Cloud Storage
|
||||
|
||||
imgproxy can process files from Google Cloud Storage buckets, but this feature is disabled by default. To enable it, set `IMGPROXY_GCS_KEY` to the content of Google Cloud JSON key:
|
||||
|
||||
* `IMGPROXY_GCS_KEY`: Google Cloud JSON key. When set, enables image fetching from Google Cloud Storage buckets. Default: blank.
|
||||
|
||||
Check out the [Serving files from Google Cloud Storage](./serving_files_from_google_cloud_storage.md) guide to learn more.
|
||||
Check out the [Serving files from Google Cloud Storage](serving_files_from_google_cloud_storage.md) guide to learn more.
|
||||
|
||||
### New Relic metrics
|
||||
## New Relic metrics
|
||||
|
||||
imgproxy can send its metrics to New Relic. Specify your New Relic license key to activate this feature:
|
||||
|
||||
* `IMGPROXY_NEW_RELIC_KEY`: New Relic license key;
|
||||
* `IMGPROXY_NEW_RELIC_APP_NAME`: New Relic application name. Default: `imgproxy`.
|
||||
|
||||
Check out the [New Relic](./new_relic.md) guide to learn more.
|
||||
Check out the [New Relic](new_relic.md) guide to learn more.
|
||||
|
||||
### Prometheus metrics
|
||||
## Prometheus metrics
|
||||
|
||||
imgproxy can collect its metrics for Prometheus. Specify binding for Prometheus metrics server to activate this feature:
|
||||
|
||||
* `IMGPROXY_PROMETHEUS_BIND`: Prometheus metrics server binding. Can't be the same as `IMGPROXY_BIND`. Default: blank.
|
||||
|
||||
Check out the [Prometheus](./prometheus.md) guide to learn more.
|
||||
Check out the [Prometheus](prometheus.md) guide to learn more.
|
||||
|
||||
### Error reporting
|
||||
## Error reporting
|
||||
|
||||
imgproxy can report occurred errors to Bugsnag, Honeybadger and Sentry:
|
||||
|
||||
@ -192,7 +192,7 @@ imgproxy can report occurred errors to Bugsnag, Honeybadger and Sentry:
|
||||
* `IMGPROXY_SENTRY_ENVIRONMENT`: Sentry environment to report to. Default: `production`.
|
||||
* `IMGPROXY_SENTRY_RELEASE`: Sentry release to report to. Default: `imgproxy/{imgproxy version}`.
|
||||
|
||||
### Log
|
||||
## Log
|
||||
|
||||
* `IMGPROXY_LOG_FORMAT`: the log format. The following formats are supported:
|
||||
* `pretty`: _(default)_ colored human-readable format;
|
||||
@ -209,16 +209,16 @@ imgproxy can send logs to syslog, but this feature is disabled by default. To en
|
||||
|
||||
**Note:** imgproxy always uses structured log format for syslog.
|
||||
|
||||
### Memory usage tweaks
|
||||
## Memory usage tweaks
|
||||
|
||||
**Warning:** It's highly recommended to read [Memory usage tweaks](./memory_usage_tweaks.md) guide before changing this settings.
|
||||
**Warning:** It's highly recommended to read [Memory usage tweaks](memory_usage_tweaks.md) guide before changing this settings.
|
||||
|
||||
* `IMGPROXY_DOWNLOAD_BUFFER_SIZE`: the initial size (in bytes) of a single download buffer. When zero, initializes empty download buffers. Default: `0`;
|
||||
* `IMGPROXY_GZIP_BUFFER_SIZE`: the initial size (in bytes) of a single GZip buffer. When zero, initializes empty GZip buffers. Makes sense only when GZip compression is enabled. Default: `0`;
|
||||
* `IMGPROXY_FREE_MEMORY_INTERVAL`: the interval (in seconds) at which unused memory will be returned to the OS. Default: `10`;
|
||||
* `IMGPROXY_BUFFER_POOL_CALIBRATION_THRESHOLD`: the number of buffers that should be returned to a pool before calibration. Default: `1024`.
|
||||
|
||||
### Miscellaneous
|
||||
## Miscellaneous
|
||||
|
||||
* `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.
|
||||
* `IMGPROXY_USE_LINEAR_COLORSPACE`: when `true`, imgproxy will process images in linear colorspace. This will slow down processing. Note that images won't be fully processed in linear colorspace while shrink-on-load is enabled (see below).
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
# Generating the URL (Advanced)
|
||||
|
||||
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.
|
||||
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
|
||||
## Format definition
|
||||
|
||||
The advanced URL should contain the signature, processing options, and source URL, like this:
|
||||
|
||||
@ -13,13 +13,13 @@ The advanced URL should contain the signature, processing options, and source UR
|
||||
|
||||
Check out the [example](#example) at the end of this guide.
|
||||
|
||||
#### Signature
|
||||
### Signature
|
||||
|
||||
Signature protects your URL from being altered by an attacker. It is highly recommended to sign imgproxy URLs in production.
|
||||
|
||||
Once you set up your [URL signature](./configuration.md#url-signature), check out the [Signing the URL](./signing_the_url.md) guide to 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
|
||||
### Processing options
|
||||
|
||||
Processing options should be specified as URL parts divided by slashes (`/`). Processing option has the following format:
|
||||
|
||||
@ -27,11 +27,11 @@ Processing options should be specified as URL parts divided by slashes (`/`). Pr
|
||||
%option_name:%argument1:%argument2:...:argumentN
|
||||
```
|
||||
|
||||
The list of processing options does not define imgproxy's processing pipeline. Instead, imgproxy already comes with a specific, built-in image processing pipeline for the maximum performance. Read more about it in the [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:
|
||||
|
||||
##### Resize
|
||||
#### Resize
|
||||
|
||||
```
|
||||
resize:%resizing_type:%width:%height:%enlarge:%extend
|
||||
@ -40,7 +40,7 @@ rs:%resizing_type:%width:%height:%enlarge:%extend
|
||||
|
||||
Meta-option that defines the [resizing type](#resizing-type), [width](#width), [height](#height), [enlarge](#enlarge), and [extend](#extend). All arguments are optional and can be omited to use their default values.
|
||||
|
||||
##### Size
|
||||
#### Size
|
||||
|
||||
```
|
||||
size:%width:%height:%enlarge:%extend
|
||||
@ -49,7 +49,7 @@ s:%width:%height:%enlarge:%extend
|
||||
|
||||
Meta-option that defines the [width](#width), [height](#height), [enlarge](#enlarge), and [extend](#extend). All arguments are optional and can be omited to use their default values.
|
||||
|
||||
##### Resizing type
|
||||
#### Resizing type
|
||||
|
||||
```
|
||||
resizing_type:%resizing_type
|
||||
@ -64,7 +64,7 @@ Defines how imgproxy will resize the source image. Supported resizing types are:
|
||||
|
||||
Default: `fit`
|
||||
|
||||
##### Width
|
||||
#### Width
|
||||
|
||||
```
|
||||
width:%width
|
||||
@ -75,7 +75,7 @@ Defines the width of the resulting image. When set to `0`, imgproxy will calcula
|
||||
|
||||
Default: `0`
|
||||
|
||||
##### Height
|
||||
#### Height
|
||||
|
||||
```
|
||||
height:%height
|
||||
@ -86,7 +86,7 @@ Defines the height of the resulting image. When set to `0`, imgproxy will calcul
|
||||
|
||||
Default: `0`
|
||||
|
||||
##### Dpr
|
||||
#### Dpr
|
||||
|
||||
```
|
||||
dpr:%dpr
|
||||
@ -96,7 +96,7 @@ When set, imgproxy will multiply the image dimensions according to this factor f
|
||||
|
||||
Default: `1`
|
||||
|
||||
##### Enlarge
|
||||
#### Enlarge
|
||||
|
||||
```
|
||||
enlarge:%enlarge
|
||||
@ -107,7 +107,7 @@ If set to `0`, imgproxy will not enlarge the image if it is smaller than the giv
|
||||
|
||||
Default: `0`
|
||||
|
||||
##### Extend
|
||||
#### Extend
|
||||
|
||||
```
|
||||
extend:%extend
|
||||
@ -118,7 +118,7 @@ If set to `0`, imgproxy will not extend the image if the resizing result is smal
|
||||
|
||||
Default: `0`
|
||||
|
||||
##### Gravity
|
||||
#### Gravity
|
||||
|
||||
```
|
||||
gravity:%gravity_type:%x_offset:%y_offset
|
||||
@ -141,12 +141,12 @@ When imgproxy needs to cut some parts of the image, it is guided by the gravity.
|
||||
|
||||
Default: `ce:0:0`
|
||||
|
||||
###### Special gravities:
|
||||
##### Special gravities:
|
||||
|
||||
* `gravity:sm` - smart gravity. `libvips` detects the most "interesting" section of the image and considers it as the center of the resulting image. Offsets are not applicable here;
|
||||
* `gravity:fp:%x:%y` - focus point gravity. `x` and `y` are floating point numbers between 0 and 1 that define the coordinates of the center of the resulting image. Treat 0 and 1 as right/left for `x` and top/bottom for `y`.
|
||||
|
||||
##### Crop
|
||||
#### Crop
|
||||
|
||||
```
|
||||
crop:%width:%height:%gravity
|
||||
@ -158,7 +158,7 @@ Defines an area of the image to be processed (crop before resize).
|
||||
* `width` and `height` define the size of the area. When `width` or `height` is set to `0`, imgproxy will use the full width/height of the source image.
|
||||
* `gravity` accepts the same values as [gravity](#gravity) option. When `gravity` is not set, imgproxy will use the value of the [gravity](#gravity) option.
|
||||
|
||||
##### Quality
|
||||
#### Quality
|
||||
|
||||
```
|
||||
quality:%quality
|
||||
@ -169,7 +169,7 @@ Redefines quality of the resulting image, percentage.
|
||||
|
||||
Default: value from the environment variable.
|
||||
|
||||
##### Background
|
||||
#### Background
|
||||
|
||||
```
|
||||
background:%R:%G:%B
|
||||
@ -185,7 +185,7 @@ With no arguments provided, disables any background manipulations.
|
||||
|
||||
Default: disabled
|
||||
|
||||
##### Blur
|
||||
#### Blur
|
||||
|
||||
```
|
||||
blur:%sigma
|
||||
@ -196,7 +196,7 @@ When set, imgproxy will apply the gaussian blur filter to the resulting image. `
|
||||
|
||||
Default: disabled
|
||||
|
||||
##### Sharpen
|
||||
#### Sharpen
|
||||
|
||||
```
|
||||
sharpen:%sigma
|
||||
@ -209,7 +209,7 @@ As an approximate guideline, use 0.5 sigma for 4 pixels/mm (display resolution),
|
||||
|
||||
Default: disabled
|
||||
|
||||
##### Watermark
|
||||
#### Watermark
|
||||
|
||||
```
|
||||
watermark:%opacity:%position:%x_offset:%y_offset:%scale
|
||||
@ -235,7 +235,7 @@ Puts watermark on the processed image.
|
||||
|
||||
Default: disabled
|
||||
|
||||
##### Preset
|
||||
#### Preset
|
||||
|
||||
```
|
||||
preset:%preset_name1:%preset_name2:...:%preset_nameN
|
||||
@ -244,11 +244,11 @@ pr:%preset_name1:%preset_name2:...:%preset_nameN
|
||||
|
||||
Defines a list of presets to be used by imgproxy. Feel free to use as many presets in a single URL as you need.
|
||||
|
||||
Read more about presets in the [Presets](./presets.md) guide.
|
||||
Read more about presets in the [Presets](presets.md) guide.
|
||||
|
||||
Default: empty
|
||||
|
||||
##### Cache buster
|
||||
#### Cache buster
|
||||
|
||||
```
|
||||
cachebuster:%string
|
||||
@ -261,7 +261,7 @@ It's highly recommended to prefer `cachebuster` option over URL query string bec
|
||||
|
||||
Default: empty
|
||||
|
||||
##### Filename
|
||||
#### Filename
|
||||
|
||||
```
|
||||
filename:%string
|
||||
@ -272,7 +272,7 @@ Defines a filename for `Content-Disposition` header. When not specified, imgprox
|
||||
|
||||
Default: empty
|
||||
|
||||
##### Format
|
||||
#### Format
|
||||
|
||||
```
|
||||
format:%extension
|
||||
@ -284,11 +284,11 @@ Specifies the resulting image format. Alias for [extension](#extension) URL part
|
||||
|
||||
Default: `jpg`
|
||||
|
||||
#### Source URL
|
||||
### Source URL
|
||||
|
||||
There are two ways to specify source url:
|
||||
|
||||
##### Plain
|
||||
#### Plain
|
||||
|
||||
The source URL can be provided as is, prendended by `/plain/` part:
|
||||
|
||||
@ -304,7 +304,7 @@ When using plain source URL, you can specify the [extension](#extension) after `
|
||||
/plain/http://example.com/images/curiosity.jpg@png
|
||||
```
|
||||
|
||||
##### Base64 encoded
|
||||
#### Base64 encoded
|
||||
|
||||
The source URL can be encoded with URL-safe Base64. The encoded URL can be split with `/` for your needs:
|
||||
|
||||
@ -318,15 +318,15 @@ When using encoded source URL, you can specify the [extension](#extension) after
|
||||
/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png
|
||||
```
|
||||
|
||||
#### Extension
|
||||
### Extension
|
||||
|
||||
Extension specifies the format of the resulting image. At the moment, imgproxy supports only `jpg`, `png`, `webp`, `gif`, and `ico`, them being the most popular and useful image formats on the Web.
|
||||
|
||||
**Note:** Read about GIF support [here](./image_formats_support.md#gif-support).
|
||||
**Note:** Read about GIF support [here](image_formats_support.md#gif-support).
|
||||
|
||||
The extension part can be omitted. In this case, imgproxy will use source image format as resulting one. If source image format is not supported as resulting, imgproxy will use `jpg`. 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, imgproxy will use source image format as resulting one. If source image format is not supported as resulting, imgproxy will use `jpg`. You also can [enable WebP support detection](configuration.md#webp-support-detection) to use it as default resulting format when possible.
|
||||
|
||||
### Example
|
||||
## 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 then converts the image to `png`:
|
||||
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
# 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 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.
|
||||
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
|
||||
## Format definition
|
||||
|
||||
The basic URL should contain the signature, resize parameters, and source URL, like this:
|
||||
|
||||
@ -13,13 +13,13 @@ The basic URL should contain the signature, resize parameters, and source URL, l
|
||||
|
||||
Check out the [example](#example) at the end of this guide.
|
||||
|
||||
#### Signature
|
||||
### Signature
|
||||
|
||||
Signature protects your URL from being modified by an attacker. It is highly recommended to sign imgproxy URLs in a production environment.
|
||||
|
||||
Once you set up your [URL signature](./configuration.md#url-signature), check out the [Signing the URL](./signing_the_url.md) guide to learn about how to sign your URLs. Otherwise, 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
|
||||
### Resizing types
|
||||
|
||||
imgproxy supports the following resizing types:
|
||||
|
||||
@ -27,11 +27,11 @@ imgproxy supports the following resizing types:
|
||||
* `fill`: resizes the image while keeping aspect ratio to fill given size and cropping projecting parts;
|
||||
* `auto`: if both source and resulting dimensions have the same orientation (portrait or landscape), imgproxy will use `fill`. Otherwise, it will use `fit`.
|
||||
|
||||
#### Width and height
|
||||
### Width and height
|
||||
|
||||
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
|
||||
### Gravity
|
||||
|
||||
When imgproxy needs to cut some parts of the image, it is guided by the gravity. The following values are supported:
|
||||
|
||||
@ -47,15 +47,15 @@ When imgproxy needs to cut some parts of the image, it is guided by the gravity.
|
||||
* `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
|
||||
### Enlarge
|
||||
|
||||
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.
|
||||
|
||||
#### Source URL
|
||||
### Source URL
|
||||
|
||||
There are two ways to specify source url:
|
||||
|
||||
##### Plain
|
||||
#### Plain
|
||||
|
||||
The source URL can be provided as is, prepended by `/plain/` part:
|
||||
|
||||
@ -71,7 +71,7 @@ When using plain source URL, you can specify the [extension](#extension) after `
|
||||
/plain/http://example.com/images/curiosity.jpg@png
|
||||
```
|
||||
|
||||
##### Base64 encoded
|
||||
#### Base64 encoded
|
||||
|
||||
The source URL can be encoded with URL-safe Base64. The encoded URL can be split with `/` for your needs:
|
||||
|
||||
@ -85,15 +85,15 @@ When using encoded source URL, you can specify the [extension](#extension) after
|
||||
/aHR0cDovL2V4YW1w/bGUuY29tL2ltYWdl/cy9jdXJpb3NpdHku/anBn.png
|
||||
```
|
||||
|
||||
#### Extension
|
||||
### Extension
|
||||
|
||||
Extension specifies the format of the resulting image. At the moment, imgproxy supports only `jpg`, `png`, `webp`, `gif`, and `ico`, them being the most popular and useful image formats on the Web.
|
||||
|
||||
**Note:** Read about GIF support [here](./image_formats_support.md#gif-support).
|
||||
**Note:** Read about GIF support [here](image_formats_support.md#gif-support).
|
||||
|
||||
The extension part can be omitted. In this case, imgproxy will use source image format as resulting one. If source image format is not supported as resulting, imgproxy will use `jpg`. 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, imgproxy will use source image format as resulting one. If source image format is not supported as resulting, imgproxy will use `jpg`. You also can [enable WebP support detection](configuration.md#webp-support-detection) to use it as default resulting format when possible.
|
||||
|
||||
### Example
|
||||
## 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`:
|
||||
|
||||
|
||||
31
docs/index.html
Normal file
31
docs/index.html
Normal file
@ -0,0 +1,31 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Document</title>
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
|
||||
<meta name="description" content="Description">
|
||||
<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
|
||||
<link rel="stylesheet" href="assets/theme.css">
|
||||
<link rel="stylesheet" href="assets/style.css">
|
||||
</head>
|
||||
<body>
|
||||
<div id="app">
|
||||
<div class="loading">
|
||||
<div class="loading__spinner"></div>
|
||||
</div>
|
||||
</div>
|
||||
<script>
|
||||
window.$docsify = {
|
||||
name: '<img style="width:80%" title="imgproxy logo" src="https://cdn.rawgit.com/DarthSim/imgproxy/master/logo.svg" >',
|
||||
repo: 'https://github.com/imgproxy',
|
||||
loadSidebar: true,
|
||||
subMaxLevel: 2,
|
||||
auto2top: true
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/docsify-themeable@0"></script>
|
||||
<script src="//unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
There are four ways you can install imgproxy:
|
||||
|
||||
### Docker
|
||||
## Docker
|
||||
|
||||
imgproxy can (and should) be used as a standalone application inside a Docker container. Just pull the official image from Docker Hub:
|
||||
|
||||
@ -18,7 +18,7 @@ $ docker build -t imgproxy .
|
||||
$ docker run -p 8080:8080 -it imgproxy
|
||||
```
|
||||
|
||||
### Heroku
|
||||
## Heroku
|
||||
|
||||
imgproxy can be deployed to Heroku with a click of a button:
|
||||
|
||||
@ -33,15 +33,15 @@ $ heroku stack:set container
|
||||
$ git push heroku master
|
||||
```
|
||||
|
||||
### Packages
|
||||
## Packages
|
||||
|
||||
#### Arch Linux and derivatives
|
||||
### Arch Linux and derivatives
|
||||
|
||||
[imgproxy](https://aur.archlinux.org/packages/imgproxy/) package is available from AUR.
|
||||
|
||||
### From the source
|
||||
## From the source
|
||||
|
||||
#### Ubuntu
|
||||
### Ubuntu
|
||||
|
||||
First, install [libvips](https://github.com/libvips/libvips).
|
||||
|
||||
@ -69,7 +69,7 @@ And finally, install imgproxy itself:
|
||||
$ CGO_LDFLAGS_ALLOW="-s|-w" go get -f -u github.com/imgproxy/imgproxy
|
||||
```
|
||||
|
||||
#### macOS + Homebrew
|
||||
### macOS + Homebrew
|
||||
|
||||
```bash
|
||||
$ brew install vips go
|
||||
|
||||
@ -4,23 +4,23 @@ There are some imgproxy options that can help you to optimize memory usage and d
|
||||
|
||||
**Warning:** This is an advanced part. Please make sure that you know what you're doing before changing anything.
|
||||
|
||||
### `IMGPROXY_DOWNLOAD_BUFFER_SIZE`
|
||||
### IMGPROXY_DOWNLOAD_BUFFER_SIZE
|
||||
|
||||
imgproxy uses memory buffers to download source images. While these buffers are empty at the start by default, they can grow to a required size when imgproxy downloads an image. Allocating new memory to grow the buffers can cause memory fragmentation. Allocating required memory at the start can eliminate much of memory fragmentation since buffers won't grow. Setting `IMGPROXY_DOWNLOAD_BUFFER_SIZE` will tell imgproxy to initialize download buffers with _at least_ the specified size. It's recommended to use the estimated 95 percentile of your image sizes as the initial download buffers size.
|
||||
|
||||
### `IMGPROXY_GZIP_BUFFER_SIZE`
|
||||
### IMGPROXY_GZIP_BUFFER_SIZE
|
||||
|
||||
The same as `IMGPROXY_DOWNLOAD_BUFFER_SIZE` but for GZip buffers. If you use GZip compression of the resulting images, you can reduce memory fragmentation by using the estimated maximum size of the GZipped resulting image as the initial size of GZip buffers.
|
||||
|
||||
### `IMGPROXY_FREE_MEMORY_INTERVAL`
|
||||
### IMGPROXY_FREE_MEMORY_INTERVAL
|
||||
|
||||
Working with a large amount of data can cause allocating some memory that is not used most of the time. That's why imgproxy enforces Go's garbage collector to free as much memory as possible and return it to the OS. The default interval of this action is 10 seconds, but you can change it by setting `IMGPROXY_FREE_MEMORY_INTERVAL`. Decreasing the interval can smooth the memory usage graph but it can also slow down imgproxy a little. Increasing has the opposite effect.
|
||||
|
||||
### `IMGPROXY_BUFFER_POOL_CALIBRATION_THRESHOLD`
|
||||
### IMGPROXY_BUFFER_POOL_CALIBRATION_THRESHOLD
|
||||
|
||||
Buffer pools in imgproxy do self-calibration time by time. imgproxy collects stats about the sizes of the buffers returned to a pool and calculates the default buffer size and the maximum size of a buffer that can be returned to the pool. This allows dropping buffers that are too big for most of the images and save some memory. By default, imgproxy starts calibration after 1024 buffers were returned to a pool. You can change this number with `IMGPROXY_BUFFER_POOL_CALIBRATION_THRESHOLD` variable. Increasing the number will give you rarer but more accurate calibration.
|
||||
|
||||
### `MALLOC_ARENA_MAX`
|
||||
### MALLOC_ARENA_MAX
|
||||
|
||||
`libvips` uses GLib for memory management, and it brings GLib memory fragmentation issues to heavily multi-threaded programs. imgproxy is defenitely one of them. First thing you can try if you noticed constantly growing RSS usage without Go's sys memory growth is set `MALLOC_ARENA_MAX`:
|
||||
|
||||
@ -31,13 +31,13 @@ MALLOC_ARENA_MAX=2 imgproxy
|
||||
This will reduce GLib memory appetites by reducing the number of malloc arenas that it can create. By default GLib creates one are per thread, and this would folow to a memory fragmentation.
|
||||
|
||||
|
||||
### Using [jemalloc](http://jemalloc.net/)
|
||||
### Using jemalloc
|
||||
|
||||
If setting `MALLOC_ARENA_MAX` doesn't show you satisfying results, it's time to try jemalloc. As jemalloc site says:
|
||||
If setting `MALLOC_ARENA_MAX` doesn't show you satisfying results, it's time to try [jemalloc](http://jemalloc.net/). As [jemalloc site](http://jemalloc.net/) says:
|
||||
|
||||
> jemalloc is a general purpose malloc(3) implementation that emphasizes fragmentation avoidance and scalable concurrency support.
|
||||
|
||||
Most Linux distributives provide their jemalloc packages. Using jemalloc doesn't require rebuilding imgproxy or it's dependencies and can be enabled by `LD_PRELOAD` environment variable. See Debian example below. Not that jemalloc library path may vary in your system.
|
||||
Most Linux distributives provide their jemalloc packages. Using jemalloc doesn't require rebuilding imgproxy or it's dependencies and can be enabled by `LD_PRELOAD` environment variable. See Debian example below. Note that jemalloc library path may vary in your system.
|
||||
|
||||
```
|
||||
sudo apt-get install libjemalloc1
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
# Presets
|
||||
|
||||
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.
|
||||
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
|
||||
## Presets definition
|
||||
|
||||
The preset definition looks like this:
|
||||
|
||||
@ -10,19 +10,19 @@ The preset definition looks like this:
|
||||
%preset_name=%processing_options
|
||||
```
|
||||
|
||||
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`:
|
||||
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 with imgproxy in the [Configuration](./configuration.md) guide.
|
||||
Read how to specify your presets with imgproxy in the [Configuration](configuration.md) guide.
|
||||
|
||||
### Default preset
|
||||
## Default preset
|
||||
|
||||
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.
|
||||
|
||||
### Only presets
|
||||
## Only presets
|
||||
|
||||
Setting `IMGPROXY_ONLY_PRESETS` as `true` switches imgproxy into "presets-only mode". In this mode imgproxy accepts presets list as processing options just like you'd specify them for the `preset` option:
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ URL signature checking is disabled by default, but it is highly recommended to e
|
||||
* `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.
|
||||
Read our [Configuration](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:
|
||||
|
||||
@ -22,15 +22,15 @@ $ echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n')
|
||||
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 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`;
|
||||
* 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 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.**
|
||||
**You can find helpful code snippets in various programming languages the [examples](https://github.com/imgproxy/imgproxy/tree/master/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:
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user