From 20f24a73ccba22d6fef34c622b61993e582d9f36 Mon Sep 17 00:00:00 2001
From: Chris Lu <chris.lu@gmail.com>
Date: Tue, 10 Mar 2026 22:24:20 -0700
Subject: [PATCH] Using Environment Variables for Secrets

---
 Security-Configuration.md | 87 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/Security-Configuration.md b/Security-Configuration.md
index f91f644..d71a729 100644
--- a/Security-Configuration.md
+++ b/Security-Configuration.md
@@ -159,6 +159,93 @@ ca = ""
 white_list = ""
 ```
 
+## Using Environment Variables for Secrets
+
+All `security.toml` values can be overridden via environment variables, which avoids storing secrets in plaintext config files. This is especially useful for:
+
+- **NixOS** and other declarative systems where config files are stored in Git
+- **Docker / Kubernetes** deployments using secret management
+- **CI/CD** pipelines where secrets come from a vault
+
+The convention is: prefix with `WEED_`, uppercase the key path, and replace `.` with `_`.
+
+### JWT Signing Keys
+
+Instead of putting JWT keys in `security.toml`:
+```shell
+# Volume server JWT (write)
+export WEED_JWT_SIGNING_KEY="your-secret-key"
+
+# Volume server JWT (read)
+export WEED_JWT_SIGNING_READ_KEY="your-read-secret-key"
+
+# Filer JWT (write)
+export WEED_JWT_FILER_SIGNING_KEY="your-filer-secret-key"
+
+# Filer JWT (read)
+export WEED_JWT_FILER_SIGNING_READ_KEY="your-filer-read-secret-key"
+```
+
+### TLS Certificate Paths
+
+```shell
+# gRPC CA certificate
+export WEED_GRPC_CA="/path/to/ca.crt"
+
+# gRPC volume server certificates
+export WEED_GRPC_VOLUME_CERT="/path/to/volume.crt"
+export WEED_GRPC_VOLUME_KEY="/path/to/volume.key"
+
+# gRPC master server certificates
+export WEED_GRPC_MASTER_CERT="/path/to/master.crt"
+export WEED_GRPC_MASTER_KEY="/path/to/master.key"
+
+# gRPC filer server certificates
+export WEED_GRPC_FILER_CERT="/path/to/filer.crt"
+export WEED_GRPC_FILER_KEY="/path/to/filer.key"
+
+# gRPC client certificates
+export WEED_GRPC_CLIENT_CERT="/path/to/client.crt"
+export WEED_GRPC_CLIENT_KEY="/path/to/client.key"
+```
+
+### Docker Compose Example
+
+```yaml
+services:
+  master:
+    image: chrislusf/seaweedfs:latest
+    environment:
+      WEED_JWT_SIGNING_KEY: "${JWT_SECRET}"
+      WEED_JWT_FILER_SIGNING_KEY: "${JWT_FILER_SECRET}"
+      WEED_GRPC_CA: /run/secrets/ca.crt
+      WEED_GRPC_MASTER_CERT: /run/secrets/master.crt
+      WEED_GRPC_MASTER_KEY: /run/secrets/master.key
+    secrets:
+      - ca.crt
+      - master.crt
+      - master.key
+    command: master
+```
+
+### Mixing Config File and Environment Variables
+
+You can keep non-sensitive settings in `security.toml` and override only the secrets via environment variables. Environment variables take precedence over values in the config file.
+
+```toml
+# security.toml — no secrets here, safe to commit to Git
+[jwt.signing]
+key = ""                         # overridden by WEED_JWT_SIGNING_KEY
+expires_after_seconds = 10
+
+[grpc]
+ca = "/etc/seaweedfs/certs/ca.crt"
+```
+
+For the full list of environment variable conventions, see [[Environment Variables]].
+
+---
+
 The following command is what I used to generate the private key and certificate files, using https://github.com/square/certstrap. To compile this tool, you can run `go get github.com/square/certstrap` - or alternatively `brew install certstrap` if you are on Mac OS and use [Homebrew](https://brew.sh).
 
 ```