From d1dadb2210dbaa51743a1bc522ba1b5fe963eccb Mon Sep 17 00:00:00 2001
From: "Foluso ADEBISI (DevBox Aux)" <adebisi-fa@live.com>
Date: Thu, 1 Oct 2026 03:17:52 +0100
Subject: [PATCH] docs: dotenvx workflow for env files

.env.example moves to the repository root with dotenvx setup/run notes; the
README documents 'dotenvx run -f .env -- node tools/server.js' and the
Docker caveat (--env-file cannot read encrypted values).
---
 tools/.env.example => .env.example |  9 +++++++++
 README.md                          | 19 +++++++++++++++----
 2 files changed, 24 insertions(+), 4 deletions(-)
 rename tools/.env.example => .env.example (51%)

diff --git a/tools/.env.example b/.env.example
similarity index 51%
rename from tools/.env.example
rename to .env.example
index 2187fc9..ca111dd 100644
--- a/tools/.env.example
+++ b/.env.example
@@ -1,6 +1,15 @@
 # Image Cropper service credentials — the ONLY environment variables this app
 # uses. Everything else (URLs, port, domain catalog) is hardcoded in source.
 # Without these the rest of the app works and /cropper answers 503.
+#
+# This repository uses dotenvx-encrypted env files (.env, .env.production);
+# the private keys live in .env.keys (gitignored). To set up or change a value:
+#
+#   cp .env.example .env
+#   dotenvx set MINIO_SECRET_KEY "<value>" -f .env
+#   # then commit the encrypted .env
+#
+# Run locally:  dotenvx run -f .env -- node tools/server.js
 MINIO_ACCESS_KEY=
 MINIO_SECRET_KEY=
 AZURE_STORAGE_CONNECTION_STRING=
diff --git a/README.md b/README.md
index 483ddd0..7786a40 100644
--- a/README.md
+++ b/README.md
@@ -72,8 +72,9 @@ identity photos. It reuses the YOUreka session for identity, requires the
 against the portal's OpenFGA endpoint — live on save, 5-minute cached on
 reads), and keeps the a2loft OTP requirement only on the save step.
 
-Its service credentials are the sole environment variables this app uses
-(same names the old `id-image-bot` used — an existing `.env` is drop-in):
+Its service credentials are the sole environment variables this app uses.
+They live in dotenvx-encrypted files at the repository root — `.env` for
+development, `.env.production` for deployment:
 
 ```sh
 MINIO_ACCESS_KEY=…            MINIO_SECRET_KEY=…
@@ -83,8 +84,18 @@ CARVEKIT_API_KEY=…
 ```
 
 Without them the rest of the app works and `/cropper` routes answer `503`.
-Run locally with `cp tools/.env.example tools/.env` + your values and
-`node --env-file=tools/.env tools/server.js` (or `docker run --env-file …`).
+The private decryption keys sit in `.env.keys` (gitignored, never commit it).
+
+```sh
+dotenvx run -f .env -- node tools/server.js          # local, from the repo root
+dotenvx set MINIO_SECRET_KEY "<value>" -f .env       # add/rotate a value
+```
+
+Deploying with Docker: `--env-file` cannot read encrypted values, so either
+decrypt at deploy time (`dotenvx decrypt -f .env.production --stdout` into a
+runtime env file) or pass `DOTENV_PRIVATE_KEY_PRODUCTION` into the container
+and run through `dotenvx` inside the image (ask if you want the Dockerfile
+wired for that).
 
 ## Tests