Skip to main content
Version: 4-preview

Internal cache: Amazon S3

imgproxy can store cached images in Amazon S3 buckets or S3-compatible storage. To use S3 cache, do the following:

  1. Set the IMGPROXY_CACHE_USE environment variable to s3.
  2. Set up the necessary credentials to grant access to your cache bucket.
  3. Specify the cache bucket name with IMGPROXY_CACHE_BUCKET.
  4. (optional) Specify the AWS region with IMGPROXY_CACHE_S3_REGION or AWS_REGION. Default: us-west-1
  5. (optional) Specify the S3 endpoint with IMGPROXY_CACHE_S3_ENDPOINT. You can also set IMGPROXY_CACHE_S3_ENDPOINT_USE_PATH_STYLE=false to use the virtual host style for the endpoint.

Configuration​

  • IMGPROXY_CACHE_USE: set to s3 to enable S3 cache.
  • IMGPROXY_CACHE_BUCKET: the S3 bucket name for cache storage. Default: blank
  • IMGPROXY_CACHE_S3_REGION: the S3 region for the cache bucket. Default: blank
  • IMGPROXY_CACHE_S3_ENDPOINT: a custom S3 endpoint for the cache. Useful for S3-compatible services like MinIO, Cloudflare R2, DigitalOcean Spaces, etc. Default: blank
  • IMGPROXY_CACHE_S3_ENDPOINT_USE_PATH_STYLE: controls how the S3 bucket endpoint is constructed. When true, the endpoint will be constructed using the path style (https://your-endpoint.com/%bucket). When false, the endpoint will be constructed using the virtual host style (https://%bucket.your-endpoint.com). Default: true
  • IMGPROXY_CACHE_S3_ASSUME_ROLE_ARN: the ARN of an IAM role to assume for cache access. Default: blank
  • IMGPROXY_CACHE_S3_ASSUME_ROLE_EXTERNAL_ID: the external ID required to assume the IAM role for cache access. Default: blank
  • IMGPROXY_CACHE_PATH_PREFIX: a path prefix for the cache files. Default: blank
  • IMGPROXY_CACHE_KEY_HEADERS: a comma-separated list of HTTP request headers to include in the cache key. Default: blank
  • IMGPROXY_CACHE_KEY_COOKIES: a comma-separated list of HTTP request cookies to include in the cache key. Default: blank
  • IMGPROXY_CACHE_REPORT_ERRORS: when true, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: false

Set up credentials​

There are three ways to specify your AWS credentials. The credentials need to have read/write rights for the cache bucket:

IAM Roles​

If you're running imgproxy on an Amazon Web Services platform, you can use IAM roles to get the security credentials to make calls to AWS S3.

Environment variables​

You can specify an AWS Access Key ID and a Secret Access Key by setting the standard AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

AWS_ACCESS_KEY_ID=my_access_key AWS_SECRET_ACCESS_KEY=my_secret_key imgproxy

# same for Docker
docker run -e AWS_ACCESS_KEY_ID=my_access_key -e AWS_SECRET_ACCESS_KEY=my_secret_key -it ghcr.io/imgproxy/imgproxy

Shared credentials file​

Alternatively, you can create the .aws/credentials file in your home directory with the following content:

[default]
aws_access_key_id = %access_key_id
aws_secret_access_key = %secret_access_key

Cross-Account Access​

Cache S3 access credentials may be acquired by assuming a role using STS. To do so, specify the IAM Role ARN with the IMGPROXY_CACHE_S3_ASSUME_ROLE_ARN environment variable. Additionally, if you require an external ID to be passed when assuming a role, specify the IMGPROXY_CACHE_S3_ASSUME_ROLE_EXTERNAL_ID environment variable. This approach still requires you to provide initial AWS credentials by using one of the ways described above. The provided credentials role should allow assuming the role with the provided ARN.

Choosing the AWS region​

The AWS region specified with the IMGPROXY_CACHE_S3_REGION environment variable determines the S3 endpoint used by imgproxy for the initial request to the bucket. If AWS reports that the bucket is in a different region, imgproxy will remember this, retry the request, and use the new region for all subsequent requests for this bucket.

This allows imgproxy to access buckets in any region. However, the initial request to the bucket in a region other than the one specified in the environment variable may introduce some latency.