kaa1bhairav/s3-manager repository overview

⁠S3 Manager

A self-hosted web UI for managing S3 and S3-compatible buckets: register one or more S3 connections (endpoint, region, access key/secret), browse and manage bucket contents, preview text files inline, share connections with other users at different permission levels, and review a full audit trail of who did what and when. Ships as a single Docker image with an embedded MongoDB, or point it at your own external MongoDB.

⁠Stack

• Frontend: Next.js (App Router) + shadcn/ui, TanStack Query
• Backend: Go (chi router), AWS SDK v2 for S3 (works with any S3-compatible endpoint)
• Database: MongoDB — embedded in the container by default, or external via MONGO_URI
• Packaging: one Docker image, port 3000. Next.js proxies /api/* to the Go backend on 127.0.0.1:8080; supervisord manages mongod (if embedded), the Go binary, and the Next.js server inside the container.

⁠Prerequisites

⁠Building

⁠The Docker image (recommended — this is the only artifact most people need)

From the project root:

docker build -f docker/Dockerfile -t s3-manager .

This is a multi-stage build:

1. frontend-builder (node:22-alpine) — npm ci + next build (standalone output).
2. backend-builder (golang:1.25-alpine) — static Go binary (CGO_ENABLED=0).
3. Final stage — based on mongo:7 (so mongod ships for free), with Node 22 added to run the Next.js standalone server, plus supervisord to manage all three processes. Everything lands in one image; nothing is downloaded at container start.

Tag a specific version if you want to keep old images around:

docker build -f docker/Dockerfile -t s3-manager:1.0.0 .

⁠Backend only (Go binary)

cd backend
go build -o s3-manager-server ./cmd/server

Produces a single static binary at backend/s3-manager-server. Run it directly with MONGO_URI, JWT_SECRET, ENCRYPTION_KEY, etc. set as environment variables (see below).

⁠Frontend only (production build)

cd frontend
npm install
npm run build   # writes .next/standalone
npm run start   # serves it on :3000

Set INTERNAL_API_URL to point the frontend's /api/* proxy at wherever the backend is running (defaults to http://127.0.0.1:8080).

⁠Running with Docker

⁠Embedded MongoDB (default), default 2GB storage cap

docker run -d --name s3-manager -p 3000:3000 \
  -e JWT_SECRET="$(openssl rand -hex 32)" \
  -e ENCRYPTION_KEY="$(openssl rand -hex 32)" \
  -e ADMIN_EMAIL="[email protected]" \
  -e ADMIN_PASSWORD="12345678" \
  -v s3manager_data:/data/db \
  s3-manager

Open http://localhost:3000⁠ and log in with the admin credentials above.

⁠Embedded MongoDB, custom storage cap

Add -e MAX_DB_SIZE_MB=5120 (defaults to 2048). This is a soft, app-enforced budget: the backend polls MongoDB's own storage stats and prunes the oldest audit log entries as usage approaches the limit; once it's fully exceeded, new connections/uploads/shares are blocked until usage drops back down. No privileged container flags are required.

⁠External MongoDB instead of the embedded one

docker run -d --name s3-manager -p 3000:3000 \
  -e MONGO_URI="mongodb+srv://user:pass@your-cluster/dbname" \
  -e JWT_SECRET="$(openssl rand -hex 32)" \
  -e ENCRYPTION_KEY="$(openssl rand -hex 32)" \
  -e ADMIN_EMAIL="[email protected]" \
  -e ADMIN_PASSWORD="12345678" \
  s3-manager

When MONGO_URI is set, the embedded mongod process never starts.

⁠Environment variables

The workspace admin is seeded once from ADMIN_EMAIL/ADMIN_PASSWORD — there is exactly one admin account, not "whoever signs up first". Every signup after that is a regular member. Admins can view every user, every connection's activity, and can promote, demote, or remove users from the Admin → Users page. Connection owners can share a connection with other users as viewer (read/download/list) or editor (upload/delete/create folder/rename), enforced server-side on every request — shared connections automatically appear in the recipient's own S3 Connections list.

⁠Local development (without Docker)

docker compose -f docker-compose.dev.yml up

This starts MongoDB, the Go backend (go run, live in a mounted volume), and the Next.js dev server, wired together with the same env vars used in production. Visit http://localhost:3000⁠.

Alternatively, run each piece natively:

# MongoDB (any local instance, or `docker run -p 27017:27017 mongo:7`)

# Backend
cd backend
MONGO_URI=mongodb://127.0.0.1:27017 JWT_SECRET=dev ENCRYPTION_KEY=dev \
  [email protected] ADMIN_PASSWORD=devpassword123 \
  go run ./cmd/server

# Frontend
cd frontend
npm install
npm run dev

⁠Project layout

backend/     Go API (auth, S3 connections, bucket browser, sharing, audit, DB quota)
frontend/    Next.js + shadcn/ui dashboard
docker/      Dockerfile, entrypoint.sh, supervisord.conf.template