From 03ed4e70a227ab5b6f28e174456b45c9c180d6e7 Mon Sep 17 00:00:00 2001
From: Nikholas Pcenicni <82239765+nikpcenicni@users.noreply.github.com>
Date: Sat, 28 Mar 2026 18:17:54 -0400
Subject: [PATCH] Enhance .env.sample and compose.yaml for Versity S3 Gateway
 by adding detailed comments on NFS metadata handling and sidecar mode. This
 improves documentation clarity for users configuring NFS mounts and metadata
 storage options.

---
 komodo/s3/versitygw/.env.sample  |  5 +++++
 komodo/s3/versitygw/compose.yaml | 12 +++++++-----
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/komodo/s3/versitygw/.env.sample b/komodo/s3/versitygw/.env.sample
index 7b3ae80..387995b 100644
--- a/komodo/s3/versitygw/.env.sample
+++ b/komodo/s3/versitygw/.env.sample
@@ -17,3 +17,8 @@ ROOT_SECRET_KEY=
 
 # Host port mapped to the gateway (container listens on 10000).
 VERSITYGW_PORT=10000
+
+# 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
+# Or use NFSv4.2 with xattr support and remove --sidecar from compose if you prefer.
diff --git a/komodo/s3/versitygw/compose.yaml b/komodo/s3/versitygw/compose.yaml
index 9460562..8b58324 100644
--- a/komodo/s3/versitygw/compose.yaml
+++ b/komodo/s3/versitygw/compose.yaml
@@ -1,5 +1,9 @@
 # Versity S3 Gateway — POSIX backend over Docker volumes.
 # https://github.com/versity/versitygw
+#
+# POSIX default metadata uses xattrs; NFS often lacks xattr support unless NFSv4.2
+# + client/server support. `--sidecar` stores metadata in files instead (see
+# `posix` flags / VGW_META_SIDECAR in cmd/versitygw/posix.go).
 services:
   versitygw:
     image: versity/versitygw:v1.3.1
@@ -23,12 +27,15 @@ services:
       - /mnt/nfs/versity/s3:/data/s3
       - /mnt/nfs/versity/iam:/data/iam
       - /mnt/nfs/versity/versions:/data/versions
+      - /mnt/nfs/versity/sidecar:/data/sidecar
     command:
       - "--port"
       - ":10000"
       - "--iam-dir"
       - "/data/iam"
       - "posix"
+      - "--sidecar"
+      - "/data/sidecar"
       - "--versioning-dir"
       - "/data/versions"
       - "/data/s3"
@@ -44,8 +51,3 @@ services:
       timeout: 5s
       retries: 3
       start_period: 10s
-
-volumes:
-  s3_data:
-  iam:
-  versions: