# Serve images from S3

Serve images from an S3 bucket or an S3-compatible service such as Cloudflare R2, MinIO or SeaweedFS.

Serve the images of an S3 bucket, or of an S3-compatible service such as Cloudflare R2, MinIO or SeaweedFS, with one environment variable and the credentials that the bucket needs:

```sh
CHOP_ORIGIN=s3://my-bucket/uploads AWS_REGION=eu-west-1 \
AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... \
npx @wpelevator/chop
```

```text
chop listening on http://0.0.0.0:8080, serving s3://my-bucket/uploads
```

The request `/2026/05/photo.jpg` reads the key `uploads/2026/05/photo.jpg`. The S3 origin needs chop 0.2.0 or later. Lambda puts the same `AWS_*` variables in the environment for its execution role, so there is nothing to add there.

Without a region, chop exits with code `2`:

```text
An S3 origin on AWS needs a region: set s3Region (CHOP_S3_REGION or AWS_REGION).
```

Without credentials, chop sends unsigned requests, which only work for a bucket with public read access, and prints a warning at startup:

```text
warning: The S3 origin has no credentials (s3AccessKeyId and s3SecretAccessKey): requests are unsigned, which only works for a bucket with public read access.
```

## Common tasks

### Use AWS, Lambda or a public bucket

The first command covers AWS. A public bucket needs only a region, and chop prints the warning that there are no credentials:

```sh
CHOP_ORIGIN=s3://public-photos/uploads CHOP_S3_REGION=eu-west-1 chop
```

### Use SeaweedFS or MinIO on a private network

An endpoint on a private network needs `CHOP_ORIGIN_ALLOW_PRIVATE`, and plain http also needs `CHOP_ORIGIN_ALLOW_HTTP`:

```sh
CHOP_ORIGIN=s3://photos \
CHOP_S3_ENDPOINT=http://seaweedfs:8333 \
CHOP_ORIGIN_ALLOW_HTTP=1 CHOP_ORIGIN_ALLOW_PRIVATE=1 \
CHOP_S3_ACCESS_KEY_ID=chop CHOP_S3_SECRET_ACCESS_KEY=... \
chop
```

### Use Cloudflare R2

```sh
CHOP_ORIGIN=s3://photos \
CHOP_S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com CHOP_S3_REGION=auto \
CHOP_S3_ACCESS_KEY_ID=... CHOP_S3_SECRET_ACCESS_KEY=... \
chop
```

### Find out why images are missing

A signature problem, a wrong key and a missing permission all look like a `404` to the client. chop writes the S3 error code to the standard error, like `origin ERR_NOT_FOUND: s3.example.com answered 403 SignatureDoesNotMatch`. Look there first. [Troubleshoot chop](troubleshooting.md#s3-error-codes) lists the codes.

## Reference

The settings are in the [S3 group of the configuration reference](configuration.md#s3).

### Keys and signing

`CHOP_ORIGIN=s3://bucket` or `s3://bucket/prefix` reads the originals from a bucket, and `--origin s3://bucket` works too. The path of a request is appended to the prefix to make the key. With `s3://my-bucket/uploads`, the request `/2026/05/photo.jpg` reads the key `uploads/2026/05/photo.jpg`.

Each segment is percent-encoded once, which is what S3 signs, so spaces, `+`, `!`, `*`, `'`, `(`, `)` and non-ASCII names work. The bucket name follows the S3 rules: 3 to 63 lower case letters, digits, dots and hyphens. A prefix can't have empty, `.` or `..` segments. An `s3://` origin can't be combined with an explicit `CHOP_DATA_DIR` or `--data`.

chop signs every request to the bucket with AWS Signature Version 4, using only `node:crypto`. The rest follows the [HTTP origin](https-origin.md): the pinned DNS lookup and address checks, no redirects, the size cap while reading, the timeouts, and the fetch limit and queue. `CHOP_ORIGIN_ALLOW_HTTP` and `CHOP_ORIGIN_ALLOW_PRIVATE` apply to the endpoint. URL sources from `CHOP_ALLOWED_HOSTS` still work next to an S3 origin. They are fetched without a signature, and the credentials are never sent to them.

### Endpoints and addressing

On AWS the default is the virtual-hosted form, `bucket.s3.<region>.amazonaws.com`. A bucket name with dots uses the path-style form, `s3.<region>.amazonaws.com/bucket/key`, because the wildcard certificate of AWS doesn't cover dotted names. `CHOP_S3_PATH_STYLE=true` forces path style.

With a custom endpoint the default is `endpoint/bucket/key`. `CHOP_S3_PATH_STYLE=false` uses `bucket.endpoint-host` instead, which needs a host name that can have subdomains and not an IP address. The endpoint is checked like an origin: `https://`, or `http://` with `CHOP_ORIGIN_ALLOW_HTTP`, without user information, a query string or a fragment. A loopback, private or link-local address needs `CHOP_ORIGIN_ALLOW_PRIVATE`.

### Credentials

Credentials need both a key and a secret. With only one of them, or with a session token alone, chop doesn't start. The error names the settings and not their values. With neither, requests are unsigned, which only works for a bucket with public read access, and chop prints a warning at startup.

chop reads credentials once at startup and doesn't refresh them. Temporary credentials with a session token stop working when they expire in a long-running process, so restart chop when they rotate, or use static keys for a server. chop doesn't read instance metadata, shared credential files or web identity. The secret key and the session token are only read from the environment, there is no flag, and they never appear in a log, warning or error message.

### Errors

Errors are answered like those of an HTTP origin. A missing key, a `403` and a `404` are a plain `404` for the client. A `5xx`, a network or TLS error and a redirect are a `502`. A timeout is a `504`, and an object over `maxInputBytes` is a `413`.

S3 explains an error in an XML body. A signature problem, a wrong key and a missing permission all look like a missing image to the client, so chop reads at most the first 2048 bytes of an error body, waits at most two seconds for them, and writes the `<Code>` to the standard error. The codes and their usual causes are in [Troubleshoot chop](troubleshooting.md#s3-error-codes). The codes never reach the client.

### Limits of the S3 origin

- **GET only.** chop reads whole objects with a signed `GET`. It doesn't list buckets, use ranges or presigned URLs.
- **Interface VPC endpoints.** A private endpoint for S3 resolves to private addresses, which chop blocks unless `CHOP_ORIGIN_ALLOW_PRIVATE=1` is set. Set it together with the endpoint.
- **SeaweedFS filer.** SeaweedFS can also serve a bucket through its filer over plain HTTP, which needs no signature and no S3 settings. Use the [HTTP origin](https-origin.md) with `CHOP_ORIGIN=http://seaweedfs:8888/buckets/<bucket>`, `CHOP_ORIGIN_ALLOW_HTTP=1` and `CHOP_ORIGIN_ALLOW_PRIVATE=1`, when the filer isn't exposed to anyone else. Use the S3 origin when you want access keys.
