diff --git a/docs/gateway.md b/docs/gateway.md
index fb1fd503..a582ca7c 100644
--- a/docs/gateway.md
+++ b/docs/gateway.md
@@ -197,6 +197,14 @@ The directory is bind-mounted read-only into the gateway container at `/run/hive
 
 `selfSignedTls = true` and `tls.certDir` set together is an assertion error.
 
+**Key file permissions**: nixpkgs's `security.acme` outputs private keys as `0640 root:acme` by default. nginx inside the gateway container runs as the `nginx` user and cannot read a key with that ownership. Fix with:
+
+```nix
+security.acme.certs."example.com".group = "nginx";
+```
+
+or make the key world-readable (`0644`) if your threat model allows it. nginx errors out at startup on a key it can't read — the error is explicit in the journal, not a silent failure.
+
 **Peer hive config**: when using a CA-signed cert, peer hives can declare this hive without `certFingerprint` in `swarm.peers` — the standard CA bundle validates:
 
 ```nix