imgproxy 4.0.22

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Pick imgproxy 4.0.22 on Ubuntu 24.04 as the software version and select your Region. Then choose Launch through EC2.

Choose m5.large, your key pair and a security group as above.

To launch with the AWS CLI instead, replace the values in angle brackets:

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=imgproxy}]'

Connect over SSH as the ubuntu user, which is the SSH user for imgproxy 4.0.22 on Ubuntu 24.04.

ssh -i <your-key.pem> ubuntu@<public-ip>

First boot generates the certificate, the signing key and the salt, then starts imgproxy and nginx. Check the units:

systemctl is-active imgproxy nginx imgproxy-firstboot
sudo test -f /var/lib/sac/data/imgproxy-firstboot.done && echo FIRSTBOOT_DONE /opt/imgproxy/bin/imgproxy version

All three units are active, the first boot marker is present and imgproxy reports its version. Confirm this:

active active active FIRSTBOOT_DONE 4.0.22

nginx is the only service on public addresses, and imgproxy listens on loopback. Check the listeners:

sudo ss -lntpH | awk '{split($6, a, "\""); print $4, a[2]}' | sort -u

0.0.0.0:22 sshd 0.0.0.0:443 nginx 0.0.0.0:80 nginx 127.0.0.1:8080 imgproxy 127.0.0.53%lo:53 systemd-resolve 127.0.0.54:53 systemd-resolve [::]:22 sshd [::]:443 nginx [::]:80 nginx

sudo cat /root/imgproxy-credentials.txt

The file is readable by root only. Confirm this:

# imgproxy 4.0.22 - generated on first boot by imgproxy-firstboot.service
# The signing key and salt are unique to this instance; none was baked into the image. Keep this file secret.
# Every request path must carry a signature made with them: unsigned or wrongly signed requests get HTTP 403. IMGPROXY_HOST=ec2-203-0-113-10.compute-1.amazonaws.com IMGPROXY_URL=https://ec2-203-0-113-10.compute-1.amazonaws.com/ IMGPROXY_KEY=<64 hex characters> IMGPROXY_SALT=<64 hex characters> IMGPROXY_SIGNATURE_SIZE=32 IMGPROXY_DEMO_URL=https://ec2-203-0-113-10.compute-1.amazonaws.com/<signature>/rs:fit:300:300/plain/local:///sac-sample.png@png ...

• IMGPROXY_URL is where imgproxy is served. It uses the instance's public DNS name from EC2 instance metadata; the certificate also names the public and private IP addresses. To use your own DNS name, see Step 9.
• IMGPROXY_KEY and IMGPROXY_SALT are what your application signs URLs with. They are also in /etc/imgproxy/imgproxy.env, which imgproxy reads.
• IMGPROXY_DEMO_URL is a ready signed URL for the bundled sample image, resized to fit 300 x 300.

When you need to share the file, for example in a support request, print it with the key and salt masked:

sudo sed -E 's/^(IMGPROXY_(KEY|SALT)=).*/\1********/' /root/imgproxy-credentials.txt | grep '^IMGPROXY_'

Open IMGPROXY_DEMO_URL in your browser. The certificate is self-signed, so the browser asks you to confirm it the first time.

From the instance, run the following. It fetches the demo URL and checks that the result is a real 300 x 200 PNG. It then shows that the same path without a valid signature is refused:

sudo bash -c ' F=/root/imgproxy-credentials.txt H=$(sed -n "s/^IMGPROXY_HOST=//p" $F); D=$(sed -n "s/^IMGPROXY_DEMO_URL=//p" $F) R="--resolve $H:443:127.0.0.1" P=/rs:fit:300:300/plain/local:///sac-sample.png@png curl -sk $R -o /tmp/demo.png -w "signed demo URL -> HTTP %{http_code}, %{content_type}\n" "$D" imgproxy-assert-png /tmp/demo.png 300 200 curl -sk $R -o /dev/null -w "no signature -> HTTP %{http_code}\n" "https://$H$P" curl -sk $R -o /dev/null -w "/insecure (unsigned) -> HTTP %{http_code}\n" "https://$H/insecure$P" rm -f /tmp/demo.png '

signed demo URL -> HTTP 200, image/png OK /tmp/demo.png: valid PNG 300x200, 924 bytes no signature -> HTTP 403 /insecure (unsigned) -> HTTP 403

imgproxy-sign-url signs any path with this instance's key. The following processes an image from the public internet (imgproxy's own test image) into a 100 x 50 PNG:

H=$(sudo sed -n 's/^IMGPROXY_HOST=//p' /root/imgproxy-credentials.txt) SRC=https://raw.githubusercontent.com/imgproxy/imgproxy/a08006d11003eef87218a7407b1f21a40f6da615/testdata/geometry.png
U=$(sudo imgproxy-sign-url --url "https://$H" "/rs:fit:100:100/plain/$SRC@png")
curl -sk --resolve "$H:443:127.0.0.1" -o /tmp/geometry.png -w 'HTTP %{http_code}\n' "$U" imgproxy-assert-png /tmp/geometry.png 100 50 rm -f /tmp/geometry.png

HTTP 200 OK /tmp/geometry.png: valid PNG 100x50, 7051 bytes

An imgproxy URL is https://<host>/<signature>/<processing options>/plain/<source URL>@<format>. Common options are rs:<type>:<width>:<height> (resize: fit keeps the whole image, fill crops to the exact size), q:<quality> and g:<gravity> for the crop position. The full list is in the imgproxy documentation.

Request the sample image in several formats and sizes:

H=$(sudo sed -n 's/^IMGPROXY_HOST=//p' /root/imgproxy-credentials.txt) for o in rs:fill:400:400/q:85@webp rs:fit:640:0@avif rs:fill:160:90/g:ce@jpg rs:fit:1200:1200@tiff; do
U=$(sudo imgproxy-sign-url --url "https://$H" "/${o%@*}/plain/local:///sac-sample.png@${o#*@}")
curl -sk --resolve "$H:443:127.0.0.1" -o /dev/null -w "${o} -> %{http_code} %{content_type} %{size_download} bytes\n" "$U" done

rs:fill:400:400/q:85@webp -> 200 image/webp 2416 bytes rs:fit:640:0@avif -> 200 image/avif 1391 bytes rs:fill:160:90/g:ce@jpg -> 200 image/jpeg 1196 bytes rs:fit:1200:1200@tiff -> 200 image/tiff 2880278 bytes

To serve your own images, use their URL as the source, for example /rs:fit:800:0/plain/https://images.example.com/photos/cat.jpg@webp. If the source URL contains a query string or an @, percent-encode it or use the base64 form /rs:fit:800:0/<base64url of the source URL>.webp.

Your application builds the URL path, signs it with the key and salt from Step 4 and puts the signature in front. The calculation is:

signature = base64url( HMAC_SHA256( key = hex_decode(IMGPROXY_KEY), message = hex_decode(IMGPROXY_SALT) + path ) ) with the trailing "=" padding removed URL = https://<host>/<signature><path>

Here is a Python example. Keep the key and salt in your secrets store, never in client-side code:

import base64, hashlib, hmac def imgproxy_url(host, key_hex, salt_hex, path): digest = hmac.new(bytes.fromhex(key_hex), bytes.fromhex(salt_hex) + path.encode(), hashlib.sha256).digest() signature = base64.urlsafe_b64encode(digest).rstrip(b"=").decode() return f"https://{host}/{signature}{path}" print(imgproxy_url("img.example.com", KEY, SALT, "/rs:fit:300:300/plain/https://images.example.com/cat.jpg@webp"))

The following runs the same calculation on the instance and confirms that it matches imgproxy-sign-url:

sudo python3 - <<'PY' import base64, hashlib, hmac, subprocess env = dict(l.split("=", 1) for l in open("/root/imgproxy-credentials.txt").read().splitlines() if l and not l.startswith("#")) path = "/rs:fit:300:300/plain/local:///sac-sample.png@png" digest = hmac.new(bytes.fromhex(env["IMGPROXY_KEY"]), bytes.fromhex(env["IMGPROXY_SALT"]) + path.encode(), hashlib.sha256).digest() mine = "/" + base64.urlsafe_b64encode(digest).rstrip(b"=").decode() + path helper = subprocess.run(["imgproxy-sign-url", path], capture_output=True, text=True).stdout.strip() print("signatures match" if mine == helper else "MISMATCH") PY

signatures match

Client libraries that implement this exist for most languages. See the imgproxy documentation on signing.

By default, a correctly signed URL may point at any public address. Only holders of your key can create one, but pinning the sources is good practice.

Edit /etc/imgproxy/imgproxy.env and list your origins, comma-separated, each as a URL prefix. Then restart imgproxy:

sudo nano /etc/imgproxy/imgproxy.env
# IMGPROXY_ALLOWED_SOURCES=https://images.example.com/,https://my-bucket.s3.amazonaws.com/,local://
sudo systemctl restart imgproxy

To serve images straight from a private S3 bucket, imgproxy also supports s3:// sources with IMGPROXY_USE_S3=true. It then needs AWS credentials.

Because imgproxy is blocked from the instance metadata service on this image, use an access key in /etc/imgproxy/imgproxy.env (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION) for a dedicated IAM user that can only read that bucket. Alternatively, make the bucket reachable through CloudFront and use https:// sources.

Point a DNS record at the instance (an Elastic IP keeps the address stable), then tell the instance its name. This regenerates the self-signed certificate for that name, updates the credentials file and reloads nginx:

sudo imgproxy-set-hostname img.your-domain.example

To use a certificate from a public CA instead, replace /etc/ssl/imgproxy/imgproxy.crt (full chain) and /etc/ssl/imgproxy/imgproxy.key (mode 0600) and run sudo systemctl reload nginx.

Behind CloudFront or an Application Load Balancer, point the origin at port 443 and the health check at /healthz.

To replace the key and salt (for example after a staff change), run the rotation helper. It writes a new pair to /etc/imgproxy/imgproxy.env and the credentials file, and it restarts imgproxy.

Every URL signed with the old key stops working, so update your application's secret at the same time:

sudo imgproxy-rotate-keys
H=$(sudo sed -n 's/^IMGPROXY_HOST=//p' /root/imgproxy-credentials.txt) sleep 2 curl -sk --resolve "$H:443:127.0.0.1" -o /dev/null -w 'new demo URL -> HTTP %{http_code}\n' "$(sudo sed -n 's/^IMGPROXY_DEMO_URL=//p' /root/imgproxy-credentials.txt)"

imgproxy-rotate-keys: new signing key and salt in place; URLs signed with the previous key are now refused new demo URL -> HTTP 200

A correctly signed request for the instance metadata service, a loopback address or a private address is refused, while a public source works (Step 5). Verify this:

H=$(sudo sed -n 's/^IMGPROXY_HOST=//p' /root/imgproxy-credentials.txt)
T=$(date '+%Y-%m-%d %H:%M:%S') for src in http://169.254.169.254/latest/meta-data/ http://127.0.0.1:8080/health http://10.0.0.1/photo.jpg; do
U=$(sudo imgproxy-sign-url --url "https://$H" "/rs:fit:50:50/plain/$src@png")
curl -sk --resolve "$H:443:127.0.0.1" -o /dev/null -w "$src -> HTTP %{http_code}\n" "$U" done
sudo journalctl -u imgproxy -o cat --since "$T" | grep -oE '(Link-local|Loopback|Private) source address is not allowed' | sort | uniq -c

http://169.254.169.254/latest/meta-data/ -> HTTP 404 http://127.0.0.1:8080/health -> HTTP 404 http://10.0.0.1/photo.jpg -> HTTP 404 1 Link-local source address is not allowed 1 Loopback source address is not allowed 1 Private source address is not allowed

imgproxy and nginx are also blocked from the instance metadata service at the network level. imgproxy runs sandboxed as a dynamic user, with a guard that refuses to start it without a real signing key. Verify this:

systemctl show imgproxy nginx -p IPAddressDeny --value
systemctl show imgproxy -p DynamicUser -p ProtectSystem -p ExecStartPre --value | cut -c1-80 grep -E '^IMGPROXY_(BIND|ALLOW_[A-Z_]+)=' /etc/imgproxy/imgproxy.env.tmpl

fd00:ec2::254/128 168.63.129.16/32 169.254.169.254/32 fd00:ec2::254/128 168.63.129.16/32 169.254.169.254/32 { path=/usr/local/sbin/imgproxy-config-guard ; argv[]=/usr/local/sbin/imgproxy-c yes strict IMGPROXY_BIND=127.0.0.1:8080 IMGPROXY_ALLOW_LINK_LOCAL_SOURCE_ADDRESSES=false IMGPROXY_ALLOW_LOOPBACK_SOURCE_ADDRESSES=false IMGPROXY_ALLOW_PRIVATE_SOURCE_ADDRESSES=false

systemd may list the three denied addresses in a different order. What matters is that all three appear for both units.