Serving files from Amazon S3
imgproxy can process images from S3 buckets. To use this feature, do the following:
- Set the
IMGPROXY_USE_S3
environment variable to betrue
. - Set up the necessary credentials to grant access to your bucket.
- (optional) Specify the AWS region with
IMGPROXY_S3_REGION
orAWS_REGION
. Default:us-west-1
- (optional) Specify the S3 endpoint with
IMGPROXY_S3_ENDPOINT
. You can also setIMGPROXY_S3_ENDPOINT_USE_PATH_STYLE=false
to use the virtual host style for the endpoint. - (optional) Set the
IMGPROXY_S3_USE_DECRYPTION_CLIENT
environment variable totrue
if your objects are client-side encrypted. - (optional) Specify the AWS IAM Role to Assume with
IMGPROXY_S3_ASSUME_ROLE_ARN
. - (optional) Specify the External ID that needs to be passed in along with the AWS IAM Role to Assume with
IMGPROXY_S3_ASSUME_ROLE_EXTERNAL_ID
. This will have no effect if the assume role ARN is not specified. - Use
s3://%bucket_name/%file_key
as the source image URL.
If you need to specify the version of the source object, you can use the query string of the source URL:
s3://%bucket_name/%file_key?%version_id
If filenames in your S3 may contain ?
, you may want to set IMGPROXY_SOURCE_URL_QUERY_SEPARATOR to another string that is not used in filenames or set it to blank to disable query string extraction.
For example, if you set IMGPROXY_SOURCE_URL_QUERY_SEPARATOR
to ?version=
, you can specify the version like this:
s3://%bucket_name/%file_key?version=%version_id
Set up credentials
There are three ways to specify your AWS credentials. The credentials need to have read rights for all of the buckets given in the source URLs:
IAM Roles
If you're running imgproxy on an Amazon Web Services platform, you can use IAM roles to to get the security credentials to make calls to AWS S3.
- Elastic Container Service (ECS): Assign an IAM role to a task.
- Elastic Kubernetes Service (EKS): Assign a service account to a pod.
- Elastic Beanstalk: Assign an IAM role to an instance.
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