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:
CHOP_ORIGIN=s3://my-bucket/uploads AWS_REGION=eu-west-1 \
AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... \
npx @wpelevator/chop
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:
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:
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:
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:
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
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 lists the codes.
Reference
The settings are in the S3 group of the configuration reference.
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: 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. 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=1is 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 with
CHOP_ORIGIN=http://seaweedfs:8888/buckets/<bucket>,CHOP_ORIGIN_ALLOW_HTTP=1andCHOP_ORIGIN_ALLOW_PRIVATE=1, when the filer isn't exposed to anyone else. Use the S3 origin when you want access keys.