Enable URL signatures for security
master-enable-url-signature flag. This requires a signature key provided via the -url-signature-key flag or the URL_SIGNATURE_KEY environment variable.repository·master·Indexed 26 days ago
https://github.com/h2non/imaginaryA fast HTTP microservice written in Go for high-level image processing. Backed by libvips and bimg, it provides high-performance transformations including resizing, cropping, and format conversion with a low memory footprint. Features include a transformation pipeline, URL signatures for security, remote HTTP URL source support, and placeholder image responses.
-enable-url-signature flag. This requires a signature key provided via the -url-signature-key flag or the URL_SIGNATURE_KEY environment variable.Imaginary uses an Apache-compatible log format. You can ingest these logs using Fluentd by applying a parser filter to separate access logs from warning/error logs.
Access logs (containing a code field) will be tagged with *.imaginary.access, while warning and error logs (lacking a code field) will be tagged with *.imaginary.error.
# use your own tag name (*.imaginary for this example)
<filter *.imaginary>
@type parser
key_name log
reserve_data true
<parse>
@type multi_format
# access logs parser
<pattern>
format regexp
expression /^[^ ]* [^ ]* [^ ]* \[(?<time>[^\]]*)\] "(?<method>\S+)(?: +(?<path>[^ ]*) +\S*)?" (?<code>[^ ]*) (?<size>[^ ]*) (?<response_time>[^ ]*)$/
types code:integer,size:integer,response_time:float
time_key time
time_format %d/%b/%Y %H:%M:%S
</pattern>
# warnings / error logs parser
<pattern>
format none
message_key message
</pattern>
</parse>
</filter>
<match *.imaginary>
@type rewrite_tag_filter
# Logs with code field are access logs, and logs without are error logs
<rule>
key code
pattern ^.+$
tag ${tag}.access
</rule>
<rule>
key code
pattern ^.+$
invert true
tag ${tag}.error
</rule>
</match>imaginary as a Docker container. By default, it listens on port 9000. Use the following commands to pull the image and run it with different configurations:To deploy to Cloud Foundry (Bluemix/Pivotal), follow these steps:
LD_LIBRARY_PATH to point to the vips library.git clone https://github.com/h2non/imaginary.git
cf push -b https://github.com/yacloud-io/go-buildpack-imaginary.git imaginary-inst01 --no-start
cf set-env imaginary-inst01 LD_LIBRARY_PATH /home/vcap/app/vendor/vips/lib
cf start imaginary-inst01To install imaginary as a Go module, use the following commands. Ensure you also have the latest version of bimg installed.
go get -u github.com/h2non/imaginary
go get -u github.com/h2non/bimgTo allow imaginary to fetch images from remote HTTP URLs (using the ?url=http://... query parameter), you must enable the -enable-url-source flag.
Additional security and control options for remote sources:
-allowed-origins <urls> (comma-separated) to restrict which hosts/paths can be used as sources.-enable-auth-forwarding to forward X-Forward-Authorization or Authorization headers from the client to the image source server.-authorization <value> to define a constant Authorization header sent to all image source servers, overwriting forwarding behavior.-max-allowed-size <bytes> to restrict the maximum size of the remote image source.You can enable simple token-based authorization by passing the -key flag to the imaginary binary. Once enabled, the API key can be provided in requests via either the API-Key HTTP header or a key query parameter.
POST /crop HTTP/1.1
Host: localhost:8088
API-Key: secretWhen -enable-placeholder is active, imaginary returns a placeholder image instead of an error for bad requests or server errors. The placeholder is dynamically resized and converted to match the requested width, height, and image type.
To use a custom placeholder image, use the -placeholder <path> flag. It is recommended to use a large image (e.g., 1200x1200px) in JPEG, PNG, or WEBP format.
multipart/form-data, you must include at least one field named file containing the raw image data. If you wish to use a different field name, you can specify it using the field parameter.To protect your server from DDoS-like attacks and ensure stable performance in production, use the -concurrency flag. A recommended limit is up to 20 requests per second per server.
$ imaginary -concurrency 20imaginary requires libvips 8.8+ (8.9+ recommended). You can use the following script to install it on OSX, Debian/Ubuntu, Redhat, Fedora, or Amazon Linux. This script requires curl and pkg-config to be installed on your system.
curl -s https://raw.githubusercontent.com/h2non/bimg/master/preinstall.sh | sudo bash -imaginary can be configured to only allow requests where the image source URL matches a specified list of origins. This is done using the -allowed-origins flag. The validation checks if the remote URL matches the hostname and path of at least one origin in the list, supporting wildcards.