From 7c95c8c5c32b6904abff23c09ed823177b4dfef3 Mon Sep 17 00:00:00 2001
From: g-roliveira <125938946+g-roliveira@users.noreply.github.com>
Date: Mon, 16 Feb 2026 10:58:37 -0300
Subject: [PATCH] docs: document S3-compatible URI parameters and examples

---
 .env.template | 18 +++++++++++++++++-
 README.md     | 30 ++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/.env.template b/.env.template
index 67f531fc..564c7027 100644
--- a/.env.template
+++ b/.env.template
@@ -18,7 +18,23 @@
 ## This can be a path to local folder or a path to an external location
 ## depending on features enabled at build time. Possible external locations:
 ##
-## - AWS S3 Bucket (via `s3` feature): s3://bucket-name/path/to/folder
+## - S3-compatible bucket (via `s3` feature): s3://bucket-name/path/to/folder
+##
+## Optional query parameters are supported for S3-compatible providers:
+## - endpoint (MinIO/R2/Ceph RGW): ?endpoint=https%3A%2F%2Fs3.example.internal
+## - enable_virtual_host_style (set false for path-style): ?enable_virtual_host_style=false
+## - default_storage_class: ?default_storage_class=STANDARD
+##   Use an empty value to omit the storage-class header:
+##   ?default_storage_class=
+## - region (provider/signing specific): ?region=us-east-1
+##
+## Examples:
+## - AWS S3 defaults: s3://bucket-name/path/to/folder
+## - MinIO path-style: s3://bucket-name/path/to/folder?endpoint=http%3A%2F%2Fminio%3A9000&enable_virtual_host_style=false&default_storage_class=STANDARD
+## - Cloudflare R2: s3://bucket-name/path/to/folder?endpoint=https%3A%2F%2F<accountid>.r2.cloudflarestorage.com&region=auto&default_storage_class=
+##
+## Credentials in URI query params are supported as a last resort, but it is
+## strongly recommended to use environment credentials/IAM instead.
 ##
 ## When using an external location, make sure to set TMP_FOLDER,
 ## TEMPLATES_FOLDER, and DATABASE_URL to local paths and/or a remote database
diff --git a/README.md b/README.md
index c84a9c40..0a4e4b4d 100644
--- a/README.md
+++ b/README.md
@@ -111,6 +111,36 @@ services:
 
 <br>
 
+### S3-Compatible Object Storage
+
+When built with the `s3` feature, storage paths like `DATA_FOLDER`, `ATTACHMENTS_FOLDER`, `ICON_CACHE_FOLDER` and `SENDS_FOLDER` can use `s3://` URIs with query parameters:
+
+```text
+s3://bucket/prefix?endpoint=https%3A%2F%2Fs3.example.internal&enable_virtual_host_style=false&default_storage_class=STANDARD
+```
+
+- AWS S3 works with defaults (no extra parameters required).
+- MinIO/Ceph usually require `endpoint` and `enable_virtual_host_style=false`.
+- Cloudflare R2 usually requires `endpoint` and often `region=auto`.
+- To omit `x-amz-storage-class`, set `default_storage_class=` (empty value).
+
+Kubernetes example:
+
+```yaml
+env:
+  - name: DATA_FOLDER
+    value: "s3://vaultwarden-data/prod?endpoint=https%3A%2F%2Fs3.example.internal&enable_virtual_host_style=false&default_storage_class=STANDARD"
+  - name: DATABASE_URL
+    valueFrom:
+      secretKeyRef:
+        name: vaultwarden-db
+        key: url
+```
+
+Use IAM/service account/environment credentials when possible. URI credentials are supported as a last resort.
+
+<br>
+
 ## Get in touch
 
 Have a question, suggestion or need help? Join our community on [Matrix](https://matrix.to/#/#vaultwarden:matrix.org), [GitHub Discussions](https://github.com/dani-garcia/vaultwarden/discussions) or [Discourse Forums](https://vaultwarden.discourse.group/).