Config Reference

Imagizer Config allows for advanced configuration of the Imagizer instance using a JSON object. The Imagizer config may be retrieved and modified through either the Admin API or through EC2 User Data.

See a full config object example here.

WARNING

Not currently support on http://cloud.imagizer.com.

allowDynamicOrigin

Allow Imagizer to dynamically set the backend using the origin, source_url or bucket parameters. (default: true)

Disable the origin, source_url, and bucket parameters.

{  
   "allowDynamicOrigin": false
}

allowOriginalImageRequest

Allow Imagizer to pass through the original image when no parameters are present. (default: true)

{  
   "allowOriginalImageRequest": true
}

applicationWorkers

The size of the application worker pools. There are two worker pools running on Imagizer. The process and fetch pools. By default, Imagizer will set a safe number of workers for each pool depending on the number of RAM the instance has available. The size of the pools may be overridden to optimize the performance of the instance.

The size of the process pool should be at least as large as the maximum number of concurrent connections the instance will ever see. The size of the fetch pool should be at least as large as the maximum number of concurrent connections to the image storage origin.

Property Description
autoConfig When true Imagizer will auto configure the size of the application pools. (default: true)
process The number of workers in the process pool.
fetch The number of workers in the fetch pool.

awsAuthorization

The name and credentials for a private AWS S3 Bucket where your images are stored. Use this property or the backend property, but not both.

TIP

You must first create an AWS IAM Role or IAM User with a policy containing the s3:getObject permission.

Property Description
bucket The AWS S3 bucket name.
key The AWS auth key which has access to the bucket. (optional)
secret The AWS secret which matches the key. (optional)

Using an IAM Role.
Omit the credentials.

{  
   "awsAuthorization":{  
      "bucket":"my.aws.bucket"
   }
}

Using an AWS User.

{  
   "awsAuthorization":{  
      "bucket":"my.aws.bucket",
      "key":"AWS_ACCESS_KEY_ID",
      "secret":"AWS_SECRET_KEY"
   }
}

backend

The base URL of the web folder where your images are stored. You may use this option for a publicly available AWS S3 bucket. (default: http://s3.amazonaws.com)

See awsAuthorization for private S3 buckets.

Set the backend to http://images.example.com.

{
   "backend": "http://images.example.com"
}

Set the backend to https://images.example.com.

{
   "backend": "https://images.example.com"
}

backendTimeout

The number of seconds to wait for a backend request to finish. (default: 15)

Set the backend timeout to 30 seconds.

{
   "backendTimeout": 30
}

backendConnectTimeout

The number of seconds to wait while trying to connect to the backend. (default: 5)

Set the backend connect timeout to 5 seconds.

{
   "backendConnectTimeout": 5
}

bucketsAllowed

Restrict the bucket parameter to a preset list of approved buckets.

TIP

Leaving bucketsAllowed empty will allow any bucket to be used.

Limit the use of the bucket parameter to three different buckets.

{  
   "bucketsAllowed": [
        "my.s3.bucket",
        "my.s3.bucket2",
        "my.s3.bucket3"
    ]
}

cache

There are two types of cache storage: memory-based (default) and disk-based. There is also an option to disable caching.

To enable disk cache attach one or more volumes to your instance and set the cache option to "disk". All attached volumes to the instance will be automatically mounted and formatted for use. Formatting may take some time.

Property Description
memory Cache all images in memory. (default)
disk Cache all images on the disk.
none Disable all caching.
originOnly Cache only the original images in memory. Does not support disk cache.

WARNING

Disk cache is for advanced use only. Disk cache requires a large amount of disk space to keep a high hit-rate, otherwise performance will be degraded.

Enable disk cache.

{  
   "cache":"disk"
}

Disable caching completely.

{  
   "cache":"none"
}

cacheControl

Imagizer caching is controlled by the Cache-Control header on origin images. The Browser Cache TTL and Server Cache TTL will only be applied when there is no Cache-Control header present on origin images or the override value is set to true.

Property Description
override When true override the origin Cache-Control header (default: false)
browserCacheTtl Specifies the maximum time in seconds that the image is cached on the client side. This is the max-age directive. (Specified in seconds, default: 10 minutes)
serverCacheTtl Specifies the maximum time in seconds that the image is cached on the server side in Imagizer. This is the s-maxage directive. (Specified in seconds, default: 30 days)

Override the cache control headers and set browser cache to 10 minutes and the Imagizer server cache to 30 days.

{  
   "cacheControl":{
      "override": true,
      "browserCacheTtl": 1800,
      "serverCacheTtl": 2678400
   }
}

consul

Register with a Consul agent on boot.
More Information

When configured, Imagizer will send a PUT request to the given endpoint with the given payload on boot. In case of failure, Imagizer will retry the request up to three times. The instance will continue to boot on failure with error log entries.

The properties of the payload can be auto-filled by Imagizer. Use one of the following variables.

Name Description
$ip The IP of the instance.
$host The hostname of the instance.
$awsPublicIp The AWS public IP address of the instance.
$awsPublicHost The AWS public hostname of the instance.
{  
   "consul":{  
      "endpoint":"http://0.0.0.0:8500/v1/catalog/register",
      "payload":{  
         "Datacenter":"dc1",
         "Node":"$host",
         "Address":"$ip",
         "Service":{  
            "Service":"imagizer",
            "Port":80
         }
      }
   }
}

cluster

Enable cluster mode which uses the Consistent Hashing with the Bounded Loads algorithm to distribute the load across several Imagizer instances.

See more information on Consistent Hashing with Bounded Loads.

TIP

The cluster configuration requires nodes to be able to communicate with each other through ports 17001 and 17006. Make sure these ports are open only to the Imagizer nodes in the cluster.

Property Description
enable When true, Imagizer will load balance requests across Imagizer instances specified in the nodes property.
hashBalanceFactor Specify the balancing factor for bounded-load consistent hashing. (default: 125)
awsAutoScaleSync When true, Imagizer will keep the nodes property synced with the current AWS auto-scaling group. (default: false)
includeQueryStringInHash When true use the whole URL including parameters (not only the path part of the request) to build the load balancer hash. (default: true)
nodes An array of Imagizer hosts (hostnames or IP addresses) of all the Imagizer nodes in the cluster.

Enable cluster mode across an AWS AutoScaling group.

{
  "cluster":{
    "enable": true,
    "awsAutoScaleSync": true
  }
}

Enable cluster mode across a set list of Imagizer nodes.

{
  "cluster":{
    "enable": true,
    "nodes": [
      "10.0.0.1",
      "10.0.0.2",
      "10.0.0.3",
      "10.0.0.4"
    ]
  }
}

defaultImages

Use default image in place of missing images and/or errors.

Property Description
missing Image to be used instead of 404 error code.
error Image to be used instead of all other errors.
shouldProcess If true process the default image using the given image parameters. (default: false)
return200Response If true return a 200 response code with the default images. If false return the error code with the default image. (default: true)

Setup default error images.

{
   "defaultImages": {
      "missing": "http://example.com/404image.jpg",
      "error": "http://example.com/errorimage.jpg",
      "shouldProcess": false,
      "return200Response": true
   }
}

defaultImageParameters

Imagizer allows for global image parameters to be set on every request. This feature is handy for adding Imagizer processing like compression and formatting to all images without the need to modify image URLs.

TIP

These values may be overridden from client supplied URL parameters.

Globally set quality to 75, format to auto, and limit the max image width to 1000px.

{  
   "defaultImageParams":{  
      "quality":75,
      "format":"auto",
      "width":1000
   }
}

defaultMobileImageParameters

Similar to the Default Image Parameters, Default Mobile Image Parameters are globally set for all image requests coming from a mobile device. These parameters will override any of the Default Image Parameters.

TIP

These values may be overridden from client supplied URL parameters.

WARNING

Seperate cache for mobile devices must be enabled from these parameters to work correctly.

Globally for mobile devices set quality to 65 and limit the max image width to 800px.

{  
   "defaultMobileImageParams":{  
      "quality":75,
      "width":800
   }
}

displayWelcomePage

When true display the Imagizer welcome page on the root path /. (default: true)

{  
   "displayWelcomePage": true
}

enablePostToProcess

Enable POST requests port 80. See the POST Requests guide for more information.

{  
   "enablePostToProcess": true
}

fallbackBackend

The fallback backend is used when the primary backend returns an error. The use of the fallback backend is optional. By default the fallback backend is used when a 403 or 404 is received from the primary backend. See fallbackErrorCodes below to customize the error codes.

Property Description
backend The backend upstream server url.
backendTimeout The backend fetch timeout. (default: 30 sec)
backendConnectTimeout The backend fetch connect timeout. (default: 3 sec)
awsAuthorization An AWS Authorization object. (optional)
fallbackErrorCodes An array of http error codes to trigger the use of the fallback backend. (default: [404, 403])

Use a public fallback backend.

{
    "fallbackBackend": {
        "backend": "http://my.backup.s3.amazomaws.com"
    }
}

Use a private S3 fallback bucket.

{
    "fallbackBackend": {
        "awsAuthorization":{  
              "bucket":"my.backup",
              "key":"AWS_ACCESS_KEY_ID",
              "secret":"AWS_SECRET_KEY"
        }
    }
}

faceDetectionWidth

Determines the image width for the preprocessing of an image before applying facial detection. (default: 600)

{
   "faceDetectionWidth": 600
}

hostsAllowed

By default the Imagizer Image API allows any origins to be passed through the origin and source_url parameter. This can be restricted to a preset list of approved backend origins.

TIP

Leaving hostsAllowed empty will allow any origin to be used.

Limit the use of the hostname parameter to three different backends.

{  
   "hostsAllowed": [
        "bucket.s3.amazonaws.com",
        "bucket2.s3.amazonaws.com",
        "bucket3.s3.amazonaws.com"
    ]
}

ignoreCertWarnings

When true, ignore SSL errors from the backend.

{  
   "ignoreCertWarnings": true
}

ignoreFormats

An array of image formats which should be ignored. No image process will take pace on these images. The original image will be passed through untouched.

{  
   "ignoreFormats": [
      "gif",
      "svg"
   ]
}

imageParamsAllowed

By default the Imagizer Image API allows any combination of request parameters. Restrict the requests parameters to a preset list of combinations using the imageParamsAllowed property.

TIP

Leaving imageParamsAllowed empty will allow any number of Image API parameter combinations allowed

Limit the use of the image API to thumbnails of 120px wide and large images of 1000px wide with a watermarked logo image

{  
   "imageParamsAllowed": [
        {
            "width": 120
        },
        {
            "width": 500,
            "height": 500,
            "mark": "http://example.com/watermark.png",
            "mark_pos": "bottom,right",
            "mark_offset": 2
        }   
    ]
}

logging

Imagizer supports logging to a remote syslog server and AWS CloudWatch. The web server access log and error log along with the application log will be sent. The application log supports four levels (debug, info, warn, error) of logging. By default info, warning, and error logs will be sent. Log severity will be set accordingly. Facility will default to "local7"

Property Description
enable Enables web server and application logging to syslog. (default: false)
appLogLevel Defines the application level logging. (debug, info, warn, error) (default: info)
facility Sets facility of syslog messages, as defined in RFC 3164. (Default: local7)
syslogServer Defines the address of a syslog server. The address can be specified as a IP address.
syslogPort Defines the port of a syslog server. (default: 514)
CloudWatch Defines AWS Cloud Watch configuration.

cloudWatch

Cloud Watch Logging may be enable and authorized using either an IAM role attached to your Imagizer instance or AWS user credentials.

Property Description
enable Enables web server and application logging to Cloud Watch. (default: false)
region The AWS Cloud Watch region to send logs to.
key The AWS auth key which has access to the Cloud Watch. (optional)
secret The AWS secret which matches the key. (optional)

TIP

You must first create an AWS IAM Role or IAM User with a policy containing the logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents, and logs:DescribeLogStreams permissions.

WARNING

One logging method at a time is supported. Cloud Watch logging will not work when syslog logging is enabled.

Enable CloudWatch Logging using IAM Role

{  
   "logging":{  
      "enable": true,
      "appLogLevel": "info",
      "cloudWatch": {
         "enable":true
      }
   }
}

Enable CloudWatch Logging using AWS credentials

{  
   "logging":{  
      "enable": true,
      "appLogLevel": "info",
      "cloudWatch": {
         "enable":true,
         "key": "XXXXXXXXXXXXXXXXX",
         "secret": "XXXXXXXXXXXXXXXXX"
      }
   }
}

datadog

Imagizer supports logging to Datadog. Datadog will receive the web server's (Nginx) and Imagizer application logs.

Property Description
enable When true Imagizer will send logs to Datadog. (default: false)
key Your Datadog API key.

Enable DataDog Logging

{  
   "logging":{  
      "enable": true,
      "appLogLevel": "warn",
      "dataDog": {
         "enable":true,
         "key": "XXXXXXXXXXXXXXXXX"
      }
   }
}

maxImageDimensions

Limit the maximum dimensions allowed for images. This limits the original image as well as any processed images. By default, Imagizer will limit the dimensions of images to 5000px by 5000px.

Parameter Description
enable When true enable the Max Image Dimensions limit.
width The max allowed width of an image.
height The max allowed height of an image.

Limit the max dimensions of images to 3500px by 3500px

{
   "maxImageDimensions":{  
      "enable":true,
      "width":3500,
      "height":3500
   }
}

passThroughHeaders

Imagizer will pass through request headers to the origin image only when specified in the config. Use the passThroughHeaders parameter to specify an array of headers to be use on each origin image request. Wildcards (*) are supported to match multiple headers.

Pass the Host, Origin, and X-My-Custom-Header headers through to the origin.

{  
   "passThroughHeaders":[  
      "Host",
      "Origin",
      "X-My-Custom-Header"
   ]
}

Pass all request headers

{
   "passThroughHeaders":[  
      "*"
   ]
}

stats

Imagizer collects and stores system and application stats. These stats are available through the Admin API at any time. Optionally, support for Ganglia, Datadog, and cloudWatch are available.

ganglia

Send all stats to Ganglia. Stats are sent once a minute.

WARNING

AWS EC2 does not support multicast. Use the default udp protocol.

Property Description
enable If true send all stats to ganglia.
host The ganglia host.
port The ganglia port (default: 8649).
protocol The protocol to use when sending stats to ganglia. (udp or multicast) (default: udp)

Enable Ganglia Stats

{  
   "stats":{
      "ganglia":{  
         "host":"ganglia.example.com",
         "port":8649,
         "prototal":"udp"
      }
   }
}

cloudWatch

Send all stats to AWS CloudWatch. Stats are sent once a minute.

CloudWatch stats may be authorized using either an IAM role attached to your Imagizer instance or AWS user credentials.

Property Description
enable Enables Cloud Watch stats. (default: false)
region The AWS Cloud Watch region to send stats to.
key The AWS auth key which has access to the Cloud Watch. (optional)
secret The AWS secret which matches the key. (optional)

TIP

You must first create an AWS IAM Role or IAM User with a policy containing the cloudwatch:PutMetricData permission.

Enable CloudWatch using IAM Role.

{  
   "stats":{  
      "cloudWatch":{  
         "enable":"true",
         "region":"us-east-1"
      }
   }
}

Enable CloudWatch Metrics using AWS credentials.

{  
   "stats":{  
      "enable": true,
      "cloudWatch": {
         "enable":true,
         "key": "XXXXXXXXXXXXXXXXX",
         "secret": "XXXXXXXXXXXXXXXXX"
      }
   }
}

datadog

Imagizer supports Datadog metrics. Datadog will receive system stats on categories such as CPU, memory, disk, and processes, along with all the Imagizer application stats.

Property Description
enable When true Imagizer will send stats to Datadog (default: false).
key Your Datadog API key.
namespace Prepend all stats with this namespace string.
tags An array of tags which will be applied to all Datadog metrics and logs. https://docs.datadoghq.com/getting_started/tagging

Enable DataDog Stats

{  
   "stats":{  
      "enable": true,
      "appLogLevel": "warn",
      "dataDog": {
         "enable":true,
         "key": "XXXXXXXXXXXXXXXXX",
         "namespace": "imagizer",
         "tags": [
            "region:us-east1",
            "env:production"
         ]
      }
   }
}

secureWebProxy

Using a secure web proxy will send all secure (https) origin image requests to a specified proxy.

TIP

For non-https traffic, see webProxy.

All https traffic will pass through my-proxy-example.com on port 8282.

{  
   "secureWebProxy":{  
      "host":"my-proxy-example.com",
      "port":"8282"
   }
}

separateMobileCache

This will allow for the caching of two different objects for each image url, one for the mobile version and one for the desktop version. Separate mobile cache allows for features such as Default Mobile Image Parameters.

Enable Separate Mobile Cache

{  
    "separateMobileCache": true
}

separateWebpCache

This will allow for the caching of two different objects for each image url, one for clients which support webp and one for clients that do not support webp. Webp support is detected based on the Accept header. Separate Webp cache allows for features such as Auto Format.

Enable Webp Cache

{  
    "separateWebpCache": true
}

separateHostCache

Enable Host Cache

Use separate cache zones for each hostname used. (default: false)

{  
    "separateHostCache": true
}

upscaleAllowed

Allow Imagizer to upscale images beyond their original dimensions. (default: false)

Allow upscaling of images.

{
  "upscaleAllowed": true
}

urlRewrites

Url rewrites will perform search and replace on the request url before preceding to image processing. This will allow for changes to both the path and the query parameters on all requests passed to Imagizer.

Url Rewrites allow for both string and regex(PCRE) search and replace. Multiple rewrites are allowed.

Property Description
search The value being searched for, otherwise known as the needle.
replace The replacement value that replaces found search values.
includeQueryString If true include the query string in the search and replace. (default: false)
isRegex If true treat the search string as a regex. (default: false)

Modify the image path of all requests. Replace "is/image" with "product/published".

/is/image/myimage1.jpg?width=400 => /product/published/myimage1.jpg?width=400

{
   "urlRewrites":[  
      {  
         "search":"is/image",
         "replace":"product/published"
      }
   ]
}

Migrate previously used image optimizer URLs to Imagizer formatted API

/images/myimage1.jpg?resize=300x400 => /images/myimage1.jpg?width=300&height=400

{  
   "urlRewrites":[  
      {  
         "search":"/resize=([0-9]+)x([0-9]+)/",
         "replace":"width=$1&height=$2",
         "includeQueryString":true,
         "isRegex":true
      }
   ]
}

webProxy

Using a web proxy will send all origin image requests to a specified proxy.

TIP

For https traffic, see secureWebProxy.

All http traffic will pass through my-proxy-example.com on port 8281.

{  
   "webProxy":{  
      "host":"my-proxy-example.com",
      "port":"8181"
   }
}