{"id":20447018,"url":"https://github.com/quix-labs/caddy-image-processor","last_synced_at":"2026-03-16T15:01:18.962Z","repository":{"id":229458129,"uuid":"776779510","full_name":"quix-labs/caddy-image-processor","owner":"quix-labs","description":"CaddyServer module for processing images on the fly.","archived":false,"fork":false,"pushed_at":"2024-12-15T12:26:33.000Z","size":259,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-13T01:06:20.214Z","etag":null,"topics":["caddy","go","image-processing","proxy","vips"],"latest_commit_sha":null,"homepage":"","language":"Go","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/quix-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security.go","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"alancolant"}},"created_at":"2024-03-24T13:23:35.000Z","updated_at":"2025-01-10T06:45:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"7642ec16-d9fa-46dc-9765-9e55a502eaf9","html_url":"https://github.com/quix-labs/caddy-image-processor","commit_stats":null,"previous_names":["quix-labs/caddy-image-processor"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quix-labs%2Fcaddy-image-processor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quix-labs%2Fcaddy-image-processor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quix-labs%2Fcaddy-image-processor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quix-labs%2Fcaddy-image-processor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quix-labs","download_url":"https://codeload.github.com/quix-labs/caddy-image-processor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248650508,"owners_count":21139678,"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":["caddy","go","image-processing","proxy","vips"],"created_at":"2024-11-15T10:24:10.869Z","updated_at":"2026-03-16T15:01:13.918Z","avatar_url":"https://github.com/quix-labs.png","language":"Go","funding_links":["https://github.com/sponsors/alancolant"],"categories":[],"sub_categories":[],"readme":"[![Build Static Releases](https://github.com/quix-labs/caddy-image-processor/actions/workflows/build-on-release.yml/badge.svg)](https://github.com/quix-labs/caddy-image-processor/actions/workflows/build-on-release.yml)\n[![Build Docker](https://github.com/quix-labs/caddy-image-processor/actions/workflows/docker-on-release.yml/badge.svg)](https://github.com/quix-labs/caddy-image-processor/actions/workflows/docker-on-release.yml)\n\n# Caddy Image Processor\n\nThis repository contains a CaddyServer module for processing images on the fly using libvips.\n\n## Features\n\n- Automatic image processing based on URL query parameters\n- Supports resizing, rotating, cropping, quality adjustments, format conversion, and more\n- Efficient processing using libvips\n\n## Prerequisites\n\n- [libvips](https://libvips.github.io/libvips/install.html) installed on your system\n- [libvips-dev](https://libvips.github.io/libvips/install.html) installed on your system (only for xcaddy build)\n\n## Installation and Configuration\n\n### Using Docker\n\n- Pull the Docker image from the GitHub Container Registry:\n    ```bash\n    docker pull ghcr.io/quix-labs/caddy-image-processor:latest\n    ```\n\n### Using xcaddy\n\n- Before building the module, ensure you have `xcaddy` installed on your system. You can install it using the following\n  command:\n\n  ```bash\n  go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest\n  ```\n\n- To build this module into Caddy, run the following command:\n\n  ```bash\n  CGO_ENABLED=1 xcaddy build --with github.com/quix-labs/caddy-image-processor\n  ```\n\n  This command compiles Caddy with the image processing module included.\n\n### Using prebuilt assets\n\n- You can also install the tool using release assets.\n\n  Download the appropriate package from\n  the [Releases page](https://github.com/quix-labs/caddy-image-processor/releases), and then follow the instructions\n  provided for your specific platform.\n\n## Usage\n\n### Using Docker\n\n```bash\ndocker run -p 80:80 -v $PWD/Caddyfile:/etc/caddy/Caddyfile -d ghcr.io/quix-labs/caddy-image-processor:latest\n```\n\nYour can see more information in the [official docker documentation for caddy](https://hub.docker.com/_/caddy)\n\n### Using xcaddy build / prebuilt assets\n\n```bash\n/path/to/your/caddy run --config /etc/caddy/Caddyfile\n```\n\nYour can see more information in\nthe [official documentation for caddy](https://caddyserver.com/docs/build#package-support-files-for-custom-builds-for-debianubunturaspbian)\n\n## Example Caddyfile\n\n### Using file_server\n\n```plaintext\nlocalhost {\n    root /your-images-directory\n    file_server\n    image_processor\n}\n```\n\n### Using reverse_proxy\n\n```plaintext\nlocalhost {\n    reverse_proxy your-domain.com\n    image_processor\n}\n```\n\nIn this example, all requests undergo processing by the image processor module before being served by the\ncaddy.\n\n## Available Query Parameters\n\n| Param | Name          | Description                                                                                             | Type                          |\n|-------|---------------|---------------------------------------------------------------------------------------------------------|-------------------------------|\n| h     | Height        | Image height                                                                                            | Integer                       |\n| w     | Width         | Image width                                                                                             | Integer                       |\n| ah    | AreaHeight    | Area height                                                                                             | Integer                       |\n| aw    | AreaWidth     | Area width                                                                                              | Integer                       |\n| t     | Top           | Y-coordinate of the top-left corner                                                                     | Integer                       |\n| l     | Left          | X-coordinate of the top-left corner                                                                     | Integer                       |\n| q     | Quality       | Image quality (JPEG compression)                                                                        | Integer (default 75)          |\n| cp    | Compression   | Compression level (0-9, 0 = lossless)                                                                   | Integer                       |\n| z     | Zoom          | Zoom level                                                                                              | Integer                       |\n| crop  | Crop          | Whether cropping is enabled                                                                             | Boolean                       |\n| en    | Enlarge       | Whether enlargement is enabled                                                                          | Boolean                       |\n| em    | Embed         | Whether embedding is enabled                                                                            | Boolean                       |\n| flip  | Flip          | Whether vertical flipping is enabled                                                                    | Boolean                       |\n| flop  | Flop          | Whether horizontal flipping is enabled                                                                  | Boolean                       |\n| force | Force         | Whether to force action                                                                                 | Boolean                       |\n| nar   | NoAutoRotate  | Whether auto-rotation is disabled                                                                       | Boolean                       |\n| np    | NoProfile     | Whether profile is disabled                                                                             | Boolean                       |\n| itl   | Interlace     | Whether interlacing is enabled                                                                          | Boolean (default true)        |\n| smd   | StripMetadata | Whether to strip metadata                                                                               | Boolean (default true)        |\n| tr    | Trim          | Whether trimming is enabled                                                                             | Boolean                       |\n| ll    | Lossless      | Whether compression is lossless                                                                         | Boolean                       |\n| th    | Threshold     | Color threshold                                                                                         | Float                         |\n| g     | Gamma         | Gamma correction                                                                                        | Float                         |\n| br    | Brightness    | Brightness                                                                                              | Float                         |\n| c     | Contrast      | Contrast                                                                                                | Float                         |\n| r     | Rotate        | Rotation angle (45, 90, 135, 180, 235, 270, 315)                                                        | Integer                       |\n| b     | GaussianBlur  | Gaussian blur level                                                                                     | Integer                       |\n| bg    | Background    | Background color (white, black, red, magenta, blue, cyan, green, yellow, or hexadecimal format #RRGGBB) | Color                         |\n| fm    | Type          | Image type (jpg, png, gif, webp, avif)                                                                  | Image Type (default original) |\n\n## Examples\n\n* Resize an image to a width of 400 pixels and a height of 300 pixels:\n    * http://example.com/image.jpg?w=400\u0026h=300\n* Crop an image to a width of 200 pixels and a height of 150 pixels starting from the top-left corner (x=50, y=50):\n    * http://example.com/image.jpg?w=200\u0026h=150\u0026t=50\u0026l=50\u0026crop=true\n* Adjust the quality of the image to 80:\n    * http://example.com/image.jpg?q=80\n* Convert an image to PNG format and apply a Gaussian blur of 5:\n    * http://example.com/image.jpg?fm=png\u0026b=5\n* Rotate an image by 180 degrees and flip it horizontally:\n    * http://example.com/image.jpg?r=180\u0026flop=true\n* Apply a color threshold of 0.5 and adjust the brightness to -10:\n    * http://example.com/image.jpg?th=0.5\u0026br=-10\n* Convert an image to AVIF format with lossless compression:\n    * http://example.com/image.jpg?fm=avif\u0026ll=true\n\n## Advanced Configuration\n\nThis configuration allows you to control error handling with `on_fail` and `on_security_fail`.\n\nYou can also manage query parameter processing using `allowed_params` and `disallowed_params`.\n\nThis gives you fine-grained control over image processing in your Caddy server.\n\n\n### Example with `on_fail` and Security Configuration\n```plaintext\nlocalhost:80 {\n    root test-dataset\n    file_server\n\t\n    image_processor {\n\t    \n        # Serve original image if image in unprocessable\n        on_fail bypass\t    \n        \n        # Return 500 Internal Server Error if processing fails\n        # on_fail abort\t    \n        \n        security {\n\n            # Use ignore to remove param from processing, all valid param are processed\n            on_security_fail ignore\n\n            # Use abort to return 400 Bad Request when fails\n            # on_security_fail abort\n\n            # Use bypass to serve original image without processing\n            # on_security_fail bypass\n\n            # Explicitely disable rotate capabilities\n            disallowed_params r\n            \n            # As an alternative use this to only accept width and height processing \n            # allowed_params w h \n            \n            constraints {\n                h range 60 480\n\n                w {\n                    values 60 130 240 480 637\n\n                    # Shortcut range 60 637\n                    range {\n                        from 60\n                        to 637\n                    }\n                }\n            }\n        }\n    }\n}\n```\n\n### Explanation:\n\n* `on_fail`:\n    * `bypass` (default value): If any error occurs, the original, unprocessed image will be returned.\n    * `abort`: If an error occurs, a 500 Internal Server Error response will be returned.\n\n\n* `on_security_fail`:\n    * `ignore` (default value): If any security checks fail, they are ignored, and the image processing continues.\n    * `bypass`: If any security checks fail, the original, unprocessed image will be returned.\n    * `abort`: If any security checks fail, a 400 Bad Request response will be returned.\n\n\n* **Security Configuration** (`disallowed_params` vs `allowed_params`):\n  * `disallowed_params`: Specifies which query parameters are not allowed.\n    \n    For example, parameters like w (width) and r (rotation) can be restricted.\n\n  * `allowed_params`: Specify which query parameters are allowed. As an alternative to `disallowed_params`.\n\n  *  **Important**: You cannot use both allowed_params and disallowed_params in the same configuration.\n  *  `constraints`: You san specify constraints for each parameter (see example)\n\n\n## Planned Features\n\nThe following features are planned for future implementation:\n\n- Sharp compliance: fit,...\n\n## Development\n\nTo contribute to the development of Caddy Image Processor, follow these steps:\n\n1. Make sure you have Go installed on your system.\n2. Clone this repository to your local machine:\n   ```bash\n   git clone https://github.com/quix-labs/caddy-image-processor.git\n   ```\n\n3. Navigate to the project directory:\n4. Install `xcaddy` if you haven't already:\n    ```bash\n    go get -u github.com/caddyserver/xcaddy/cmd/xcaddy\n    ```\n5. Make your changes in the source code.\n6. Run tests to ensure your changes haven't introduced any issues:\n    ```bash\n   make test\n    ```\n7. If tests pass, you can build the project:\n    ```bash\n   make build\n    ```\n8. To run the project in development mode, use the following command:\n    ```bash\n   make run\n    ```\n9. Once you're satisfied with your changes, create a pull request to the main branch of the repository for review.\n\n## Credits\n\n- [COLANT Alan](https://github.com/alancolant)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquix-labs%2Fcaddy-image-processor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquix-labs%2Fcaddy-image-processor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquix-labs%2Fcaddy-image-processor/lists"}