Take the master key from KEEPORG_MASTER_KEY_FILE

Why: the usual way to hand a secret to a container is to mount it as a file
and name the path in the environment. Compose, swarm and Kubernetes all do
it that way, and it keeps the key out of the process environment and off any
disk the container can write.

What: the master key is now looked for in KEEPORG_MASTER_KEY, then
KEEPORG_MASTER_KEY_FILE, then the configured master_key_file. A secret file
may hold base64, with or without padding or a trailing newline, or exactly
32 raw bytes, because secret stores produce both.

Only the configured path is ever created, which is what keeps a plain
package install working with no setup. The two environment variables name a
key something else owns, so a missing one is reported and vault creation
refused. Minting a replacement there would be worse than failing: it opens
none of the existing vaults, and the mistake would otherwise surface one
failed merge at a time.

The compose example now provisions the key as a real secret rather than an
environment variable, and the Dockerfile and README show the same. Neither
names a version any more, so they stop drifting as the server is bumped.

Proved: unit tests for every source and precedence, all four accepted
encodings, and that a missing secret writes nothing anywhere. In real
containers: a podman secret carrying base64 survives a stop and start with
"1 vault keys available for merging" and merges a stale push afterwards; a
secret holding 32 raw bytes creates a vault; and a secret that failed to
mount is named in the startup log, with vault creation answering with the
three places a key may come from.

packaging/deb/server/changelog

@@ -1,3 +1,16 @@
+keeporgd (0.4.0) unstable; urgency=medium
+
+  * Read the master key from the file named by KEEPORG_MASTER_KEY_FILE, the
+    convention compose, swarm and Kubernetes use for a provisioned secret.
+    The file may hold base64 or exactly 32 raw bytes.
+  * Neither master-key environment variable is ever created by the server:
+    a secret that failed to mount is reported at startup and vault creation
+    is refused, rather than replaced with a new key that would open none of
+    the existing vaults. Only the configured master_key_file is created on
+    first run.
+
+ -- tiredsysadmin <rcmd@garage.rcmd.space>  Fri, 30 Oct 2026 09:42:50 +0100
+
 keeporgd (0.3.0) unstable; urgency=medium
 
   * Container image: a scratch-based image of about 9 MB holding the static

packaging/docker/compose.yaml

@@ -1,24 +1,27 @@
-# A deployment of the KeepOrg server, showing the two things that are easy
-# to get wrong: where the master key comes from, and that it does not live
-# in the data volume.
+# A deployment of the KeepOrg server, showing the thing that is easiest to
+# get wrong: where the master key comes from, and that it does not live in
+# the data volume.
 #
-#   podman-compose up -d      (or docker compose up -d)
+#   head -c 32 /dev/urandom | base64 > master.key   # once; keep a copy safe
+#   chmod 600 master.key
+#   podman-compose up -d                            # or docker compose up -d
 #
-# Generate the master key once, and keep a copy somewhere safe:
-#   head -c 32 /dev/urandom | base64 > master.key
-#
-# Without it the server still runs and still synchronizes; it only refuses
-# to create or merge vaults.
+# The key is provisioned as a secret and named to the server with
+# KEEPORG_MASTER_KEY_FILE, so it is never in the process environment and
+# never on a disk the container can write. Without a key the server still
+# runs and still synchronizes; it only refuses to create or merge vaults.
 
 services:
   keeporgd:
-    # Override with KEEPORG_VERSION; `make docker` tags the version from
-    # versions.mk and :latest.
-    image: keeporgd:${KEEPORG_VERSION:-0.3.0}
+    # `make docker` tags both the version from versions.mk and :latest.
+    # Pin with KEEPORG_VERSION in production.
+    image: keeporgd:${KEEPORG_VERSION:-latest}
     build:
       context: ../..
       args:
-        VERSION: "${KEEPORG_VERSION:-0.3.0}"
+        # Only used when compose builds the image itself; `make docker`
+        # stamps the real version.
+        VERSION: "${KEEPORG_VERSION:-dev}"
     restart: unless-stopped
     # Terminate TLS in front of this, and set external_url to the address a
     # browser sees: invite links, device approval and the OIDC redirect are
@@ -29,23 +32,27 @@ services:
       - "-url=https://keeporg.example.com"
     ports:
       - "127.0.0.1:8765:8765"
+    secrets:
+      - keeporg_master_key
     environment:
-      # Preferred: the key never touches a disk the container can write.
-      # Read it from your secret store and pass it in.
-      KEEPORG_MASTER_KEY: "${KEEPORG_MASTER_KEY:?set KEEPORG_MASTER_KEY, see the comment above}"
+      KEEPORG_MASTER_KEY_FILE: /run/secrets/keeporg_master_key
+      # The alternative, when the key comes from a store that injects
+      # variables rather than files. One or the other, not both.
+      # KEEPORG_MASTER_KEY: "${KEEPORG_MASTER_KEY:-}"
+      #
       # Only read on the very first start, when no accounts exist yet.
       KEEPORG_ADMIN_PASSWORD: "${KEEPORG_ADMIN_PASSWORD:-}"
     volumes:
       - keeporg-data:/var/lib/keeporg
-      # Only needed instead of KEEPORG_MASTER_KEY above, or to mount a
-      # server.json. Keep it on different storage from keeporg-data.
-      # - keeporg-config:/etc/keeporg
     # The server writes one directory and needs no privileges at all.
     read_only: true
     cap_drop: ["ALL"]
     security_opt: ["no-new-privileges:true"]
     user: "65532:65532"
 
+secrets:
+  keeporg_master_key:
+    file: ./master.key
+
 volumes:
   keeporg-data:
-  # keeporg-config: