s3-uploader/README.md

FramelightX S3 Uploader

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:

cp .env.example .env

2. Edit .env with your credentials:

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:

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

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.