Caddy Image Processor
This repository contains a CaddyServer module for processing images on the fly using libvips.
Features
- Automatic image processing based on URL query parameters
- Supports resizing, rotating, cropping, quality adjustments, format conversion, and more
- Efficient processing using libvips
Prerequisites
- libvips installed on your system
- libvips-dev installed on your system (only for xcaddy build)
Installation and Configuration
Using Docker
Using xcaddy
-
Before building the module, ensure you have xcaddy
installed on your system. You can install it using the following
command:
go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest
-
To build this module into Caddy, run the following command:
CGO_ENABLED=1 xcaddy build --with github.com/quix-labs/caddy-image-processor
This command compiles Caddy with the image processing module included.
Using prebuilt assets
-
You can also install the tool using release assets.
Download the appropriate package from
the Releases page, and then follow the instructions
provided for your specific platform.
Usage
Using Docker
docker run -p 80:80 -v $PWD/Caddyfile:/etc/caddy/Caddyfile -d ghcr.io/quix-labs/caddy-image-processor:latest
Your can see more information in the official docker documentation for caddy
Using xcaddy build / prebuilt assets
/path/to/your/caddy run --config /etc/caddy/Caddyfile
Your can see more information in
the official documentation for caddy
Example Caddyfile
Using file_server
localhost {
root /your-images-directory
file_server
image_processor
}
Using reverse_proxy
localhost {
reverse_proxy your-domain.com
image_processor
}
In this example, all requests undergo processing by the image processor module before being served by the
caddy.
Available Query Parameters
Param |
Name |
Description |
Type |
h |
Height |
Image height |
Integer |
w |
Width |
Image width |
Integer |
ah |
AreaHeight |
Area height |
Integer |
aw |
AreaWidth |
Area width |
Integer |
t |
Top |
Y-coordinate of the top-left corner |
Integer |
l |
Left |
X-coordinate of the top-left corner |
Integer |
q |
Quality |
Image quality (JPEG compression) |
Integer (default 75) |
cp |
Compression |
Compression level (0-9, 0 = lossless) |
Integer |
z |
Zoom |
Zoom level |
Integer |
crop |
Crop |
Whether cropping is enabled |
Boolean |
en |
Enlarge |
Whether enlargement is enabled |
Boolean |
em |
Embed |
Whether embedding is enabled |
Boolean |
flip |
Flip |
Whether vertical flipping is enabled |
Boolean |
flop |
Flop |
Whether horizontal flipping is enabled |
Boolean |
force |
Force |
Whether to force action |
Boolean |
nar |
NoAutoRotate |
Whether auto-rotation is disabled |
Boolean |
np |
NoProfile |
Whether profile is disabled |
Boolean |
itl |
Interlace |
Whether interlacing is enabled |
Boolean (default true) |
smd |
StripMetadata |
Whether to strip metadata |
Boolean (default true) |
tr |
Trim |
Whether trimming is enabled |
Boolean |
ll |
Lossless |
Whether compression is lossless |
Boolean |
th |
Threshold |
Color threshold |
Float |
g |
Gamma |
Gamma correction |
Float |
br |
Brightness |
Brightness |
Float |
c |
Contrast |
Contrast |
Float |
r |
Rotate |
Rotation angle (45, 90, 135, 180, 235, 270, 315) |
Integer |
b |
GaussianBlur |
Gaussian blur level |
Integer |
bg |
Background |
Background color (white, black, red, magenta, blue, cyan, green, yellow, or hexadecimal format #RRGGBB) |
Color |
fm |
Type |
Image type (jpg, png, gif, webp, avif) |
Image Type (default original) |
Examples
- Resize an image to a width of 400 pixels and a height of 300 pixels:
- 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):
- Adjust the quality of the image to 80:
- Convert an image to PNG format and apply a Gaussian blur of 5:
- Rotate an image by 180 degrees and flip it horizontally:
- Apply a color threshold of 0.5 and adjust the brightness to -10:
- Convert an image to AVIF format with lossless compression:
Planned Features
The following features are planned for future implementation:
- Sharp compliance: fit,...
Development
To contribute to the development of Caddy Image Processor, follow these steps:
-
Make sure you have Go installed on your system.
-
Clone this repository to your local machine:
git clone https://github.com/quix-labs/caddy-image-processor.git
-
Navigate to the project directory:
-
Install xcaddy
if you haven't already:
go get -u github.com/caddyserver/xcaddy/cmd/xcaddy
-
Make your changes in the source code.
-
Run tests to ensure your changes haven't introduced any issues:
make test
-
If tests pass, you can build the project:
make build
-
To run the project in development mode, use the following command:
make run
-
Once you're satisfied with your changes, create a pull request to the main branch of the repository for review.
Credits
License
The MIT License (MIT). Please see License File for more information.