S3 Web Browser - Go Edition

Because clicking through the AWS console is a form of torture we've all silently accepted.

A fast, modern S3-compatible storage browser built with Go. It works on your machine, in Docker, and probably in production too (no promises).

What Does This Thing Do?

• Browse S3 buckets like it's 2026 and we have UIs now
• Download files through the server so your presigned URLs stay where they belong: hidden
• View files in browser (images, PDFs, videos, text - your browser will thank you)
• Dark mode because we're not savages
• Mobile-responsive for when you're debugging S3 from the toilet (we know)
• Fast because it's Go, what did you expect
• Single binary (~10MB Docker image, smaller than your node_modules)

Works With (AKA "Supported Backends")

• AWS S3 (the OG)
• MinIO (the cool self-hosted cousin)
• RustFS (if you know, you know)
• SeaweedFS (sounds fake, works great)
• GarageHQ (French engineering, no surrender)
• Literally anything with an S3-compatible API

Quick Start

Docker (The "I Don't Want To Install Go" Route)

# Clone it (you know the drill)
git clone https://git.nghia.app/nghialele/s3-browser.git
cd s3-browser

# Copy the env file and fill in your secrets
cp .env.example .env
# (Yes, you actually have to edit it. I can't do everything.)

# Ship it
docker compose up -d

# Open http://localhost:8000 and try not to break anything

Local Development (For The Brave)

# You need Go 1.26+ (if you're on 1.25, what are you doing with your life?)
git clone https://git.nghia.app/nghialele/s3-browser.git
cd s3-browser

cp .env.example .env

# Build it
make -f Makefile.go build

# Run it (fingers crossed)
./s3-browser

Configuration

Create a .env file. Copy-paste this and replace the placeholder values. You've done this before.

# Where your files live
S3_BACKEND=rustfs
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_DEFAULT_REGION=us-east-1
AWS_ENDPOINT_URL=https://s3.nghia.pm
S3_ADDRESSING_STYLE=path

# The server stuff
PORT=8000
PAGE_ITEMS=100

# Optional: Lock it down with basic auth
# (Leave empty if you like to live dangerously)
BASIC_AUTH_USER=
BASIC_AUTH_PASS=

Makefile Commands

For those who prefer make over remembering random commands:

make -f Makefile.go build        # Build the binary (fancy)
make -f Makefile.go run          # Build AND run (two birds, one stone)
make -f Makefile.go test         # Run tests (please do this)
make -f Makefile.go docker-build # Build Docker image (containerize all the things)
make -f Makefile.go compose-up   # Docker compose up (the full send)

Architecture

s3-browser/
├── cmd/s3-browser/     # The main() - where dreams begin
├── config/             # Reading .env files so you don't have to
├── handlers/           # HTTP handlers (the business logic party)
├── storage/            # S3 backend interface (abstraction is beautiful)
├── templates/          # Go HTML templates (yes, we write HTML by hand)
├── Dockerfile.go       # Multi-stage build (because we're professionals)
├── docker-compose.go.yml
└── Makefile.go         # make build go brrrr

The Cool Stuff

Proxy Downloads

Files stream through Go like a well-oiled machine:

• Clean URLs that don't expose your S3 secrets to the world
• Proper Content-Type headers (your browser will know what hit it)
• Access control ready (for when you finally implement auth)

View In Browser

• Images render inline (no more "right-click, Save As")
• PDFs open in the browser viewer (RIP your RAM)
• Videos play directly (buffering not included)
• Text files display in-browser (cat > vim, fight me)

Dark Mode

• Detects your system preference (we're not mind readers, but close)
• Manual toggle that actually persists (localStorage, baby)
• Smooth transitions (because we care about the little things)
• Looks good in both modes (trust the process)

API Routes

Where the magic happens:

• GET / - See all your buckets (the root of all data)
• GET /buckets/:bucket - Dive into a bucket (careful, it's deep)
• GET /download/buckets/:bucket/* - Yoink a file
• GET /view/buckets/:bucket/* - Look at a file without downloading (fancy)

Docker

Build The Image

docker build -f Dockerfile.go -t s3-browser .
# Congrats, you just containerized a container browser. How meta.

Run The Container

docker run -d \
  --name s3-browser \
  -p 8000:8000 \
  --env-file .env \
  s3-browser
# Now go check if it works before you forget what you just did

License

LELE SILLY LICENSE v6.9 - See LICENSE for the full chaotic legal document.

TL;DR: Do whatever you want. Just don't be a dick. If it breaks, you get to keep both pieces.

Credits

Built with love, caffeine, and questionable life choices using:

• Go - Because waiting for compile times builds character
• Echo - HTTP framework that doesn't make you cry
• aws-sdk-go-v2 - Talking to S3 without tears
• Tailwind CSS - CSS that writes itself (almost)

---

If this project made your life 1% easier, that's a win. If it made it worse, well... check the LICENSE.