---
title: Deploy imgproxy with AI
url: "/guides/imgproxy/"
canonical_url: https://docs.blossom88.com/guides/imgproxy/
markdown_url: https://docs.blossom88.com/guides/imgproxy.md
summary: Deploy imgproxy with AI on Blossom. Resize images from a private Cloudflare
  R2 bucket, serve signed URLs, and cache images at the CDN.
categories:
- deployment
- images
---

# Deploy imgproxy with AI

[imgproxy](https://imgproxy.net/) resizes and optimizes images on demand. Keep
one original in object storage and request the size your page needs, from a
small thumbnail to a full-width screenshot.

Deploy it on Blossom Cloud with a private Cloudflare R2 bucket and put your
image domain behind Cloudflare's CDN.

[Install the Blossom CLI and skill](/learn/getting-started/install/)
on your agent's machine and choose a Blossom Cloud Location when you log in.
You can also use
[Blossom BYOC (bring your own cloud)](/learn/getting-started/choose-your-cloud/#blossom-byoc).

## Ask Your Agent


> **Ask your AI agent:** Deploy imgproxy on Blossom with my images in R2. Help me serve smaller images
> on my website through Cloudflare.

> Follow this guide: https://docs.blossom88.com/guides/imgproxy/



Your agent creates a private bucket in your Cloudflare account and a
[bucket-restricted, read-only credential](https://developers.cloudflare.com/r2/api/tokens/)
for imgproxy. Use a separate credential for uploading images. Keep both in
private environment files outside your application repository.

| Part | Purpose |
|---|---|
| imgproxy web Service | Resizes originals into the requested dimensions and format |
| Private R2 bucket | Keeps the original images outside the Container |
| Signed image URLs | Allow the transformations your website requests |
| Cloudflare CDN | Caches processed images near your readers |

The Service uses regular App Capacity and needs no attached Volume or database.
Additional Containers can read the same bucket and use the same signing keys.

<details class="optional-reading" markdown="1">
<summary>Commands behind the deployment</summary>

Your agent checks imgproxy's current
[installation](https://docs.imgproxy.net/installation) and
[S3 configuration](https://docs.imgproxy.net/image_sources/amazon_s3), selects
a maintained official image for your Location's architecture, and pins it in
the deployment configuration.

    blossom profile:show
    blossom app:create --data '{"app":{"name":"imgproxy"}}'

The agent writes environment.yml using the returned App ID:

```yaml
environment:
  app_id: app-100
  name: production
  source_type: prebuilt_image
  prebuilt_image: <official image pinned by your agent>
  access_mode: public
```

    blossom environment:create --data environment.yml

Save these settings in a private .env.production file. Generate stable,
hex-encoded `IMGPROXY_KEY` and `IMGPROXY_SALT` values using imgproxy's
[signing guidance](https://docs.imgproxy.net/usage/signing_url).

```dotenv
IMGPROXY_BIND=:8080
IMGPROXY_USE_S3=true
IMGPROXY_S3_ENDPOINT=<your R2 S3 endpoint>
IMGPROXY_S3_REGION=auto
IMGPROXY_S3_ENDPOINT_USE_PATH_STYLE=true
AWS_ACCESS_KEY_ID=<bucket-restricted read-only access key>
AWS_SECRET_ACCESS_KEY=<its secret access key>
IMGPROXY_ALLOWED_SOURCES=s3://my-blog-images/
IMGPROXY_S3_ALLOWED_BUCKETS=my-blog-images
IMGPROXY_KEY=<stable hex signing key>
IMGPROXY_SALT=<stable hex signing salt>
```

    blossom env_var:push --environment environment-100 --file .env.production

The agent creates service.yml with the `imgproxy` startup command, port
`8080`, and resources suited to your images and traffic. Use a Command health
check running `imgproxy health`; the official image provides this command.

```yaml
health_check:
  enabled: true
  kind: command
  command: CMD-SHELL imgproxy health
```

    blossom service:create --data service.yml
    blossom domain:create --data '{"domain":{"environment_id":"environment-100","dns_name":"images.example.com","main":true}}'
    blossom environment:deploy --id environment-100 --follow
    blossom environment:show --id environment-100

Use Blossom's returned DNS target for the image domain. Configure its origin
HTTPS mode to match your Cloudflare SSL settings.

</details>

## Serve the Size Your Page Needs


> **Ask your AI agent:** Help me upload an image and use responsive images on my website. Keep the
> original available when someone wants to enlarge it.

> Follow this guide: https://docs.blossom88.com/guides/imgproxy/



Upload each original under a unique, versioned object name. Your agent
generates signed URLs for the required sizes and adds `srcset` and `sizes`
to your image markup. The browser chooses a suitable size for the display.
Use `fit` resizing without enlargement to preserve the image's proportions.

![A blog article card using a smaller image served by imgproxy.](https://images.boltops.com/_gdLXqdi69GMytRvhGQ9q0oH-Wq3RJct7bPcvdfHZ44/rs:fit:640:0:0/q:85/czM6Ly9ib2x0b3BzLWltYWdlcy9vcmlnaW5hbHMvYjBlZWRmOWFiY2ZjYTAyZWJlNTI4OTY5Y2MzZDJiZGRhYzc4ZTM0NjdhMDMyZjFmZWQ2ZDI3NDk0ZmE4NWFhNC9ibG9nLWNhcmQucG5n.webp)

Generate signatures on a trusted machine or during your build. Keep signing
keys out of browser JavaScript. A signed `raw:1` URL can serve the original
bytes for full-size viewing.

Use explicit output formats such as WebP and verify Cloudflare caches the
image URLs. Versioned originals let a changed image get a new URL while
existing pages keep working.

## Keep Images Across Updates


> **Ask your AI agent:** Redeploy imgproxy and check that the same image URLs still work.

> Follow this guide: https://docs.blossom88.com/guides/imgproxy/



    blossom environment:deploy --id environment-100 --follow

Keep the bucket and signing keys when replacing Containers. Originals live
in R2, so a new Container can serve the same signed URLs.

## What You Get

- Images sized for thumbnails, article content, and larger displays
- Original files in your own private R2 bucket
- Signed image URLs cached by Cloudflare
- Stateless Containers that can be replaced or scaled without moving images
