From 81f428af5137da63253d73d4b7f91f5cfe5726b6 Mon Sep 17 00:00:00 2001
From: givemethatsewon <nvpz1598@gmail.com>
Date: Fri, 5 Jun 2026 23:53:04 +0900
Subject: [PATCH] docs: mention file placeholder for secrets

---
 src/docs/markdown/caddyfile/concepts.md | 12 ++++++++++++
 src/docs/markdown/conventions.md        |  2 +-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/src/docs/markdown/caddyfile/concepts.md b/src/docs/markdown/caddyfile/concepts.md
index 958a5da2..30f60ea2 100644
--- a/src/docs/markdown/caddyfile/concepts.md
+++ b/src/docs/markdown/caddyfile/concepts.md
@@ -821,4 +821,16 @@ For example, if you have the [`caddy-dns/cloudflare` plugin <img src="/old/resou
 }
 ```
 
+Environment variables are convenient, but sensitive values in a process environment can be exposed by process inspection, child process inheritance, logs, crash dumps, or platform diagnostics.
+
+For secrets, prefer your platform's secret management mechanism when available. If the secret is provided as a file, you can use the [global `{file.*}` placeholder](/docs/conventions#placeholders) in config fields which support placeholders:
+
+```caddy
+{
+	acme_dns cloudflare {file./run/secrets/cloudflare_api_token}
+}
+```
+
+This does not make the secret inaccessible to Caddy; the Caddy process still needs permission to read the file. It avoids placing the secret value in the process-wide environment.
+
 If you're running Caddy as a systemd service, see [these instructions](/docs/running#overrides) for setting service overrides to define your environment variables.
diff --git a/src/docs/markdown/conventions.md b/src/docs/markdown/conventions.md
index 29d83e76..9b62335c 100644
--- a/src/docs/markdown/conventions.md
+++ b/src/docs/markdown/conventions.md
@@ -97,7 +97,7 @@ The following placeholders are always available (global):
 Placeholder | Description
 ------------|-------------
 `{env.*}` | Environment variable; example: `{env.HOME}`
-`{file.*}` | Contents from a file; example: `{file./path/to/secret.txt}`
+`{file.*}` | Contents from a file, useful when a secret is supplied as a file; example: `{file./path/to/secret.txt}`
 `{system.hostname}` | The system's local hostname
 `{system.slash}` | The system's filepath separator
 `{system.os}` | The system's OS