# imgproxy — Fast Secure Image Processing Server in Go

> Resize, crop, and convert images on-the-fly with imgproxy. A blazing-fast Go server powered by libvips for production-grade image transformation at scale.

## Install

Save in your project root:

# imgproxy — Fast Secure Image Processing Server in Go

## Quick Use
```bash
docker run -p 8080:8080 
  -e IMGPROXY_KEY=your_hex_key 
  -e IMGPROXY_SALT=your_hex_salt 
  darthsim/imgproxy
# Resize: http://localhost:8080/insecure/rs:fill:300:200/plain/https://example.com/photo.jpg
```

## Introduction
imgproxy is a fast, secure standalone server for resizing, cropping, and converting remote images. Written in Go and powered by libvips, it processes images on-the-fly without storing anything on disk. It is designed to be a drop-in image CDN backend that protects your infrastructure from image-based attacks while delivering optimized images at scale.

## What imgproxy Does
- Resizes, crops, rotates, and watermarks images via URL-based processing pipelines
- Converts between formats including WebP, AVIF, JPEG, PNG, GIF, and HEIC automatically
- Signs URLs with HMAC to prevent unauthorized image processing requests
- Fetches source images from HTTP, S3, GCS, Azure Blob, or local filesystem
- Serves responsive images with automatic format negotiation based on Accept headers

## Architecture Overview
imgproxy runs as a single stateless Go binary behind a reverse proxy or CDN. Incoming requests encode processing instructions in the URL path. The server fetches the source image, pipes it through libvips for transformation, and streams the result directly to the client. There is no disk cache by default — images are processed in memory. A URL signature scheme using HMAC-SHA256 prevents abuse. The server supports graceful shutdown, health checks, and Prometheus metrics.

## Self-Hosting & Configuration
- Deploy via Docker or prebuilt binaries; single container, no dependencies
- Set `IMGPROXY_KEY` and `IMGPROXY_SALT` env vars to enable URL signing
- Configure `IMGPROXY_MAX_SRC_RESOLUTION` to cap maximum source image size
- Enable `IMGPROXY_USE_S3=true` with AWS credentials to fetch from S3 buckets
- Tune `IMGPROXY_CONCURRENCY` and `IMGPROXY_MAX_ANIMATION_FRAMES` for load control

## Key Features
- Processes images in under 50ms for typical web sizes using libvips
- URL signing prevents denial-of-wallet attacks from arbitrary processing requests
- Automatic WebP/AVIF serving based on browser Accept header negotiation
- Supports animated GIF and WebP processing without frame extraction
- Built-in Prometheus metrics and structured JSON logging for observability

## Comparison with Similar Tools
- **Thumbor** — Python-based, slower; imgproxy is 5-10x faster with Go and libvips
- **Cloudinary** — managed SaaS with broader features; imgproxy is free and self-hosted
- **sharp (Node.js)** — library, not a server; imgproxy provides a complete HTTP service
- **Imaginary** — similar Go server; imgproxy has more formats and better security model

## FAQ
**Q: How does URL signing work?**
A: You generate an HMAC-SHA256 signature from the processing path using your key and salt. The signature is prepended to the URL, and imgproxy rejects requests with invalid signatures.

**Q: Can imgproxy replace a CDN?**
A: No — place a CDN like CloudFront or Fastly in front of imgproxy. imgproxy handles transformation; the CDN handles caching and edge distribution.

**Q: Does imgproxy support PDF and SVG?**
A: Yes. It can render PDF pages and SVG files to raster formats for processing.

**Q: What happens if a source image is too large?**
A: imgproxy returns a 422 error if the image exceeds `IMGPROXY_MAX_SRC_RESOLUTION`, protecting against memory exhaustion.

## Sources
- https://github.com/imgproxy/imgproxy
- https://docs.imgproxy.net

---
Source: https://tokrepo.com/en/workflows/74551bbd-3939-11f1-9bc6-00163e2b0d79
Author: AI Open Source