s3www is a lightweight, open-source tool to serve static files from any S3-compatible object storage service, such as AWS S3, MinIO, or DigitalOcean Spaces. It supports HTTPS with Let's Encrypt for secure hosting and is ideal for hosting static websites, single-page applications (SPAs), or file servers.
- S3 Compatibility: Works with any S3-compatible storage provider.
- HTTPS Support: Automatic TLS certificates via Let's Encrypt.
- Lightweight: Built in Go for performance and minimal resource usage.
- SPA Support: Configurable single-page application routing.
- Customizable: Supports custom error pages and CORS configuration.
- Cross-Platform: Runs on Linux, macOS, FreeBSD, and more.
- An S3-compatible storage bucket with static files (e.g.,
index.html
). - S3 credentials with
s3:GetObject
ands3:ListBucket
permissions. - Go 1.21+ (for building from source) or Docker/Podman (for containerized deployment).
- Network access to your S3 endpoint and port 8080 (or your chosen port).
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowGetObject",
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::<Bucket Name>/*"
},
{
"Sid": "AllowListBucket",
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::<Bucket Name>"
}
]
}
- Visit the Releases page and download the binary for your platform (e.g.,
s3www_0.9.0_linux_amd64.tar.gz
). - Extract the archive:
tar -xzf s3www_0.9.0_linux_amd64.tar.gz
- Move the binary to a directory in your PATH:
sudo mv s3www /usr/local/bin/
docker run --rm -p 8080:8080 y4m4/s3www:latest \
-endpoint "https://s3.amazonaws.com" \
-accessKey "accessKey" \
-secretKey "secretKey" \
-bucket "mysite" \
-address "0.0.0.0:8080"
- Clone the repository:
git clone https://github.com/harshavardhana/s3www.git cd s3www
- Build the binary:
go build
- Move the binary to a directory in your PATH:
sudo mv s3www /usr/local/bin/
-
Basic Command: Serve files from an S3 bucket over HTTP:
s3www -endpoint "https://s3.amazonaws.com" \ -accessKey "accessKey" \ -secretKey "secretKey" \ -bucket "mysite"
Output:
s3www: Started listening on http://127.0.0.1:8080
Open
http://127.0.0.1:8080
in your browser to verify. -
With Let's Encrypt: Serve over HTTPS with automatic TLS certificates:
s3www -endpoint "https://s3.amazonaws.com" \ -accessKey "accessKey" \ -secretKey "secretKey" \ -bucket "mysite" \ -lets-encrypt \ -address "example.com"
Output:
s3www: Started listening on https://example.com
Open
https://example.com
in your browser. -
Single-Page Application (SPA): Serve an SPA by specifying a fallback file:
s3www -endpoint "https://s3.amazonaws.com" \ -accessKey "accessKey" \ -secretKey "secretKey" \ -bucket "mysite" \ -spa "index.html"
You can configure s3www via command-line flags or environment variables:
Flag | Environment Variable | Description | Default |
---|---|---|---|
-endpoint |
S3WWW_ENDPOINT |
S3 endpoint URL | |
-accessKey |
S3WWW_ACCESS_KEY |
S3 access key | |
-secretKey |
S3WWW_SECRET_KEY |
S3 secret key | |
-bucket |
S3WWW_BUCKET |
S3 bucket name | |
-address |
S3WWW_ADDRESS |
Host and port to listen on | 127.0.0.1:8080 |
-lets-encrypt |
Enable Let's Encrypt TLS | false |
|
-spa |
S3WWW_SPA |
Fallback file for SPA routing | |
-tls-cert |
S3WWW_TLS_CERT |
Path to TLS certificate file | |
-tls-key |
S3WWW_TLS_KEY |
Path to TLS key file |
Example using environment variables:
export S3WWW_ENDPOINT="https://s3.amazonaws.com"
export S3WWW_ACCESS_KEY="accessKey"
export S3WWW_SECRET_KEY="secretKey"
export S3WWW_BUCKET="mysite"
export S3WWW_ADDRESS="0.0.0.0:8080"
s3www
- Static Website Hosting: Serve HTML, CSS, and JavaScript files for blogs, portfolios, or documentation.
- Single-Page Applications: Host React, Vue, or Angular apps with proper routing.
- File Sharing: Share files securely from an S3 bucket over HTTPS.
- Development Testing: Quickly test static assets from S3 during development.
- 404 Errors: Ensure your bucket contains an
index.html
file or specify a custom SPA file with-spa
. - Permission Denied: Verify your S3 credentials have
s3:GetObject
ands3:ListBucket
permissions. - Let's Encrypt Issues: Ensure your domain is publicly accessible and port 80 is open for certificate issuance.
- Connection Errors: Check the S3 endpoint URL and your network connectivity.
We welcome contributions! To get started:
- Fork the repository.
- Create a feature branch (
git checkout -b feature-name
). - Commit your changes (
git commit -m "Add feature"
). - Push to the branch (
git push origin feature-name
). - Open a pull request.
Please read the CONTRIBUTING.md for details.
This project is licensed under the Apache License, Version 2.0. See LICENSE for more information.