Croppix is an open-source image processing service based on Sharp and Smartcrop, allowing dynamic generation of cropped and optimized images directly from URL parameters, with intelligent caching support on AWS S3.

Croppix is designed to be integrated into high-performance websites, serving optimized images directly from a CDN (like CloudFront), with automatic fallback to a processing server when cache is missed.

• 🚀 Architecture and Production Deployment
• 🔧 Features and Quick Start with Docker
• 📂 URL Parameters for Image Transformations
• ✂️ Supported Crop Types (c{crop})
• 🧑‍💻 Local Development Setup
• ⚖️ License

Croppix typically runs as a Node.js service behind an Ingress (NGINX or ALB), with original images stored in an S3 bucket (AWS_BUCKET) and processed images stored in a separate bucket (AWS_BUCKET_CACHE).

Docker is recommended for deployment, along with CDN integration such as CloudFront.

1. A user requests an image from CloudFront, for example:

   https://your-cloudfront-distribution.net/photos/image123.jpg/w240_h160_csmart.webp
   

2. CloudFront checks the S3 cache bucket:

   • ✅ If the image exists, it serves it immediately
   • 🚫 If it doesn't exist (404 or 403), it falls back to Croppix

3. Croppix receives the request and processes the image:

   • Fetches it from the source bucket (AWS_BUCKET)
   • Applies the requested transformations
   • Stores the result in AWS_BUCKET_CACHE
   • Returns the image to CloudFront

4. CloudFront caches the image for future requests

Croppix is also available as a Docker container:

👉 https://hub.docker.com/r/caprionlinesrl/croppix

You can run the container with:

docker run -p 3003:3003 \
  -e AWS_ACCESS_KEY_ID=xxx \
  -e AWS_SECRET_ACCESS_KEY=xxx \
  -e AWS_REGION=us-east-1 \
  -e AWS_BUCKET=your-source-bucket \
  -e AWS_BUCKET_CACHE=your-cache-bucket \
  asterixcapri/croppix:latest

Croppix is designed to work behind a CloudFront distribution with two origins:

1. Primary origin: S3 bucket AWS_BUCKET_CACHE (with cached processed images)
2. Secondary origin (fallback): https://your-croppix-domain.com (Croppix processor)

• ⚡ High performance via CloudFront + S3
• 👊 Croppix server is hit only on cache misses
• 📆 Fully cacheable and URL-customizable images
• 🚪 Robust system with automatic fallback
• ✨ On-demand image generation via URL
• 📁 Integration with AWS S3 for source and cache
• ⚡ Output in WebP, JPEG, PNG and more
• 🔄 Smart crop, resize, retina scaling, cache busting
• ⚙ Docker-ready

A Croppix image request looks like this:

https://your-croppix-domain.com/<image-path>/<transform-params>.<format>

https://your-croppix-domain.com/photos/image123.jpg/w400_h300_d2_csmart_u1712345678.webp

Parameters can be combined with _ and used in any order.

Croppix supports the following crop modes via the c{crop} parameter:

To dynamically generate Croppix URLs in a frontend app:

const croppixBaseUrl = 'https://your-croppix-domain.com';

export const croppixUrl = (path, params) => {
  if (!path) return '';
  return croppixBaseUrl + encodeURI(path) + '/' + formatParams(params);
};

const formatParams = (params = {}) => {
  const parts = [];
  if (params.width) parts.push(`w${params.width}`);
  if (params.height) parts.push(`h${params.height}`);
  if (params.shortSide) parts.push(`s${params.shortSide}`);
  if (params.longSide) parts.push(`l${params.longSide}`);
  if (params.crop) parts.push(`c${params.crop}`);
  if (params.quality) parts.push(`q${params.quality}`);
  if (params.density) parts.push(`d${params.density}`);
  if (params.original) parts.push('o1');
  if (params.updatedAt) parts.push(`u${params.updatedAt}`);

  const extension = params.format || 'jpeg';
  return parts.join('_') + '.' + extension;
};

• Docker installed
• Two S3 buckets:
  • AWS_BUCKET for original images
  • AWS_BUCKET_CACHE for processed images

Everything else is handled by the provided Docker container.

git clone https://github.com/asterixcapri/croppix.git
cd croppix
cp .env.dist .env
docker compose up -d
./scripts/shell.sh
yarn install
yarn dev

You can create a .env file in the project root with:

AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=your-region
AWS_BUCKET=your-source-bucket
AWS_BUCKET_CACHE=your-cache-bucket

The Docker container will automatically load these variables if referenced in docker-compose.yml.

Found a bug or want to add a feature?

Open an Issue or a Pull Request.

Distributed under the MIT license.

Developed by Alessandro Astarita