s3-serve

Runs serve with an S3-compatible backend. Useful for serving websites from S3¹.

Getting started

export AWS_ACCESS_KEY_ID=<access_key_id>
export AWS_SECRET_ACCESS_KEY=<secret_key>
export S3_ENDPOINT_URL=<endpoint_url>
export S3_BUCKET=<bucket_name>

docker run --rm --cap-add SYS_ADMIN --device /dev/fuse --name s3-serve \
    -e AWS_ACCESS_KEY_ID \
    -e AWS_SECRET_ACCESS_KEY \
    -e S3_ENDPOINT_URL \
    -e S3_BUCKET \
    -p 3000:3000 \
    ghcr.io/watonomous/s3-serve:main

Use path-style addressing

If your S3 endpoint does not support virtual-hosted-style addressing, you can use path-style addressing by including --force-path-style in the MOUNTPOINT_S3_ADDITIONAL_ARGS environment variable:

# In addition to the above environment variables
export MOUNTPOINT_S3_ADDITIONAL_ARGS="--force-path-style"

docker run --rm --cap-add SYS_ADMIN --device /dev/fuse --name s3-serve \
    -e AWS_ACCESS_KEY_ID \
    -e AWS_SECRET_ACCESS_KEY \
    -e S3_ENDPOINT_URL \
    -e S3_BUCKET \
    -e MOUNTPOINT_S3_ADDITIONAL_ARGS \
    -p 3000:3000 \
    ghcr.io/watonomous/s3-serve:main

Reduce logging

By default, serve and mountpoint-s3 log all requests². You can reduce the amount of logging by including the following environment variables:

# In addition to the above environment variables
export SERVE_ADDITIONAL_ARGS="--no-request-logging"
export MOUNTPOINT_LOG="error,awscrt=off"

docker run --rm --cap-add SYS_ADMIN --device /dev/fuse --name s3-serve \
    -e AWS_ACCESS_KEY_ID \
    -e AWS_SECRET_ACCESS_KEY \
    -e S3_ENDPOINT_URL \
    -e S3_BUCKET \
    -e SERVE_ADDITIONAL_ARGS \
    -e MOUNTPOINT_LOG \
    -p 3000:3000 \
    ghcr.io/watonomous/s3-serve:main

Use a custom serve configuration

You can use a custom serve configuration by mounting a serve.json file to /etc/serve.json:

docker run --rm --cap-add SYS_ADMIN --device /dev/fuse --name s3-serve \
    -e AWS_ACCESS_KEY_ID \
    -e AWS_SECRET_ACCESS_KEY \
    -e S3_ENDPOINT_URL \
    -e S3_BUCKET \
    -v /path/to/serve.json:/etc/serve.json:ro \
    -p 3000:3000 \
    ghcr.io/watonomous/s3-serve:main

Footnotes

1. S3 does not support clean URLs. The closest you can get is to use index documents, but this only supports index.html and not other files (e.g. about.html. A workaround is to convert all <name>.html files to <name>/index.html files, but that is error-prone because it's not the default behaviour of frameworks like Next.js). Moreover, in some S3-compatible storage backends like Ceph Object Gateway, the support for index documents requires setting rgw_dns_name and rgw_dns_s3website_name, which restricts the RGW instance to only serve from two domains. On the other hand, serve supports clean URLs the box. This project combines the two to provide clean URLs on S3. ↩

2. serve logging documentation, mountpoint-s3 logging documentation 1 2 ↩