A tiny, filesystem-backed S3-compatible server for local development and testing.

essie3 speaks enough of the S3 REST API to stand in for AWS S3 when running integration tests, demos, or offline dev environments. It's a single Go binary with zero third-party dependencies.

When an object is missing, essie3 can return a deterministic fallback placeholder instead of 404 NoSuchKey — useful when seeding a dev environment where the real assets don't exist yet, so your UI doesn't render broken images.

go run .                                   # listens on :9000

# In another shell:
curl -X PUT http://localhost:9000/mybucket # create a bucket
curl -X PUT --data-binary @photo.jpg \
  -H "Content-Type: image/jpeg" \
  http://localhost:9000/mybucket/photo.jpg # upload
curl http://localhost:9000/mybucket/photo.jpg -o out.jpg  # download

That's it. Point any S3 client at http://localhost:9000 and go.

• Features
• Running
• Configuration
• Usage
• Range requests
• Auth (optional)
• Fallback placeholders
• Storage layout
• Development
• License

S3 API

• PUT, GET, HEAD, DELETE, POST (multipart), and COPY for objects
• Bucket create / head / list (stub)
• CORS enabled for browser uploads
• Per-object metadata persisted as JSON sidecar files
• HTTP Range requests (single-range) with If-Range ETag matching, on objects and fallback placeholders

Fallbacks

• Deterministic fallback placeholders by file extension (.jpg / .jpeg / .png / .gif / .webp / .pdf / .mp4 / .mov / .webm / .avi)
• Optional on-demand bubble-identicon generator for PNG / JPEG keys

Safety & ops

• Atomic object writes (temp-file + rename)
• Path-traversal protection on bucket and key names
• Optional access-key auth with an x-amz-acl: public-read escape hatch
• Graceful shutdown on SIGINT / SIGTERM

go run .

services:
  essie3:
    image: igoraleksandrov/essie3:latest
    ports:
      - "9000:9000"
    volumes:
      - ./data:/data
      - ./fallback-data:/fallback-data
    environment:
      ESSIE3_DATA_DIR: /data
      ESSIE3_FALLBACK_DATA_DIR: /fallback-data

docker compose up

All configuration is via environment variables. The fallback-related options have dedicated sections below with the full details.

aws --endpoint-url http://localhost:9000 s3 mb s3://mybucket
aws --endpoint-url http://localhost:9000 s3 cp photo.jpg s3://mybucket/photos/photo.jpg
aws --endpoint-url http://localhost:9000 s3 cp s3://mybucket/photos/photo.jpg ./downloaded.jpg

# Create bucket
curl -X PUT http://localhost:9000/mybucket

# Put object
curl -X PUT --data-binary @photo.jpg \
  -H "Content-Type: image/jpeg" \
  http://localhost:9000/mybucket/photos/photo.jpg

# Get object
curl http://localhost:9000/mybucket/photos/photo.jpg -o out.jpg

# Head object
curl -I http://localhost:9000/mybucket/photos/photo.jpg

# Delete object
curl -X DELETE http://localhost:9000/mybucket/photos/photo.jpg

curl -X POST http://localhost:9000/mybucket \
  -F "key=uploads/photo.jpg" \
  -F "file=@photo.jpg"

GET and HEAD on objects and fallback placeholders honor the HTTP Range header in its three single-range forms:

curl -H "Range: bytes=0-4"   http://localhost:9000/mybucket/photos/photo.jpg
curl -H "Range: bytes=1024-" http://localhost:9000/mybucket/photos/photo.jpg
curl -H "Range: bytes=-256"  http://localhost:9000/mybucket/photos/photo.jpg

Responses include Accept-Ranges: bytes. A satisfiable Range returns 206 Partial Content with Content-Range: bytes <start>-<end>/<total> and the sliced body. An unsatisfiable Range returns 416 Requested Range Not Satisfiable with an S3-shaped XML body (<Code>InvalidRange</Code>) and Content-Range: bytes */<total>.

If-Range: "<etag>" is honored against the object's ETag — if the header matches, the Range is served; if it doesn't, the full body is served as a 200 instead (so a client resuming an interrupted download never merges bytes from a changed object). If-Range with a date value is treated as a mismatch.

essie3 is unauthenticated by default. Set ESSIE3_ACCESS_KEY to require a specific access key on incoming requests — useful for integration tests that assert "unauthenticated requests get 403."

ESSIE3_ACCESS_KEY=AKIATEST go run .

# Unauthenticated request → 403 AccessDenied
curl -i http://localhost:9000/mybucket/key

# Wrong key → 403 InvalidAccessKeyId
AWS_ACCESS_KEY_ID=WRONGKEY AWS_SECRET_ACCESS_KEY=anything \
aws --endpoint-url http://localhost:9000 s3 ls s3://mybucket

# Correct key → served normally
AWS_ACCESS_KEY_ID=AKIATEST AWS_SECRET_ACCESS_KEY=anything \
aws --endpoint-url http://localhost:9000 s3 ls s3://mybucket

Objects stored with x-amz-acl: public-read are readable without credentials even when auth is enabled. Set the ACL on upload:

# AWS CLI
aws --endpoint-url http://localhost:9000 \
    s3 cp photo.jpg s3://mybucket/photos/photo.jpg --acl public-read

# curl
curl -X PUT --data-binary @photo.jpg \
  -H "Content-Type: image/jpeg" \
  -H "x-amz-acl: public-read" \
  http://localhost:9000/mybucket/photos/photo.jpg

Put any number of images, PDFs, or videos in the fallback directory. On GET/HEAD for a missing object, essie3 picks one deterministically based on the key (same key → same placeholder) and serves it with HTTP 200.

fallback-data/
├── generic1.jpg
├── generic2.jpg
├── generic.png
├── generic.pdf
└── generic.mp4

ESSIE3_FALLBACK_MODE controls how a miss is filled:

Under pool, if a key's extension has no matching placeholder, essie3 returns the usual NoSuchKey error.

When the curated pool has no match (or under generate), essie3 renders a bubble identicon seeded by MD5(key): 16 translucent overlapping circles on a white 512×512 canvas, colored from the D3 category20 palette. The same key always produces byte-identical output.

Generated responses include ETag: "<md5 hex>" (S3 single-PUT convention) and a Last-Modified set to the server's start time, so If-None-Match and If-Range work naturally. Set ESSIE3_FALLBACK_MODE=pool to disable the generator entirely.

ESSIE3_FALLBACK_INLINE_EXTENSIONS is a comma-separated list of extensions served with Content-Disposition: inline; everything else is served as attachment (so browsers prompt a download). Set it to an empty string to serve all fallbacks as attachments.

ESSIE3_FALLBACK_INLINE_EXTENSIONS=.jpg,.png,.pdf go run .

The default inline set is:

.jpg  .jpeg  .png  .gif  .webp  .pdf  .mp4  .mov  .webm  .avi

data/
└── <bucket>/
    ├── <key>              # raw body
    └── <key>.meta.json    # content-type, etag, created-at, acl, ...

Metadata is written atomically alongside the body. PUT and DELETE on the same key are serialized via an in-process per-key lock so concurrent writers cannot leave a body/meta mismatch.

go test ./...     # full test suite
go vet ./...
gofmt -l .        # lists files needing formatting

MIT — see LICENSE.