Dynamic Image Manipulation Service

Dims is an HTTP microservice for dynamic image manipulation written in Go. Use dims to resize images on-the-fly avoiding the costly process of pre-computing and storing images.

If you're building a website you probably need a service like dims to resize images for publishing. With dims you can do that programmatically, on-the-fly.

It can reduce costs by:

• only computing images when you need them.
• not storing image size renditions.

It can improve your development and publishing experience by:

• allowing your developers to easily define image sizes in their frontend code
• allowing your users to publish images without manipulating them first

License

DIMS User Guide © 2024 by Jeremy Collins is licensed under CC BY-NC-SA 4.0.

Getting Started

Running with Docker

For most use cases it's probably best to stick with the containers to avoid managing Imagemagick. Many Linux distributions only distribute Imagemagick 6, and go-dims requires Imagemagick 7.

Execute the following to run in development mode on port 8080:

$ docker run -e DIMS_SIGNING_KEY=devmode -p 8080:8080 ghcr.io/beetlebugorg/go-dims serve --dev

Development mode will disable signature verification so the signing key doesn't really matter, but it's still required.

You should have dims running now:

❯ curl http://127.0.0.1:8080/dims-status
ALIVE

If everything is working you should see a thumbnail below (after refreshing). If you see alt text, make sure dims is started.

Compiling from source

If you tried to compile mod-dims, go-dims' predecessor, circa 2009 or so it was painful. Things got better over time with containers and autoconf improvements but it was never easy. The process got a lot easier with go-dims.

You still need to install Imagemagick and its dependencies to compile go-dims but these days you can get everything you need to compile it on macOS using brew:

$ brew install imagemagick

On Linux you'll need to find an Imagemagick 7 package or compile it from source. It's not hard to compile, it just takes a while.

Then you can compile and run go-dims:

$ git clone https://github.com/beetlebugorg/go-dims.git
$ cd go-dims
$ go build cmd/dims/main.go
$ DIMS_SIGNING_KEY=devmode ./build/bin/dims serve --dev

Running

If you got here from Getting Started you may already have dims running. This section is about running dims in production.

Dims is designed to be an origin server behind a CDN. For smaller, or private, installations you can run it behind a cache such as Varnish, or Apache httpd with mod_cache.

Amazon Web Services

Serverless operation is supported for AWS Lambda Functional URL, and S3 Object Lambda.

Each mode offers different trade-offs.

The Lambda Functional URL mode allows you to resize images from any HTTP source, but also exposes that source to the client. This may not be ideal such as in Digital Asset Management systems.

The S3 Object Lambda mode doesn't expose the origin and allows you to keep your S3 bucket completely private. However, it only works with S3 as the source.

AWS S3 Object Lambda

CloudFront -> S3 Object Lambda Access Point -> S3 Access Point -> S3

AWS Lambda Functional URL

CloudFront -> Lambda Functional URL -> Image Source (http, s3, etc)

Local

    - [Docker]()

Resources

    - [Disk Usage]()
    - [Memory Usage]()

Configuration

You can configure dims through environment variables.

$ DIMS_SIGNING_KEY="mysecret" DIMS_ERROR_BACKGROUND="#ffffff" ./dims serve

There are not many settings, and only one required setting (DIMS_SIGNING_KEY). Most of the settings configure how dims returns cache control headers.

Signing Requests

All image manipulation requests are required to be signed with a secret shared between your web framework, and dims.

If you encounter key mismatch errors ensure that both the signing key and signing algorithm are the same between the client, and dims.

DIMS_SIGNING_KEY

The DIMS_SIGNING_KEY is used to verify the signature of each image manipulation request.

Make sure to set this to a secure random value with at least 32 characters. Use your favorite password manager to generate something strong.

Keep this value a secret. Don't check it into revision control. You'll need it to sign your dims image urls.

This setting is required.

Cache Control Headers

Cache control can be confusing but it's also super important to get it right. It impacts not only the load on your dims servers but it also affects your Lighthouse scores.

The defaults used by dims have been used in production for over 10 years. They have been optimized for good Lighthouse scores. These settings are for high traffic sites with lots of image resizing. If that's not your use case, these settings may not be right for you.

DIMS_CACHE_CONTROL_DEFAULT

Use this to set how long clients should cache manipulated images.

This is the max-age in seconds in the Cache-Control header.

This default is 31536000 seconds.

That's one year, which is basically forever. That's ok though, cache busting is implicit in the URL so any image manipulation changes the signature, busting the cache!

The was DimsCacheExpire in mod-dims.

DIMS_CACHE_CONTROL_ERROR

Use this to set how long to cache error images.

This is the max-age in seconds in the Cache-Control header.

This default is 60 seconds.

You don't want to beat up dims serving generated error images, but you also want clients to retry and hopefully get a valid image.

Let's see how this manifests. First start up dims, setting the expire to 10 seconds.

$ DIMS_CACHE_CONTROL_ERROR=11 ./dims serve 

Now let's simulate a bad request:

❯ curl -v "http://127.0.0.1:8080/dims4/default/1/resize/1x1/?url=1"
> GET /dims4/default/1/resize/1x1/?url=1 HTTP/1.1
> 
< HTTP/1.1 500 Internal Server Error
< Cache-Control: max-age=11, public
< Content-Length: 0
< Content-Type: image/jpeg
< Expires: Wed, 14 Feb 2024 00:00:11 GMT
< Date: Wed, 14 Feb 2024 00:00:00 GMT

This error image will expire after 11 seconds.

The was DimsNoImageCacheExpire in mod-dims.

DIMS_CACHE_CONTROL_USE_ORIGIN

Use this to delegate max-age to the origin.

The default is false.

You can use this to exercise more control over cache control headers. For example if you're storing images in S3 you can can set cache-control headers for individual files.

You should only set this to true if you control the origin for your images, and you have a need for more fine grained control over max-age.

If you do not control the origin then setting this to true puts you at risk that the origin owner sets max-age too high or two low for your needs. Too low and you risk DDOSing yourself.

DIMS_CACHE_CONTROL_MIN

Use this to set a minimum age from trusted origins.

The default is 0.

This only has an effect when DIMS_CACHE_CONTROL_USE_ORIGIN is set to true.

If you trust the origin but you still need a bit of a protection from misconfiguration or misuse, this is the setting for you.

DIMS_CACHE_CONTROL_MAX

Use this to set a maximum age from trusted origins.

The default is 0. This disables maximum value checks.

This only has an effect when DIMS_CACHE_CONTROL_USE_ORIGIN is set to true.

Other Settings

Occasionally useful settings that can probably be left as-is, except for the error color setting, change that one.

DIMS_ERROR_BACKGROUND

This sets the background color of the error image.

The default is #5adafd:

The error image may be sent because:

• dims was unable to download the source image
• imagemagick was unable to resize the image
• memory or resource pressure

Think of it as the error color for dims. You don't want to see it but when you do you probably want to check your logs to find out why.

If you're looking for a way to set a error image, that doesn't exist anymore. It was called the NOIMAGE image in mod-dims. The error image is now generated automatically using Imagemagick's PixelWand.

DIMS_STRIP_METADATA

This enables, or disables metadata removal after image manipulation.

The default is true.

Enabling this will remove all profile and Exif data from all images served by dims. This is usually what you want but if you're using dims for a DAM (Digital Asset Management) solution you may want to control which images you remove data from.

If you disable this you can use the strip operation to remove profiles per image.

DIMS_INCLUDE_DISPOSITION

This enables the Content-Disposition header.

The default is false.

When you enable this the Content-Disposition header like below will be included in every response:

Content-Disposition: inline; filename=<filename>

If you want to trigger an image to be downloaded you need that to be attachment; filename=<filename>. You can get that by sending the download argument in your request (?url=...&download=1).

DIMS_DOWNLOAD_TIMEOUT

The maximum time an origin image download is allowed before it is cancelled.

The default is 3000. This is in milliseconds.

DIMS_DEFAULT_OUTPUT_FORMAT

The default image format to convert images to if one is not provided.

This is not set by default.

You may find that you want to force all images to be a certain type such as webp. This setting can help but keep in mind that if the image request also includes a format command that will take precedence.

DIMS_OUTPUT_FORMAT_EXCLUDE

Image formats that will not be converted to the default output format.

This is not set by default.

Provide as a comma delimited list: GIF,SVG

mod-dims

The mod-dims and go-dims configurations are largely the same. go-dims gives some settings better names, and removes unnecessary settings.

This page documents those differences and how to migrate. It's mostly just naming.

New

Since go-dims has a new signing algorithm we added DIMS_SIGNING_ALGORITHM. Set this to md5 for compatiblity with mod-dims.

Changed

DimsClient was removed. Each option it had is now available globally.

The DimsClient setting had a lot of options:

<appId> <noImageUrl> <cache control max-age> <edge control downstream-ttl> <trustSource?> <minSourceCache> <maxSourceCache> <password>

Here is how they map to go-dims settings:

• <appId> is now DIMS_CLIENT_ID
• <noImageUrl> is now DIMS_ERROR_BACKGROUND
• <cache control max-age> is now DIMS_CACHE_CONTROL_DEFAULT
• <edge control downstream-ttl> is now DIMS_EDGE_CONTROL_DOWNSTREAM_TTL
• <trustedSource> is now DIMS_CACHE_CONTROL_USE_ORIGIN
• <minSourceCache> is now DIMS_CACHE_CONTROL_MIN
• <maxSourceCache> is now DIMS_CACHE_CONTROL_MAX
• <password> is now DIMS_SIGNING_KEY

Renamed

• DimsCacheExpire to DIMS_CACHE_CONTROL_DEFAULT
• DimsNoImageCacheExpire to DIMS_CACHE_CONTROL_ERROR

Moved

All settings related to Imagemagick were removed. They didn't disappear though. You can set everything mod-dims could using Imagemagick environment variables.

See the Imagemagick documentation for settings.

• DimsImagemagickTimeout
• DimsImagemagickMemorySize
• DimsImagemagickAreaSize
• DimsImagemagickMapSize
• DimsImagemagickDiskSize

Removed

• DimsDefaultImageURL
• DimsAddWhitelist
• DimsDisableEncodedFetch
• DimsUserAgentEnabled
• DimsUserAgentOverride
• DimsOptimizeResize

Example: dims.conf

DimsDownloadTimeout 60000
DimsImagemagickTimeout 20000

# DimsClient <appId> <noImageUrl> <cache control max-age> <edge control downstream-ttl> <trustSource?> <minSourceCache> <maxSourceCache> <password>
DimsAddClient TEST http://placehold.it/350x150 604800 604800 trust 604800 604800 t3st

DimsDefaultImageURL http://placehold.it/350x150
DimsCacheExpire 604800
DimsNoImageCacheExpire 60
DimsDefaultImagePrefix

DimsAddWhitelist www.google.com

/v4/dims Endpoint

/v4/dims/<clientId>/<signature>/<timestamp>/<commands>.../?url=<image>

The dims endpoint lets you crop, resize, and apply other transformations to images.

An image manipulation request is made up of one or more commands that will transform an image, such as resize/100x100. These commands will be applied on the image provided in the url parameter. They are applied in the order they appear in the URL.

Let's break down the example we used in the Getting Started section:

/v4/dims/default/6d3dcb6/2147483647/resize/100x100/?url=https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg

Breaking the request down into its parts we get the following:

URL:

Query String:

Error Handling

This endpoint will always return an image. When a command fails dims will return an auto-generated image using the background color defined in the DIMS_ERROR_BACKGROUND environment variable.

The auto-generated error image will be resized and/or cropped to match the requested image so it'll fit nicely in the space where the original image would have been.

Signing

All requests to this endpoint must be signed. Signing requests ensures that the image request has not been changed.

The signature is a MD5-56 hash of:

• timestamp
• signingKey
• imageCommands
• imageUrl.

Those values should be concatenated together without any spaces or other characters between them, and then hashed.

Note:

• imageCommands should not have a preceding slash but should include a trailing slash if included in the URL. (/).

  • ✅️resize/100x100/crop/10x10+25+25

  • ✅️resize/100x100/crop/10x10+25+25/

  • ❌️/resize/100x100/crop/10x10+25+25/

  • ❌️/resize/100x100/crop/10x10+25+25

• imageUrl should not be url encoded.

  • ✅️https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg

  • ❌️https%3A%2F%2Fimages.pexels.com%2Fphotos%2F1539116%2Fpexels-photo-1539116.jpeg

• timestamp is a unix timestamp (seconds since epoch).

Bringing that all together, here is an example of how to sign a request using the example from above:

❯ echo -n "2147483647mysecretresize/100x100https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg" | md5 | cut -b 1-7
6d3dcb6

We've wrapped this up into a command to make signing and validating requests easier.

Use the sign command to sign a request by passing in a URL to sign, and setting the signing key in the DIMS_SIGNING_KEY environment variable.

The signature part of your URL does not need to be valid but must be 7 characters long. The sign command will replace it with a valid signature and output the result.

❯ docker run -e DIMS_SIGNING_KEY=mysecret ghcr.io/beetlebugorg/go-dims sign 'https://myhost.com/v4/dims/default/1234567/2147483647/resize/100x100/?url=https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg' --dev
Image to be transformed:

https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg

Transformation commands found:

resize('100x100')

http://localhost:8080/v4/dims/default/6d3dcb6/2147483647/resize/100x100/?url=https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg

Commands

Commands are used to transform your origin image. Each command takes a single argument, and performs a single manipulation such as resizing or cropping the origin image.

Commands can be combined to perform more complex manipulations. They are processed in the order they appear in the url.

Resize

This command will resize an image to the size specified in the image geometry.

The resize image geometry format is <width>x<height> which will resize an image while preserving its aspect ratio. Since the aspect ratio is preserved the resulting image may be smaller than requested.

If you need an exact size you can add the ! symbol to your request, such as 100x100!. This will not preserve aspect ratios and may cause your image to compress or stretch. Listing 1 shows how the image can be stretched, Listing 2 shows it without the !.

Listing 1 - /v4/.../resize/100x100!/?url=... results in a 100x100 image

Listing 2 - /v4/.../resize/100x100/?url=... results in a 80x100 image

Some geometry formats use symbols that need to be escaped so make sure to always escape command arguments.

An example would be resizing by percentage. We're can't have % in the url so it needs to be escaped. For example, in resize/15%25, the %25 is the url encoding for %.

Crop

This command will crop an image to the size, and at the location, specified in the image geometry.

The crop image geometry format is <width>x<height>+{x}+{y} which will crop an image to the size specified width and height offset by x and y.

The width plus x offset must be less than the width of the image.

The height plus y offset must be less than the height of the image.

The +{x}+{y} is optional, they will both default to 0.

Thumbnail

This command is the same as resize/<width>x<height>^/strip/true.

This command is deprecated and will be removed in a future release.

Legacy Thumbnail

This command is similar to thumbnail and resize but it will crop the image to the width and height from the center of the image.

This command is the equivalent to running gravity/center/resize/<width>x<height>^/crop/<width>x<height>+0+0.

Format

This command will convert the origin image into the format provided by format_ext.

The formats available for conversion are:

• webp
• png
• jpg
• gif

Quality

This command adjusts the amount of compression for JPG, PNG, and TIFF images. It's named quality because it can directly affect the quality of the resulting image.

It accepts a value between:

• 1 - lowest quality, highest compression
• 100 - highest quality, lowest compression

Rotate

This command will rotate an image.

This should be a value between 0 and 360. You can provide decimal places, like 25.75, but for web use cases I can't imagine anyone is going to notice.

The default rotation is clockwise. Use negative numbers to rotate counter-clockwise.

Sepia

Sharpen

Brightness

Grayscale

This command will set the image colorspace to grayscale when true.

Strip

This command will remove ICC, and Exif profiles.

Use this command to reduce the size of your images. This especially helps when generating thumbnail images as this profile data can become a large percent of the final image once it's been reduced to a thumbnail.

By default dims will strip metadata anyway so this call is a no-op.

However, there are use cases such as DAM solutions where you may not want to strip this data by default. In those cases disable DIMS_STRIP_METADATA globally and call this command when needed.

Invert

This command inverts the colors of an image.

/v5/dims Endpoint

/v5/dims/<commands>.../?url=<image>&clientId=<clientId>&sig=<signature>

The dims endpoint lets you crop, resize, and apply other transformations to images.

An image manipulation request is made up of one or more commands that will transform an image, such as resize/100x100. These commands will be applied on the image provided in the url parameter. They are applied in the order they appear in the URL.

Let's break down the example we used in the Getting Started section:

/v5/dims/resize/100x100/?url=https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg&sign=6d3dcb6&expire=2147483647&clientId=default

Breaking the request down into its parts we get the following:

URL:

Query String:

Error Handling

This endpoint will always return an image. When a command fails dims will return an auto-generated image using the background color defined in the DIMS_ERROR_BACKGROUND environment variable.

The auto-generated error image will be resized and/or cropped to match the requested image so it'll fit nicely in the space where the original image would have been.

Signing

All requests to this endpoint must be signed. Signing requests ensures that the image request has not been changed.

The signature is a HMAC-SHA256-128 of:

• imageCommands
• imageUrl

Those values should be concatenated together without any spaces or other characters between them, and then signed.

Note:

• imageCommands should not have any preceding or trailing slashes (/).

  • ✅️resize/100x100/crop/10x10+25+25

  • ❌️/resize/100x100/crop/10x10+25+25/

• imageUrl should not be url encoded.

  • ✅️https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg

  • ❌️https%3A%2F%2Fimages.pexels.com%2Fphotos%2F1539116%2Fpexels-photo-1539116.jpeg

We've wrapped this up into a command to make signing and validating requests easier.

Use the sign command to sign a request by passing in a URL to sign, and setting the signing key in the DIMS_SIGNING_KEY environment variable.

❯ docker run -e DIMS_SIGNING_KEY=mysecret ghcr.io/beetlebugorg/go-dims sign 'https://myhost.com/v5/dims/resize/100x100/?clientId=default&url=https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg' --dev  

Image to be transformed:

https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg

Transformation commands found:

resize('100x100')

http://localhost:8080/v5/dims/resize/100x100/?clientId=default&url=https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg&sig=325d12cdbcb496ac7c27622b7bb6fb453449b3789dc3fa999996691f18f2dc

Commands

Commands are used to transform your origin image. Each command takes a single argument, and performs a single manipulation such as resizing or cropping the origin image.

Commands can be combined to perform more complex manipulations. They are processed in the order they appear in the url.

Resize

This command will resize an image to the size specified in the image geometry.

The resize image geometry format is <width>x<height> which will resize an image while preserving its aspect ratio. Since the aspect ratio is preserved the resulting image may be smaller than requested.

If you need an exact size you can add the ! symbol to your request, such as 100x100!. This will not preserve aspect ratios and may cause your image to compress or stretch. Listing 1 shows how the image can be stretched, Listing 2 shows it without the !.

Listing 1 - /v4/.../resize/100x100!/?url=... results in a 100x100 image

Listing 2 - /v4/.../resize/100x100/?url=... results in a 80x100 image

Some geometry formats use symbols that need to be escaped so make sure to always escape command arguments.

An example would be resizing by percentage. We're can't have % in the url so it needs to be escaped. For example, in resize/15%25, the %25 is the url encoding for %.

Crop

This command will crop an image to the size, and at the location, specified in the image geometry.

The crop image geometry format is <width>x<height>+{x}+{y} which will crop an image to the size specified width and height offset by x and y.

The width plus x offset must be less than the width of the image.

The height plus y offset must be less than the height of the image.

The +{x}+{y} is optional, they will both default to 0.

Thumbnail

This command is the same as resize/<width>x<height>^/strip/true.

This command is deprecated and will be removed in a future release.

Format

This command will convert the origin image into the format provided by format_ext.

The formats available for conversion are:

• webp
• png
• jpg
• gif

Quality

This command adjusts the amount of compression for JPG, PNG, and TIFF images. It's named quality because it can directly affect the quality of the resulting image.

It accepts a value between:

• 1 - lowest quality, highest compression
• 100 - highest quality, lowest compression

Rotate

This command will rotate an image.

This should be a value between 0 and 360. You can provide decimal places, like 25.75, but for web use cases I can't imagine anyone is going to notice.

The default rotation is clockwise. Use negative numbers to rotate counter-clockwise.

Sepia

Sharpen

Brightness

Grayscale

This command will set the image colorspace to grayscale when true.

Strip

This command will remove ICC, and Exif profiles.

Use this command to reduce the size of your images. This especially helps when generating thumbnail images as this profile data can become a large percent of the final image once it's been reduced to a thumbnail.

By default dims will strip metadata anyway so this call is a no-op.

However, there are use cases such as DAM solutions where you may not want to strip this data by default. In those cases disable DIMS_STRIP_METADATA globally and call this command when needed.

Invert

This command inverts the colors of an image.

Gravity

/status

/health

Resize

This command will resize an image to the size specified in the image geometry.

The resize image geometry format is <width>x<height> which will resize an image while preserving its aspect ratio. Since the aspect ratio is preserved the resulting image may be smaller than requested.

If you need an exact size you can add the ! symbol to your request, such as 100x100!. This will not preserve aspect ratios and may cause your image to compress or stretch. Listing 1 shows how the image can be stretched, Listing 2 shows it without the !.

Listing 1 - /v4/.../resize/100x100!/?url=... results in a 100x100 image

Listing 2 - /v4/.../resize/100x100/?url=... results in a 80x100 image

Some geometry formats use symbols that need to be escaped so make sure to always escape command arguments.

An example would be resizing by percentage. We're can't have % in the url so it needs to be escaped. For example, in resize/15%25, the %25 is the url encoding for %.

Crop

This command will crop an image to the size, and at the location, specified in the image geometry.

The crop image geometry format is <width>x<height>+{x}+{y} which will crop an image to the size specified width and height offset by x and y.

The width plus x offset must be less than the width of the image.

The height plus y offset must be less than the height of the image.

The +{x}+{y} is optional, they will both default to 0.

Thumbnail

This command is the same as resize/<width>x<height>^/strip/true.

This command is deprecated and will be removed in a future release.

Quality

This command adjusts the amount of compression for JPG, PNG, and TIFF images. It's named quality because it can directly affect the quality of the resulting image.

It accepts a value between:

• 1 - lowest quality, highest compression
• 100 - highest quality, lowest compression

Format

This command will convert the origin image into the format provided by format_ext.

The formats available for conversion are:

• webp
• png
• jpg
• gif

Strip

This command will remove ICC, and Exif profiles.

Use this command to reduce the size of your images. This especially helps when generating thumbnail images as this profile data can become a large percent of the final image once it's been reduced to a thumbnail.

By default dims will strip metadata anyway so this call is a no-op.

However, there are use cases such as DAM solutions where you may not want to strip this data by default. In those cases disable DIMS_STRIP_METADATA globally and call this command when needed.

Sharpen

brightness

flipflop

sepia

Grayscale

This command will set the image colorspace to grayscale when true.

Invert

This command inverts the colors of an image.

Rotate

This command will rotate an image.

This should be a value between 0 and 360. You can provide decimal places, like 25.75, but for web use cases I can't imagine anyone is going to notice.

The default rotation is clockwise. Use negative numbers to rotate counter-clockwise.

Legacy Thumbnail

This command is similar to thumbnail and resize but it will crop the image to the width and height from the center of the image.

This command is the equivalent to running gravity/center/resize/<width>x<height>^/crop/<width>x<height>+0+0.

Gravity