Skip to content

Commit 6e5c80a

Browse files
shinsentershinsenter
committed
Customize photo quality via query string
1 parent 2ce4987 commit 6e5c80a

4 files changed

Lines changed: 127 additions & 47 deletions

File tree

‎README.md‎

Lines changed: 72 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
![docker-imgproxy](www/project.jpg)
1717

1818
- **Author**: Mai Nhut Tan <shin@shin.company>
19-
- **Copyright**: 2021 AppSeeds <https://code.shin.company/docker-imgproxy#readme>
19+
- **Copyright**: 2021-2023 SHIN Company <https://code.shin.company/docker-imgproxy#readme>
2020

2121

2222
## Support my activities
@@ -116,36 +116,36 @@ See [my configurations](#advanced-settings) to know how it works.
116116

117117
### Remote images
118118

119-
With the same presets as above examples, we are going to serve an image [by NASA](https://www.nasa.gov/sites/default/files/thumbnails/image/esp_040663_1415.jpg) using the alias `@nasa`, that will be added in these URLs.
119+
With the same presets as above examples, we are going to serve an image [by NASA](https://mars.nasa.gov/system/downloadable_items/40368_PIA22228.jpg) using the alias `@nasa`, that will be added in these URLs.
120120

121121
<small>Note: the image source is from NASA, it may be unavailable in the future.</small>
122122

123123
> Image with no preset (it is resized to max-width=1600 as default).<br/>
124-
> http://localhost/@nasa/esp_040663_1415.jpg
124+
> http://localhost/@nasa/40368_PIA22228.jpg
125125
126126

127127
> The image with preset `_w200` applied (`200` is a dynamic number).<br/>
128-
> http://localhost/@nasa/_w200/esp_040663_1415.jpg
128+
> http://localhost/@nasa/_w200/40368_PIA22228.jpg
129129
130130

131131
> The image with preset `_blurry` applied.<br/>
132-
> http://localhost/@nasa/_blurry/esp_040663_1415.jpg
132+
> http://localhost/@nasa/_blurry/40368_PIA22228.jpg
133133
134134

135135
> The image with preset `_small` applied.<br/>
136-
> http://localhost/@nasa/_small/esp_040663_1415.jpg
136+
> http://localhost/@nasa/_small/40368_PIA22228.jpg
137137
138138

139139
> The image with preset `_medium` applied.<br/>
140-
> http://localhost/@nasa/_medium/esp_040663_1415.jpg
140+
> http://localhost/@nasa/_medium/40368_PIA22228.jpg
141141
142142

143143
> The image with preset `_thumb` applied.<br/>
144-
> http://localhost/@nasa/_thumb/esp_040663_1415.jpg
144+
> http://localhost/@nasa/_thumb/40368_PIA22228.jpg
145145
146146

147147
> The image with preset `_square` applied.<br/>
148-
> http://localhost/@nasa/_square/esp_040663_1415.jpg
148+
> http://localhost/@nasa/_square/40368_PIA22228.jpg
149149
150150

151151
#### Supported origin servers
@@ -157,21 +157,54 @@ You can learn how to serve files from private storage in the [configurations sec
157157

158158
### Customize resizing via query string
159159

160+
#### Image width and height
161+
160162
You can also parse arguments from the request's query string, such as `?width=300` for the image's width or `?height=200` for the image's height, or even both of demensions, to flexibly change some parameters for resizing.
161163

162164
In this setup example, I used the `width` and `height` arguments to override the existing presets.
163165

164166
> Image with specific demensions (1200x960).<br/>
165-
> http://localhost/@nasa/esp_040663_1415.jpg?width=1200&height=960
167+
> http://localhost/@nasa/40368_PIA22228.jpg?width=1200&height=960
166168
167169
> Image with `width` is set to 500px.<br/>
168-
> http://localhost/@nasa/esp_040663_1415.jpg?width=500
170+
> http://localhost/@nasa/40368_PIA22228.jpg?width=500
169171
170172
> Image with `height` is set to 500px.<br/>
171-
> http://localhost/@nasa/esp_040663_1415.jpg?height=500
173+
> http://localhost/@nasa/40368_PIA22228.jpg?height=500
172174
173175
> The image with preset `_medium` applied, but the query string will override the dimensions of the output image to 50x200px.<br/>
174-
> http://localhost/@nasa/_medium/esp_040663_1415.jpg?width=50&height=200
176+
> http://localhost/@nasa/_medium/40368_PIA22228.jpg?width=50&height=200
177+
178+
#### Image quality
179+
180+
In addition, you can override the default quality defined by `IMGPROXY_FORMAT_QUALITY` in the `docker-compose.yml` file by passing a `quality` value (ranging from 1 to 100) in the query string of the request. For example, adding `?quality=100` will set the output image quality to 100% (the best quality).
181+
182+
> Image with `quality` is set.<br/>
183+
> You can check the download size of the image using browser's Developer Tools.<br/>
184+
> http://localhost/cacti.jpg?quality=1
185+
>
186+
> http://localhost/cacti.jpg?quality=10
187+
>
188+
> http://localhost/cacti.jpg?quality=50
189+
>
190+
> http://localhost/cacti.jpg?quality=80
191+
>
192+
> http://localhost/cacti.jpg?quality=100
193+
194+
> Image quality with a human readable `quality` value.<br/>
195+
> You can check the download size of the image using browser's Developer Tools.<br/>
196+
> http://localhost/cacti.jpg?quality=low
197+
>
198+
> http://localhost/cacti.jpg?quality=clear
199+
>
200+
> http://localhost/cacti.jpg?quality=high
201+
>
202+
> http://localhost/cacti.jpg?quality=highest
203+
204+
> You can combine the `quality` option with any above preset.<br/>
205+
> http://localhost/_medium/cacti.jpg?quality=high
206+
>
207+
> http://localhost/_blurry/cacti.jpg?width=500&height=500&quality=1
175208
176209
See [my configurations](#advanced-settings) to know how it works.
177210

@@ -197,12 +230,12 @@ X-Debug: /unsafe/size:320:320:0:0/sharpen:0.3/preset:logo/plain/local:///cacti.j
197230

198231
Example 2 (remote file with preset `_w640`):
199232
```
200-
curl -Isk 'http://localhost/@nasa/_w640/esp_040663_1415.jpg?debug=1'
233+
curl -Isk 'http://localhost/@nasa/_w640/40368_PIA22228.jpg?debug=1'
201234
202235
HTTP/1.1 200 OK
203236
Server: nginx
204237
Content-Type: image/webp
205-
X-Debug: /unsafe/size:640:0:0:0/preset:logo/plain/https://www.nasa.gov/sites/default/files/thumbnails/image/esp_040663_1415.jpg@webp
238+
X-Debug: /unsafe/size:640:0:0:0/preset:logo/plain/https://mars.nasa.gov/system/downloadable_items/40368_PIA22228.jpg@webp
206239
```
207240

208241

@@ -282,7 +315,7 @@ Then run the command in the [Start the server](#start-the-server) section to res
282315

283316
### Advanced settings
284317

285-
All settings for handling image URLs are written in the [`imgproxy.conf`](imgproxy.conf#L70~L234) file using [Nginx's map directives](https://Nginx.org/en/docs/http/ngx_http_map_module.html#directives).
318+
All settings for handling image URLs are written in the [`imgproxy.conf`](imgproxy.conf#L70~L250) file using [Nginx's map directives](https://Nginx.org/en/docs/http/ngx_http_map_module.html#directives).
286319

287320
I keep all configurations in very simple variables. You can also make your own version from this base.
288321

@@ -317,7 +350,7 @@ I keep all configurations in very simple variables. You can also make your own v
317350
> #> E.g.
318351
> ~^/@mybucket/ 's3://my-bucket';
319352
> ~^/@myhost/ 'http://myhost.com';
320-
> ~^/@nasa/ 'https://www.nasa.gov/sites/default/files/thumbnails/image';
353+
> ~^/@nasa/ 'https://mars.nasa.gov/system/downloadable_items';
321354
> ~^/@pinterest/ 'https://i.pinimg.com/originals';
322355
> }
323356
> ```
@@ -368,7 +401,7 @@ I keep all configurations in very simple variables. You can also make your own v
368401
369402
> **`$imgproxy_preset`**<br/>
370403
> Define `imgproxy` options for each preset name.
371-
> You can view more details by following [their documentation](https://docs.imgproxy.net/generating_the_url?id=processing-options).
404+
> You can view more details by following [their documentation](https://docs.imgproxy.net/usage/processing?#processing-options).
372405
> ```nginx
373406
> map $preset_name $imgproxy_preset
374407
> {
@@ -407,6 +440,25 @@ I keep all configurations in very simple variables. You can also make your own v
407440
> ```
408441
409442
443+
> **`$imgproxy_quality` (overriding photo quality with query string)**<br/>
444+
> Control photo quality with query string. You can also add your custom settings.
445+
> ```nginx
446+
> map $arg_quality $imgproxy_quality
447+
> {
448+
> default '';
449+
>
450+
> # if the given value is between 1 and 100, override the quality
451+
> ~^(?<quality>[1-9][0-9]?|100)$ '/q:${quality}';
452+
>
453+
> # or receive some readable quality values
454+
> low '/q:30';
455+
> clear '/q:50';
456+
> high '/q:80';
457+
> highest '/q:100';
458+
> }
459+
> ```
460+
461+
410462
> **`$imgproxy_extension`**<br/>
411463
> Detect WebP or AVIF supports from the request header `Accept`.
412464
> ```nginx
@@ -420,12 +472,12 @@ I keep all configurations in very simple variables. You can also make your own v
420472
421473
422474
> **`$imgproxy_options`**<br/>
423-
> Generate final URL for `imgproxy` following [their documentation](https://docs.imgproxy.net/generating_the_url).
475+
> Generate final URL for `imgproxy` following [their documentation](https://docs.imgproxy.net/usage/processing).
424476
> When URL query `?skip=1` is set, use another rule to skip `imgproxy` processing.
425477
> ```nginx
426478
> map $arg_skip $imgproxy_options
427479
> {
428-
> default '/unsafe/${imgproxy_preset}${imgproxy_preset_query}/plain/${origin_server}${origin_uri}${imgproxy_extension}';
480+
> default '/unsafe/${imgproxy_preset}${imgproxy_preset_query}${imgproxy_quality}/plain/${origin_server}${origin_uri}${imgproxy_extension}';
429481
> ~.+ '/unsafe/plain/${origin_server}${origin_uri}';
430482
> }
431483
> ```

‎docker-compose.yml‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ version: '3'
55
# A production grade image processing server setup powered by imgproxy and nginx
66
#
77
# Author: Mai Nhut Tan <shin@shin.company>
8-
# Copyright: 2021 AppSeeds https://code.shin.company/
8+
# Copyright: 2021-2023 SHIN Company https://code.shin.company/
99
# URL: https://shinsenter.github.io/docker-imgproxy/
1010
################################################################################
1111

@@ -53,7 +53,7 @@ services:
5353
test: ["CMD", "imgproxy", "health"]
5454
environment:
5555
### See:
56-
### https://docs.imgproxy.net/configuration
56+
### https://docs.imgproxy.net/configuration/options
5757

5858
### log and debug
5959
IMGPROXY_LOG_LEVEL: "warn"
@@ -66,7 +66,8 @@ services:
6666
IMGPROXY_WRITE_TIMEOUT: 10
6767
IMGPROXY_DOWNLOAD_TIMEOUT: 10
6868
IMGPROXY_KEEP_ALIVE_TIMEOUT: 300
69-
IMGPROXY_MAX_SRC_FILE_SIZE: 20971520 # 20MB
69+
IMGPROXY_MAX_SRC_FILE_SIZE: 33554432 # 32MB
70+
IMGPROXY_MAX_SRC_RESOLUTION: 48
7071

7172
### image source
7273
IMGPROXY_TTL: 2592000 # client-side cache time is 30 days
@@ -78,7 +79,7 @@ services:
7879

7980
### presets
8081
IMGPROXY_AUTO_ROTATE: "true"
81-
IMGPROXY_WATERMARK_PATH: /home/watermark.jpg
82+
IMGPROXY_WATERMARK_PATH: /home/noimage_thumb.jpg
8283
IMGPROXY_PRESETS: default=resizing_type:fit/gravity:sm,logo=watermark:0.5:soea:10:10:0.15,center_logo=watermark:0.3:ce:0:0:0.3
8384

8485
### compression
@@ -99,20 +100,20 @@ services:
99100
# IMGPROXY_SIGNATURE_SIZE: 32
100101

101102
### External source (S3)
102-
### See: https://docs.imgproxy.net/serving_files_from_s3
103+
### See: https://docs.imgproxy.net/image_sources/amazon_s3
103104
# IMGPROXY_USE_S3: "true"
104105
# IMGPROXY_S3_REGION: "us-west-1"
105106
# IMGPROXY_S3_ENDPOINT: "<your endpoint>"
106107
# AWS_ACCESS_KEY_ID: "<your id>"
107108
# AWS_SECRET_ACCESS_KEY: "<your key>"
108109

109110
### External source (Google Cloud)
110-
### See: https://docs.imgproxy.net/serving_files_from_google_cloud_storage
111+
### See: https://docs.imgproxy.net/image_sources/google_cloud_storage
111112
# IMGPROXY_USE_GCS: "true"
112113
# IMGPROXY_GCS_KEY: "<your key>"
113114

114115
### External source (Azure Blob)
115-
### See: https://docs.imgproxy.net/serving_files_from_azure_blob_storage
116+
### See: https://docs.imgproxy.net/image_sources/azure_blob_storage
116117
# IMGPROXY_USE_ABS: "true"
117118
# IMGPROXY_ABS_NAME: "<your name>"
118119
# IMGPROXY_ABS_KEY: "<your key>"

‎imgproxy.conf‎

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
# A production grade image processing server setup powered by `imgproxy` and nginx
44
#
55
# Author: Mai Nhut Tan <shin@shin.company>
6-
# Copyright: 2021 AppSeeds https://code.shin.company/
6+
# Copyright: 2021-2023 SHIN Company https://code.shin.company/
77
# URL: https://shinsenter.github.io/docker-imgproxy/
88
################################################################################
99

@@ -104,7 +104,7 @@ map $uri $origin_server
104104
#> E.g.
105105
~^/@mybucket/ 's3://my-bucket';
106106
~^/@myhost/ 'http://myhost.com';
107-
~^/@nasa/ 'https://www.nasa.gov/sites/default/files/thumbnails/image';
107+
~^/@nasa/ 'https://mars.nasa.gov/system/downloadable_items';
108108
~^/@pinterest/ 'https://i.pinimg.com/originals';
109109
}
110110

@@ -147,7 +147,7 @@ map $uri_omitted_origin $preset_name
147147

148148
## **`$imgproxy_preset`**
149149
## Define `imgproxy` options for each preset name.
150-
## You can view more details by following [their documentation](https://docs.imgproxy.net/generating_the_url?id=processing-options).
150+
## You can view more details by following [their documentation](https://docs.imgproxy.net/usage/processing?#processing-options).
151151
map $preset_name $imgproxy_preset
152152
{
153153
default 'size:1600:0:0:0/preset:logo';
@@ -180,6 +180,22 @@ map "$arg_width:$arg_height" $imgproxy_preset_query
180180
~^(?<width>[0-9]+):(?<height>[0-9]+)$ '/size:${width}:${height}:1:0/bg:ffffff/resizing_type:fill';
181181
}
182182

183+
## **`$imgproxy_quality` (overriding photo quality with query string)**
184+
## Control photo quality with query string. You can also add your custom settings.
185+
map $arg_quality $imgproxy_quality
186+
{
187+
default '';
188+
189+
# if the given value is between 1 and 100, override the quality
190+
~^(?<quality>[1-9][0-9]?|100)$ '/q:${quality}';
191+
192+
# or receive some readable quality values
193+
low '/q:30';
194+
clear '/q:50';
195+
high '/q:80';
196+
highest '/q:100';
197+
}
198+
183199
## **`$imgproxy_extension`**
184200
## Detect WebP or AVIF supports from the request header `Accept`.
185201
map $http_accept $imgproxy_extension
@@ -190,16 +206,16 @@ map $http_accept $imgproxy_extension
190206
}
191207

192208
## **`$imgproxy_options`**
193-
## Generate final URL for `imgproxy` following [their documentation](https://docs.imgproxy.net/generating_the_url).
209+
## Generate final URL for `imgproxy` following [their documentation](https://docs.imgproxy.net/usage/processing).
194210
## When URL query `?skip=1` is set, use another rule to skip `imgproxy` processing.
195211
map $arg_skip $imgproxy_options
196212
{
197-
default '/unsafe/${imgproxy_preset}${imgproxy_preset_query}/plain/${origin_server}${origin_uri}${imgproxy_extension}';
213+
default '/unsafe/${imgproxy_preset}${imgproxy_preset_query}${imgproxy_quality}/plain/${origin_server}${origin_uri}${imgproxy_extension}';
198214
~.+ '/unsafe/plain/${origin_server}${origin_uri}';
199215
}
200216

201217
##! **`$imgproxy_rewrite`**
202-
## Generate final URL for `imgproxy` following [their documentation](https://docs.imgproxy.net/generating_the_url).
218+
## Generate final URL for `imgproxy` following [their documentation](https://docs.imgproxy.net/usage/processing).
203219
map $use_imgproxy $imgproxy_rewrite
204220
{
205221
default '';

0 commit comments

Comments
 (0)