{"id":13753469,"url":"https://github.com/niiknow/docker-nginx-image-proxy","last_synced_at":"2025-05-07T17:50:45.473Z","repository":{"id":50271113,"uuid":"89935845","full_name":"niiknow/docker-nginx-image-proxy","owner":"niiknow","description":"on the fly image cropping with gravity, resize and compression microservice","archived":false,"fork":false,"pushed_at":"2024-09-11T22:28:41.000Z","size":77118,"stargazers_count":108,"open_issues_count":1,"forks_count":31,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-09-12T08:37:46.285Z","etag":null,"topics":["cdn","center","crop","docker","dynamic","gravity","image","imageproxy","libgd","microservice","nginx","nginx-image-proxy","proxy","resize","transform","ubuntu","xenial"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/niiknow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-01T15:25:52.000Z","updated_at":"2024-09-11T22:21:29.000Z","dependencies_parsed_at":"2023-12-13T16:31:51.782Z","dependency_job_id":"b1f9464c-bba0-4057-89eb-9b11213e11f0","html_url":"https://github.com/niiknow/docker-nginx-image-proxy","commit_stats":null,"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niiknow%2Fdocker-nginx-image-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niiknow%2Fdocker-nginx-image-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niiknow%2Fdocker-nginx-image-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niiknow%2Fdocker-nginx-image-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/niiknow","download_url":"https://codeload.github.com/niiknow/docker-nginx-image-proxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252931391,"owners_count":21827104,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cdn","center","crop","docker","dynamic","gravity","image","imageproxy","libgd","microservice","nginx","nginx-image-proxy","proxy","resize","transform","ubuntu","xenial"],"created_at":"2024-08-03T09:01:22.879Z","updated_at":"2025-05-07T17:50:45.439Z","avatar_url":"https://github.com/niiknow.png","language":"C","funding_links":[],"categories":["proxy"],"sub_categories":[],"readme":"# nginx image proxy\n\u003eHigh Performance and Low Resource Utilization Microservice\n\nimage cropping with gravity, resize and compress on the fly with nginx **image_filter** module.  A tiny docker container to build your own Cloudinary-like service.\n\nNginx module - https://github.com/niiknow/docker-nginx-image-proxy/blob/master/build/ngx_http_image_filter_module.c\n\nOriginal File - https://github.com/niiknow/docker-nginx-image-proxy/blob/master/build/src/http/modules/ngx_http_image_filter_module.c\n\nPatch creation: `diff -u build/src/http/modules/ngx_http_image_filter_module.c build/ngx_http_image_filter_module.c \u003e build/image_filter.patch`\n\nPatch apply with: `patch src/http/modules/ngx_http_image_filter_module.c image_filter.patch`\n\nFeatures:\n- [x] image crop offset, credit: https://github.com/bobrik/nginx_image_filter\n- [x] /healthcheck endpoint\n- [x] empty gif on other errors: 403, 404, 415, 500, 502, 503, 504\n- [x] convert/force output to another format, support formats: bmp, jpg, png, gif, webp, and tiff \n- [x] use custom ssl and saved config when you mount '/app' volume.  nginx logs has also been redirect so you can backup, such as aws s3 sync.  Just delete the default redirect to stdout/access.log and stderr/error.log files.\n- [x] support international characters in URL\n- [x] automatically follow redirect at origin \n- [x] overridable nginx config - easily add secure link or additional nginx config\n- [x] watermark with\n```shell\n# file must be png\nimage_filter_water_image /path/to/file/watermark.png;\n\n# optional watermark positioning\nimage_filter_water_pos [ top-left | top-right | center | bottom-left | bottom-right (default)];\n```\n\u003e TIP: The implementation of watermark feature, at the moment, is a very naive one.  Due to limited functionality, it add watermark after the image has been resized.  It work best when resize to smaller image/thumbnail and use in combination of a smaller watermark image.  We may expand on the functionality in the future, if we have time.\n\n- [x] resize support image scale (enlarge image)\n```shell\n# optional scale max ratio, default 1\n# becareful not to set this too high or it will use too much memory.\n# \n# For example (during testing) a 200KB JPEG file (1024x768) will take up 4MB of memory \n# when loaded; but when resampled to twice (2x) of image size, the memory use jumps to 20.1MB\n# Mathematically make sense: 4MB * 2(Dimensions xy) = 4MB * 2 * 2 = 16MB (new) + 4MB (original) = 20MB\nimage_filter_scale_max 3;\n\n```\n\n# What does this solve?\nYou have a huge repository of images that need dynamic resize and cropping.  Cloudinary can be expensive and redundant if you run your own CDN in front of this microservice.\n\n# And what it doesn't?\nUnlike other libraries, this does not try to do every image transformation and/or caching.\n\n1.  For more advanced features such as: animated gif, face detection, auto image optimization, and others; we recommend using Cloudinary or similar service.\n2.  Outside of disk cache, there is no plan for other Caching methods.  We recommend putting a CDN in front, such as (MaxCDN/StackPath/KeyCDN), to provide caching and easy SSL.  We love StackPath/MaxCDN EdgeRules™.\n3.  If you want thumbnail caching to s3, just write a lambda function and use this server to generate your thumbnail.  Upload the result to s3 with the same function.\n\n# build\nTo achieve smaller/tiny microservice, this container utilize multi-stage build introduced in Docker 17.06; therefore, Docker 17.06+ is required to build.\n\n```\ndocker build -t nginx-image-proxy .\n```\n\n# run\ndocker run -d --restart=always -p 80:80 niiknow/nginx-image-proxy\n--env SERVER_CONF='https://gist.githubusercontent.com/...'\n\n# web\nExample: http://imageproxy.yourdomain.com/rx/url-options/http://remote-host.com/image-path/image.jpg\n\nor http as protocol default: http://imageproxy.yourdomain.com/rx/url-options/remote-host.com/image-path/image.jpg\n\nOption Keys:\n-------------\n\n```yml\ncode: name - valid values - default\n  q: quality - 1..100 - 96 (default to best in case it's previously optimized) \n  w: width - uint - null\n  h: height - uint - null\n  c: crop - null, 1 - null\n  rz: resize - null, 1 - 1\n  g: gravity - NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast *case-sensitive* - NorthWest\n  e: sharpen - 1..100 - 0\n  r: rotate - 0, 90, 180, 270 - 0\n  ofmt: bmp, jpg, jpeg, png, gif, webp - force output format\n```\n\nOptions Usages:\n----------------\n\nOptions are a subset of Cloudinary. It's also very flexible and customizable.\n\n* Like Cloudinary with underscore (_) as separator:  OptionKey_OptionValue - g_Center, w_100, h_100\n* Or without any separator: OptionKeyOptionValue - gCenter, w100, h100\n* Or in a QueryString: ?g=Center\u0026w=100\u0026h=100\n\nAnd if that doesn't work, you can always use your custom nginx config by passing the config url into docker environment variable: SERVER_CONF\n\n# Example \n* Original Image - https://octodex.github.com/images/codercat.jpg - 896x896\n* Dynamic Height - http://imageproxy.niiknow.org/rx/50/https://octodex.github.com/images/codercat.jpg\n![Dynamic Height](http://imageproxy.niiknow.org/rx/50/https://octodex.github.com/images/codercat.jpg?asdf)\n\n* Dynamic Width - http://imageproxy.niiknow.org/rx/x100/https://octodex.github.com/images/codercat.jpg\n![Dynamic Width](http://imageproxy.niiknow.org/rx/x100/https://octodex.github.com/images/codercat.jpg?asdf)\n\n* Fix Width and Height, fit - http://imageproxy.niiknow.org/rx/200x500/https://static.pexels.com/photos/104827/cat-pet-animal-domestic-104827.jpeg\n![Fix Width and Height - fit](http://imageproxy.niiknow.org/rx/200x500/https://static.pexels.com/photos/104827/cat-pet-animal-domestic-104827.jpeg?asdf)\n\n* Resize with rotate, sharpen - http://imageproxy.niiknow.org/rx/100,r_90,e_50/https://static.pexels.com/photos/104827/cat-pet-animal-domestic-104827.jpeg\n![Resize with rotate, sharpen](http://imageproxy.niiknow.org/rx/100,r_90,e_50/https://static.pexels.com/photos/104827/cat-pet-animal-domestic-104827.jpeg?asdf)\n\n* Crop with gravity - http://imageproxy.niiknow.org/rx/100x100,c_1,g_Center/https://static.pexels.com/photos/104827/cat-pet-animal-domestic-104827.jpeg\n![Crop with gravity](http://imageproxy.niiknow.org/rx/100x100,c_1,g_Center/https://static.pexels.com/photos/104827/cat-pet-animal-domestic-104827.jpeg?asdf)\n\n* Scale with watermark - http://imageproxy.niiknow.org/rx/2000,water_1/https://octodex.github.com/images/codercat.jpg\n![Scale with watermark](http://imageproxy.niiknow.org/rx/2000,water_1/https://octodex.github.com/images/codercat.jpg)\n\n# December 2021 Update\nWe're still using this project so maintenance and security update continues until further notice, but we're no longer adding new feature.  We're also taking down example server so demo images above may not work in the future.\n\n# Point of Interest\n* [images.weserv.nl](https://github.com/weserv/images) is another great project to look at if you need additional features with image resizing.  The original purpose of this library (nginx-image-proxy) is to provide high performance and low resource utilization image private microservice.  We searched high and low but did not find a good solution.  At that time, we saw great potential with images.weserv.nl, but was held back because it was using php.  Since July 2018, it was rewritten with lua and direct c binding; as a result, it has became the next best solution and continue to improve.  The authors also generiously provide free endpoint for public use.  This help prove their implementation to be well battle-tested for use in any production environment.\n\u003e Update, as of September 2019, images.weserv.nl was rewritten again as C++ so it has now became the better/best choice.  We are now sun-setting this project, only maintenance and security support - no new feature, for the future date of December 2021 or 2 years from December 2019.\n\n# MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniiknow%2Fdocker-nginx-image-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniiknow%2Fdocker-nginx-image-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniiknow%2Fdocker-nginx-image-proxy/lists"}