Skip to content

Commit 7706c19

Browse files
harshavardhanaharshavardhana
committed
update README.md and add CONTRIBUTING.md
1 parent 6c0bef3 commit 7706c19

2 files changed

Lines changed: 256 additions & 63 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Contributing to s3www
2+
3+
Thank you for your interest in contributing to s3www! This project is a lightweight tool for serving static files from S3-compatible storage, and we welcome contributions from the community to improve its features, performance, and usability. Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.
4+
5+
## How to Contribute
6+
7+
### Reporting Issues
8+
9+
If you encounter bugs, have feature requests, or find areas for improvement:
10+
11+
1. Check the [GitHub Issues](https://github.com/harshavardhana/s3www/issues) page to see if the issue already exists.
12+
2. If not, open a new issue with a clear title and description, including:
13+
- Steps to reproduce the issue (if applicable).
14+
- Expected and actual behavior.
15+
- Relevant details like your operating system, s3www version, and S3 provider.
16+
17+
### Submitting Changes
18+
19+
To contribute code or documentation:
20+
21+
1. **Fork the Repository**:
22+
- Fork the [s3www repository](https://github.com/harshavardhana/s3www) to your GitHub account.
23+
- Clone your fork:
24+
```bash
25+
git clone https://github.com/<your-username>/s3www.git
26+
cd s3www
27+
```
28+
29+
2. **Create a Branch**:
30+
- Create a new branch for your changes:
31+
```bash
32+
git checkout -b feature/<feature-name> # For new features
33+
# or
34+
git checkout -b fix/<bug-name> # For bug fixes
35+
```
36+
37+
3. **Make Changes**:
38+
- Follow the project’s coding style (e.g., adhere to Go conventions for code).
39+
- Keep changes focused and commit messages clear (e.g., `Add support for custom CORS headers`).
40+
- Update tests if applicable (located in the `*_test.go` files).
41+
- If modifying documentation, ensure clarity and consistency with the `README.md`.
42+
43+
4. **Test Your Changes**:
44+
- Build and test locally:
45+
```bash
46+
go build
47+
go test ./...
48+
```
49+
- Verify your changes work with an S3-compatible bucket.
50+
51+
5. **Commit and Push**:
52+
- Commit your changes with a descriptive message:
53+
```bash
54+
git commit -m "Add feature X to improve Y"
55+
```
56+
- Push your branch to your fork:
57+
```bash
58+
git push origin feature/<feature-name>
59+
```
60+
61+
6. **Open a Pull Request**:
62+
- Go to the [s3www repository](https://github.com/harshavardhana/s3www) and open a pull request from your branch.
63+
- Provide a clear description of your changes, referencing any related issues (e.g., `Fixes #123`).
64+
- Ensure your PR passes any automated checks (e.g., CI tests).
65+
66+
## Code of Conduct
67+
68+
- Be respectful and inclusive in all interactions.
69+
- Follow the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html).
70+
- Avoid personal attacks, harassment, or discriminatory language.
71+
72+
## Development Guidelines
73+
74+
- **Code Style**: Follow Go’s standard formatting (`go fmt`) and conventions. Use meaningful variable names and include comments for complex logic.
75+
- **Testing**: Add or update tests for new features or bug fixes. Ensure tests pass before submitting a PR.
76+
- **Documentation**: Update `README.md` or other docs if your changes affect usage or configuration.
77+
- **Dependencies**: Avoid adding new dependencies unless necessary, and justify their inclusion in your PR.
78+
79+
## Areas for Contribution
80+
81+
- **Bug Fixes**: Address issues listed in the [GitHub Issues](https://github.com/harshavardhana/s3www/issues) page.
82+
- **Features**: Add support for new S3 providers, enhance SPA routing, or improve performance.
83+
- **Documentation**: Clarify setup instructions, add examples, or create tutorials.
84+
- **Testing**: Improve test coverage or add integration tests for different S3 providers.
85+
86+
## Getting Help
87+
88+
If you have questions or need assistance:
89+
- Open an issue with the `question` label.
90+
- Reach out to the maintainers via the [GitHub Discussions](https://github.com/harshavardhana/s3www/discussions) page (if available).
91+
- Check the [README.md](README.md) for setup and usage details.
92+
93+
## License
94+
95+
By contributing, you agree that your contributions will be licensed under the [Apache License, Version 2.0](LICENSE).
96+
97+
Thank you for helping make s3www better!

‎README.md‎

Lines changed: 159 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,180 @@
1-
![s3www](https://raw.githubusercontent.com/harshavardhana/s3www/master/s3www.png)
1+
# s3www: Serve Static Files from S3-Compatible Storage
22

3-
Serve static files from any S3 compatible object storage endpoints.
4-
5-
> Simplifies and secure [AWS S3 Static Website Hosting](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html) by keeping your bucket private, secure, run-anywhere you like and with Automatic TLS based on Let's Encrypt.
3+
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.
64

75
## Features
8-
- Automatic credentials rotation when deployed on AWS EC2, ECS or EKS services for your AWS S3 buckets - yay! 🔒😍
9-
- Automatic certs renewal for your DOMAIN along with OCSP stapling, full suite of ACME features, HTTP->HTTPS redirection (all thanks to [certmagic](https://github.com/caddyserver/certmagic)).
106

11-
## Install
12-
Released binaries are available [here](https://github.com/harshavardhana/s3www/releases), or you can compile yourself from source.
7+
- **S3 Compatibility**: Works with any S3-compatible storage provider.
8+
- **HTTPS Support**: Automatic TLS certificates via Let's Encrypt.
9+
- **Lightweight**: Built in Go for performance and minimal resource usage.
10+
- **SPA Support**: Configurable single-page application routing.
11+
- **Customizable**: Supports custom error pages and CORS configuration.
12+
- **Cross-Platform**: Runs on Linux, macOS, FreeBSD, and more.
1313

14-
> NOTE: minimum Go version needed is v1.18
14+
## Prerequisites
1515

16-
```
17-
go install github.com/harshavardhana/s3www@latest
16+
- An S3-compatible storage bucket with static files (e.g., `index.html`).
17+
- S3 credentials with `s3:GetObject` and `s3:ListBucket` permissions.
18+
- Go 1.21+ (for building from source) or Docker/Podman (for containerized deployment).
19+
- Network access to your S3 endpoint and port 8080 (or your chosen port).
20+
21+
### Required S3 Permissions
22+
23+
```json
24+
{
25+
"Version": "2012-10-17",
26+
"Statement": [
27+
{
28+
"Sid": "AllowGetObject",
29+
"Effect": "Allow",
30+
"Action": "s3:GetObject",
31+
"Resource": "arn:aws:s3:::<Bucket Name>/*"
32+
},
33+
{
34+
"Sid": "AllowListBucket",
35+
"Effect": "Allow",
36+
"Action": "s3:ListBucket",
37+
"Resource": "arn:aws:s3:::<Bucket Name>"
38+
}
39+
]
40+
}
1841
```
1942

20-
## Binary
21-
Make sure you have `index.html` under `mysite`
43+
## Installation
44+
45+
### Option 1: Download Prebuilt Binaries
46+
47+
1. Visit the [Releases page](https://github.com/harshavardhana/s3www/releases) and download the binary for your platform (e.g., `s3www_0.9.0_linux_amd64.tar.gz`).
48+
2. Extract the archive:
49+
```bash
50+
tar -xzf s3www_0.9.0_linux_amd64.tar.gz
51+
```
52+
3. Move the binary to a directory in your PATH:
53+
```bash
54+
sudo mv s3www /usr/local/bin/
55+
```
56+
57+
### Option 2: Run with Docker
58+
59+
```bash
60+
docker run --rm -p 8080:8080 y4m4/s3www:latest \
61+
-endpoint "https://s3.amazonaws.com" \
62+
-accessKey "accessKey" \
63+
-secretKey "secretKey" \
64+
-bucket "mysite" \
65+
-address "0.0.0.0:8080"
2266
```
23-
s3www -endpoint "https://s3.amazonaws.com" -accessKey "accessKey" \
24-
-secretKey "secretKey" -bucket "mysite"
2567

26-
s3www: Started listening on http://127.0.0.1:8080
68+
### Option 3: Build from Source
69+
70+
1. Clone the repository:
71+
```bash
72+
git clone https://github.com/harshavardhana/s3www.git
73+
cd s3www
74+
```
75+
2. Build the binary:
76+
```bash
77+
go build
78+
```
79+
3. Move the binary to a directory in your PATH:
80+
```bash
81+
sudo mv s3www /usr/local/bin/
82+
```
83+
84+
## Usage
85+
86+
1. **Basic Command**:
87+
Serve files from an S3 bucket over HTTP:
88+
```bash
89+
s3www -endpoint "https://s3.amazonaws.com" \
90+
-accessKey "accessKey" \
91+
-secretKey "secretKey" \
92+
-bucket "mysite"
93+
```
94+
Output:
95+
```
96+
s3www: Started listening on http://127.0.0.1:8080
97+
```
98+
Open `http://127.0.0.1:8080` in your browser to verify.
99+
100+
2. **With Let's Encrypt**:
101+
Serve over HTTPS with automatic TLS certificates:
102+
```bash
103+
s3www -endpoint "https://s3.amazonaws.com" \
104+
-accessKey "accessKey" \
105+
-secretKey "secretKey" \
106+
-bucket "mysite" \
107+
-lets-encrypt \
108+
-address "example.com"
109+
```
110+
Output:
111+
```
112+
s3www: Started listening on https://example.com
113+
```
114+
Open `https://example.com` in your browser.
115+
116+
3. **Single-Page Application (SPA)**:
117+
Serve an SPA by specifying a fallback file:
118+
```bash
119+
s3www -endpoint "https://s3.amazonaws.com" \
120+
-accessKey "accessKey" \
121+
-secretKey "secretKey" \
122+
-bucket "mysite" \
123+
-spa "index.html"
124+
```
125+
126+
## Configuration
127+
128+
You can configure s3www via command-line flags or environment variables:
129+
130+
| Flag | Environment Variable | Description | Default |
131+
|------------------|------------------------|------------------------------------------|----------------------|
132+
| `-endpoint` | `S3WWW_ENDPOINT` | S3 endpoint URL | |
133+
| `-accessKey` | `S3WWW_ACCESS_KEY` | S3 access key | |
134+
| `-secretKey` | `S3WWW_SECRET_KEY` | S3 secret key | |
135+
| `-bucket` | `S3WWW_BUCKET` | S3 bucket name | |
136+
| `-address` | `S3WWW_ADDRESS` | Host and port to listen on | `127.0.0.1:8080` |
137+
| `-lets-encrypt` | | Enable Let's Encrypt TLS | `false` |
138+
| `-spa` | `S3WWW_SPA` | Fallback file for SPA routing | |
139+
| `-tls-cert` | `S3WWW_TLS_CERT` | Path to TLS certificate file | |
140+
| `-tls-key` | `S3WWW_TLS_KEY` | Path to TLS key file | |
141+
142+
Example using environment variables:
143+
```bash
144+
export S3WWW_ENDPOINT="https://s3.amazonaws.com"
145+
export S3WWW_ACCESS_KEY="accessKey"
146+
export S3WWW_SECRET_KEY="secretKey"
147+
export S3WWW_BUCKET="mysite"
148+
export S3WWW_ADDRESS="0.0.0.0:8080"
149+
s3www
27150
```
28151

29-
Point your web browser to http://127.0.0.1:8080 ensure your `s3www` is serving your `index.html` successfully.
152+
## Use Cases
30153

31-
## Container
32-
Make sure you have `index.html` under `mysite`
154+
- **Static Website Hosting**: Serve HTML, CSS, and JavaScript files for blogs, portfolios, or documentation.
155+
- **Single-Page Applications**: Host React, Vue, or Angular apps with proper routing.
156+
- **File Sharing**: Share files securely from an S3 bucket over HTTPS.
157+
- **Development Testing**: Quickly test static assets from S3 during development.
33158

34-
```
35-
podman run --rm -p 8080:8080 y4m4/s3www:latest \
36-
-endpoint "https://s3.amazonaws.com" \
37-
-accessKey "accessKey" \
38-
-secretKey "secretKey" \
39-
-bucket "mysite" \
40-
-address "0.0.0.0:8080"
41-
42-
s3www: Started listening on http://0.0.0.0:8080
43-
```
159+
## Troubleshooting
44160

45-
Point your web browser to http://127.0.0.1:8080 ensure your `s3www` is serving your `index.html` successfully.
161+
- **404 Errors**: Ensure your bucket contains an `index.html` file or specify a custom SPA file with `-spa`.
162+
- **Permission Denied**: Verify your S3 credentials have `s3:GetObject` and `s3:ListBucket` permissions.
163+
- **Let's Encrypt Issues**: Ensure your domain is publicly accessible and port 80 is open for certificate issuance.
164+
- **Connection Errors**: Check the S3 endpoint URL and your network connectivity.
46165

47-
## Auto TLS
48-
Make sure you have `index.html` under `mysite`
49-
```
50-
s3www -endpoint "https://s3.amazonaws.com" -accessKey "accessKey" \
51-
-secretKey "secretKey" -bucket "mysite" \
52-
-lets-encrypt -address "example.com"
166+
## Contributing
53167

54-
s3www: Started listening on https://example.com
55-
```
168+
We welcome contributions! To get started:
56169

57-
Point your web browser to https://example.com ensure your `s3www` is serving your `index.html` successfully.
170+
1. Fork the repository.
171+
2. Create a feature branch (`git checkout -b feature-name`).
172+
3. Commit your changes (`git commit -m "Add feature"`).
173+
4. Push to the branch (`git push origin feature-name`).
174+
5. Open a pull request.
58175

59-
## Permissions
176+
Please read the [CONTRIBUTING.md](CONTRIBUTING.md) for details.
60177

61-
### AWS IAM Policy
62-
s3www requires access to view and list all files in the bucket.
178+
## License
63179

64-
```
65-
{
66-
"Version": "2012-10-17",
67-
"Statement": [
68-
{
69-
"Sid": "",
70-
"Effect": "Allow",
71-
"Action": "s3:GetObject",
72-
"Resource": "arn:aws:s3:::<Bucket Name>/*"
73-
},
74-
{
75-
"Sid": "",
76-
"Effect": "Allow",
77-
"Action": "s3:ListBucket",
78-
"Resource": "arn:aws:s3:::<Bucket Name>"
79-
}
80-
]
81-
}
82-
```
83-
# License
84-
This project is distributed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0), see [LICENSE](./LICENSE) for more information.
180+
This project is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for more information.

0 commit comments

Comments
 (0)