From b3ffee9e7854fd8bcb4e4136e58d2d42813d5d88 Mon Sep 17 00:00:00 2001
From: zgaetano <zgaetano@wilddragon.net>
Date: Tue, 31 Mar 2026 15:35:25 -0400
Subject: [PATCH] Update README.md with documentation

---
 README.md | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 121 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index e93f764..bd5681e 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,122 @@
-# s3-uploader
+# FramelightX S3 Uploader
 
-Grassvalley AMPP S3 uploader utility
\ No newline at end of file
+A browser-based file upload tool for pushing media assets to any S3-compatible object storage endpoint (RustFS, MinIO, AWS S3, etc.). Built for broadcast and post-production environments where large files need to land in a managed folder structure.
+
+## Features
+
+- Upload up to 50 files at once (50GB max per file)
+- Hierarchical folder tree for organizing files into prefixed S3 keys
+- Multi-user authentication with admin and standard user roles
+- Optional live AMPP job monitoring panel (Grassvalley AMPP integration)
+- Blocks executable file uploads server-side
+- Persistent folder tree and user data stored in a Docker volume
+- Timeout-tolerant uploads — treats slow S3 acknowledgements as success rather than failing
+
+## Prerequisites
+
+- Docker and Docker Compose
+- An S3-compatible storage endpoint with access credentials
+- (Optional) A Grassvalley AMPP account and API key for job monitoring
+
+## Quick Start
+
+1. Clone the repo and copy the example env file:
+
+```bash
+cp .env.example .env
+```
+
+2. Edit `.env` with your credentials:
+
+```env
+S3_ENDPOINT=https://your-s3-endpoint.com
+S3_ACCESS_KEY=your-access-key
+S3_SECRET_KEY=your-secret-key
+S3_BUCKET=upload
+S3_REGION=us-east-1
+PORT=3000
+
+# Optional — enables the AMPP job monitoring panel
+AMPP_BASE_URL=https://us-east-1.gvampp.com
+AMPP_API_KEY=your-base64-encoded-client-credentials
+```
+
+3. Start the service:
+
+```bash
+docker compose up -d
+```
+
+4. Open `http://localhost:3000` in your browser.
+
+## Default Credentials
+
+On first run, a default admin account is created:
+
+| Username | Password |
+|----------|----------|
+| Admin | BertAndErnieVPM2026 |
+
+**Change this immediately** via the Admin panel after first login.
+
+## Folder Structure & S3 Keys
+
+The folder tree in the UI maps directly to S3 key prefixes. When you select a folder and upload files, the key is built as:
+
+```
+FolderA--SubFolder--filename.ext
+```
+
+Admins can add or remove folders from the tree. Default folders are: `Media`, `Dailies`, `VFX`, `Audio`.
+
+## User Roles
+
+| Role | Can Upload | Manage Users | Manage Folders |
+|------|-----------|-------------|----------------|
+| user | ✓ | ✗ | ✗ |
+| admin | ✓ | ✓ | ✓ |
+
+## AMPP Job Monitoring (Optional)
+
+When `AMPP_API_KEY` is configured, the dashboard displays a live panel showing the status of jobs running on the Grassvalley AMPP platform. The API key should be a Base64-encoded `client_id:client_secret` string, which is exchanged for a bearer token automatically using the OAuth2 client_credentials flow.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `S3_ENDPOINT` | `https://broadcastmgmt.cloud` | S3-compatible storage URL |
+| `S3_ACCESS_KEY` | — | S3 access key |
+| `S3_SECRET_KEY` | — | S3 secret key |
+| `S3_BUCKET` | `upload` | Target bucket name |
+| `S3_REGION` | `us-east-1` | S3 region |
+| `PORT` | `3000` | HTTP port to listen on |
+| `AUTH_USER` | `Admin` | Default admin username |
+| `AUTH_PASS` | `BertAndErnieVPM2026` | Default admin password |
+| `DATA_DIR` | `/data` | Path for persistent JSON data |
+| `AMPP_BASE_URL` | `https://us-east-1.gvampp.com` | AMPP API base URL |
+| `AMPP_API_KEY` | — | Base64 client credentials for AMPP OAuth2 |
+
+## Docker Compose
+
+```yaml
+services:
+  s3-uploader:
+    build: .
+    ports:
+      - "3000:3000"
+    volumes:
+      - uploader-data:/data
+    env_file: .env
+    restart: unless-stopped
+
+volumes:
+  uploader-data:
+```
+
+## File Upload Security
+
+The following file extensions are blocked from uploading regardless of user role:
+
+`exe`, `sh`, `bash`, `bat`, `cmd`, `ps1`, `msi`, `dll`, `py`, `rb`, `php`, `jar`, `apk`, and others.
+
+Blocked uploads are rejected at the server level — the file never reaches S3.