root

go-dims

go-dims is a fast, lightweight HTTP microservice for real-time image processing, written in Go and powered by libvips. It’s a modern, drop-in replacement for mod_dims, fully compatible with the DIMS API.

Designed for use in websites, publishing platforms, and CDN-backed applications, go-dims helps you generate image variants on-the-fly — without the need for precomputing or storing multiple renditions.

✨ Features

• ✅ Resize, crop, rotate, flip, grayscale, and more
• ✅ Add watermarks
• ✅ Strip metadata, control quality, convert formats
• ✅ Export in JPEG, PNG, and WebP
• ✅ Sign and validate requests for secure public access
• ✅ Load images from file, a URL, or S3
• ✅ Deploy as a Docker image, or AWS Lambda function
• ✅ Drop-in replacement for mod_dims

Why use go-dims?

💡 On-demand image transformation

• Resize, crop, convert formats, and more — all defined via URL.
• Built-in support for signatures to prevent misuse and ensure cacheability.
• Avoid bloated image storage by rendering variants only when requested.

⚡ Fast, minimal, portable

• Built on libvips, the fastest image processing library.
• Single static binary with zero runtime dependencies.
• Docker image is just ~11MB compressed, standalone binary is just ~9MB.
• Built for linux/amd64 and linux/arm64.

🔒 Secure

• Clean, HMAC-SHA256 signed URLs to ensure safe, tamperproof transformations.
• The go-dims Docker image is built from scratch with a statically compiled binary, no shell, no package manager, and no extraneous libraries — minimizing the attack surface.

🛠 Developer-friendly

• Easily define image variants directly in frontend code or templates.
• Uses minimal memory — perfect for local development.
• Runs equally well locally, in containers, or as an AWS Lambda function.

📦 Deployment Options

• Static binary: Just download and run.
• Docker: Launch anywhere in seconds.
• AWS Lambda: Compile and deploy as a fast, small Lambda function.

🚀 Getting Started

Run locally in development mode (no signature required):

docker run \
  -e DIMS_DEVELOPMENT_MODE=true \
  -e DIMS_DEBUG_MODE=true \
  -e DIMS_SIGNING_KEY=devmode \
  -p 8080:8080 \
  ghcr.io/beetlebugorg/go-dims serve

Then, open your browser and navigate to:

http://127.0.0.1:8080/v5/resize/100x100/?url=https://images.pexels.com/photos/1539116/pexels-photo-1539116.jpeg

⛶ Supported Transformations

📸 Examples

Original

Thumbnail, then sharpen

Thumbnail resize to 200x200 pixels, keeping the aspect ratio and cropping the image if necessary.

http://localhost:8080/v5/thumbnail/200x200/sharpen/1x2/?url=pexels-photo-1539116.jpeg

Resize with center crop

http://localhost:8080/v5/resize/200x200/crop/200x100+0+25%25/sharpen/1x2?url=pexels-photo-1539116.jpeg

Watermark

Add a watermark to the bottom right corner of the image.

http://localhost:8080/v5/thumbnail/200x200/sharpen/1x2/watermark/1,.35,se?url=pexels-photo-1539116.jpeg&overlay=hex-lab.png

🔑 Generating a Signed URL

Use the built-in CLI to generate secure, signed URLs:

❯ ./build/dims sign --key-file=signing-key.txt "http://localhost:8080/v5/resize/200x200/?url=pexels-photo-1539116.jpeg"

http://localhost:8080/v5/resize/200x200/?sig=33032505c0f4b3d43674b49575d9e379470ac6d7e7fa3e055b248802ee6867&url=pexels-photo-1539116.jpeg

License

This project is licensed under the MIT license. See the LICENSE file for details.

For software used by this project, and their licenses, see the NOTICE file.