From 11c62009a4d6c6267a490cd7eea7bab26c65075a Mon Sep 17 00:00:00 2001
From: Nikholas Pcenicni <82239765+nikpcenicni@users.noreply.github.com>
Date: Sat, 28 Mar 2026 18:20:55 -0400
Subject: [PATCH] Update README.md, .env.sample, and compose.yaml for Versity
 S3 Gateway to clarify WebUI configuration. Enhance README with details on
 separate API and WebUI ports, and update .env.sample and compose.yaml to
 include WebUI settings for improved deployment instructions and usability.

---
 README.md                        | 2 +-
 komodo/s3/versitygw/.env.sample  | 7 +++++++
 komodo/s3/versitygw/compose.yaml | 9 +++++++++
 3 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 81834a7..d9090c6 100644
--- a/README.md
+++ b/README.md
@@ -182,7 +182,7 @@ Shared services used across multiple applications.
 
 ### versitygw/ (`komodo/s3/versitygw/`)
 
-- **[Versity S3 Gateway](https://github.com/versity/versitygw)** (Port: 10000 by default) - S3-compatible API over a POSIX directory (named Docker volumes). Use as shared object storage for apps that expect S3; pair with clients using path-style URLs and your LAN hostname or reverse proxy.
+- **[Versity S3 Gateway](https://github.com/versity/versitygw)** — S3 API on port **10000** by default; optional **WebUI** on **8080** (not the same listener—enable `VERSITYGW_WEBUI_PORT` / `VGW_WEBUI_GATEWAYS` per `.env.sample`). Behind **Pangolin**, expose the API and WebUI separately (or you will see **404** browsing the API URL).
 
 **Configuration:** Set either `ROOT_ACCESS_KEY` / `ROOT_SECRET_KEY` or `ROOT_ACCESS_KEY_ID` / `ROOT_SECRET_ACCESS_KEY`. Optional `VERSITYGW_PORT`. Compose uses `${VAR}` interpolation so credentials work with Komodo’s `docker compose --env-file <run_directory>/.env` (avoid `env_file:` in the service when `run_directory` is not the same folder as `compose.yaml`, or the written `.env` will not be found).
 
diff --git a/komodo/s3/versitygw/.env.sample b/komodo/s3/versitygw/.env.sample
index 387995b..c44fd38 100644
--- a/komodo/s3/versitygw/.env.sample
+++ b/komodo/s3/versitygw/.env.sample
@@ -18,6 +18,13 @@ ROOT_SECRET_KEY=
 # Host port mapped to the gateway (container listens on 10000).
 VERSITYGW_PORT=10000
 
+# WebUI (container listens on 8080). In Pangolin, create a *second* HTTP resource for this
+# port — do not point the UI hostname at :10000 (that is S3 API only; `/` is not the SPA).
+VERSITYGW_WEBUI_PORT=8080
+# HTTPS URL clients use for the S3 API (must match your Pangolin route to :10000), e.g.:
+# VGW_WEBUI_GATEWAYS=https://s3.example.com
+VGW_WEBUI_GATEWAYS=
+
 # NFS: object metadata defaults to xattrs; most NFS mounts need sidecar mode
 # (compose.yaml uses --sidecar /data/sidecar). Create the host path, e.g.
 #   mkdir -p /mnt/nfs/versity/sidecar
diff --git a/komodo/s3/versitygw/compose.yaml b/komodo/s3/versitygw/compose.yaml
index 8b58324..b5cfbdc 100644
--- a/komodo/s3/versitygw/compose.yaml
+++ b/komodo/s3/versitygw/compose.yaml
@@ -21,8 +21,14 @@ services:
       ROOT_SECRET_ACCESS_KEY: ${ROOT_SECRET_ACCESS_KEY}
       # Matches Helm chart default; enables `/_/health` for probes.
       VGW_HEALTH: /_/health
+      # WebUI (browser): separate listener; TLS terminates at Pangolin — serve HTTP in-container.
+      VGW_WEBUI_NO_TLS: "true"
+      # Public base URL of the *S3 API* (same host you expose on port 10000 via Pangolin).
+      # Required for the WebUI JS to call the gateway (see Versity wiki / chart notes).
+      VGW_WEBUI_GATEWAYS: ${VGW_WEBUI_GATEWAYS}
     ports:
       - "${VERSITYGW_PORT:-10000}:10000"
+      - "${VERSITYGW_WEBUI_PORT:-8080}:8080"
     volumes:
       - /mnt/nfs/versity/s3:/data/s3
       - /mnt/nfs/versity/iam:/data/iam
@@ -31,6 +37,9 @@ services:
     command:
       - "--port"
       - ":10000"
+      # Optional WebUI — without this, only the S3 API is served (browsers often see 404 on `/`).
+      - "--webui"
+      - ":8080"
       - "--iam-dir"
       - "/data/iam"
       - "posix"