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:

```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.