feat: add Docker _FILE secret convention for sensitive env vars (#205)

Support reading secrets from mounted files instead of plain-text
environment variables, following the standard Docker/Kubernetes
convention used by MariaDB, Postgres, and Stirling-PDF.

Supported vars: DEFAULT_PASSWORD, S3_ACCESS_KEY_ID,
S3_SECRET_ACCESS_KEY, OIDC_CLIENT_SECRET, COOKIE_SECRET,
SNAPOTTER_LICENSE_KEY.

docker/docker-compose-gpu.yml

@@ -51,6 +51,15 @@ services:
       # - OIDC_USERNAME_CLAIM=preferred_username
       # - OIDC_CLOCK_TOLERANCE=30
       # - COOKIE_SECRET=
+      #
+      # Docker secrets (_FILE convention): mount secrets as files instead of
+      # passing them as plain-text env vars. Supported for sensitive vars only.
+      # - DEFAULT_PASSWORD_FILE=/run/secrets/snapotter_password
+      # - S3_ACCESS_KEY_ID_FILE=/run/secrets/s3_access_key
+      # - S3_SECRET_ACCESS_KEY_FILE=/run/secrets/s3_secret_key
+      # - OIDC_CLIENT_SECRET_FILE=/run/secrets/oidc_secret
+      # - COOKIE_SECRET_FILE=/run/secrets/cookie_secret
+      # - SNAPOTTER_LICENSE_KEY_FILE=/run/secrets/license_key
     restart: unless-stopped
     # --- Security hardening ---
     mem_limit: 8g
@@ -91,6 +100,13 @@ services:
         max-size: "50m"
         max-file: "5"
 
+# Uncomment to use Docker secrets (requires Docker Swarm or compose v2.23+):
+# secrets:
+#   snapotter_password:
+#     file: ./secrets/snapotter_password.txt
+#   oidc_secret:
+#     file: ./secrets/oidc_secret.txt
+
 volumes:
   SnapOtter-data:
   SnapOtter-workspace:

docker/docker-compose.yml

@@ -50,6 +50,15 @@ services:
       # - OIDC_USERNAME_CLAIM=preferred_username
       # - OIDC_CLOCK_TOLERANCE=30
       # - COOKIE_SECRET=
+      #
+      # Docker secrets (_FILE convention): mount secrets as files instead of
+      # passing them as plain-text env vars. Supported for sensitive vars only.
+      # - DEFAULT_PASSWORD_FILE=/run/secrets/snapotter_password
+      # - S3_ACCESS_KEY_ID_FILE=/run/secrets/s3_access_key
+      # - S3_SECRET_ACCESS_KEY_FILE=/run/secrets/s3_secret_key
+      # - OIDC_CLIENT_SECRET_FILE=/run/secrets/oidc_secret
+      # - COOKIE_SECRET_FILE=/run/secrets/cookie_secret
+      # - SNAPOTTER_LICENSE_KEY_FILE=/run/secrets/license_key
     restart: unless-stopped
     # --- Security hardening ---
     mem_limit: 6g
@@ -83,6 +92,13 @@ services:
         max-size: "50m"
         max-file: "5"
 
+# Uncomment to use Docker secrets (requires Docker Swarm or compose v2.23+):
+# secrets:
+#   snapotter_password:
+#     file: ./secrets/snapotter_password.txt
+#   oidc_secret:
+#     file: ./secrets/oidc_secret.txt
+
 volumes:
   SnapOtter-data:
   SnapOtter-workspace:

docker/entrypoint.sh

@@ -1,6 +1,44 @@
 #!/bin/sh
 set -e
 
+# --- Docker secret file convention (_FILE suffix) ---
+# For each supported var, if VAR_FILE is set, read the secret from that file
+# path into VAR. This lets users mount Docker/Kubernetes secrets instead of
+# passing credentials as plain-text environment variables.
+#
+# Supported: DEFAULT_PASSWORD, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY,
+#            OIDC_CLIENT_SECRET, COOKIE_SECRET, SNAPOTTER_LICENSE_KEY
+resolve_file_env() {
+  var="$1"
+  file_var="${var}_FILE"
+  eval current_val="\"\${${var}:-}\""
+  eval file_path="\"\${${file_var}:-}\""
+
+  if [ -z "$file_path" ]; then
+    return
+  fi
+
+  if [ -n "$current_val" ]; then
+    echo "WARNING: Both $var and $file_var are set. $file_var takes precedence." >&2
+  fi
+
+  if [ ! -f "$file_path" ] || [ ! -r "$file_path" ]; then
+    echo "ERROR: $file_var points to '$file_path' but the file does not exist or is not readable." >&2
+    exit 1
+  fi
+
+  # Command substitution strips trailing newlines (standard for secret files)
+  export "$var"="$(cat "$file_path")"
+  unset "$file_var"
+}
+
+resolve_file_env DEFAULT_PASSWORD
+resolve_file_env S3_ACCESS_KEY_ID
+resolve_file_env S3_SECRET_ACCESS_KEY
+resolve_file_env OIDC_CLIENT_SECRET
+resolve_file_env COOKIE_SECRET
+resolve_file_env SNAPOTTER_LICENSE_KEY
+
 # Apply auth defaults at runtime so they are never baked into image layers.
 # Users can override any of these via -e flags at docker run time.
 export AUTH_ENABLED="${AUTH_ENABLED:-true}"

tests/unit/docker-file-secrets.test.ts

@@ -0,0 +1,141 @@
+import { execFileSync } from "node:child_process";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+const SUPPORTED_VARS = [
+  "DEFAULT_PASSWORD",
+  "S3_ACCESS_KEY_ID",
+  "S3_SECRET_ACCESS_KEY",
+  "OIDC_CLIENT_SECRET",
+  "COOKIE_SECRET",
+  "SNAPOTTER_LICENSE_KEY",
+];
+
+const RESOLVE_SCRIPT = `
+resolve_file_env() {
+  var="$1"
+  file_var="\${var}_FILE"
+  eval current_val="\\"\\\${$var:-}\\""
+  eval file_path="\\"\\\${$file_var:-}\\""
+  if [ -z "$file_path" ]; then return; fi
+  if [ -n "$current_val" ]; then
+    echo "WARNING: Both $var and $file_var are set. $file_var takes precedence." >&2
+  fi
+  if [ ! -f "$file_path" ] || [ ! -r "$file_path" ]; then
+    echo "ERROR: $file_var points to '$file_path' but the file does not exist or is not readable." >&2
+    exit 1
+  fi
+  export "$var"="$(cat "$file_path")"
+  unset "$file_var"
+}
+${SUPPORTED_VARS.map((v) => `resolve_file_env ${v}`).join("\n")}
+${SUPPORTED_VARS.map((v) => `echo "${v}=\${${v}:-}"`).join("\n")}
+${SUPPORTED_VARS.map((v) => `echo "${v}_FILE=\${${v}_FILE:-}"`).join("\n")}
+`;
+
+let secretsDir: string;
+
+beforeAll(() => {
+  secretsDir = mkdtempSync(join(tmpdir(), "snapotter-secrets-"));
+});
+
+afterAll(() => {
+  rmSync(secretsDir, { recursive: true, force: true });
+});
+
+function writeSecret(name: string, content: string): string {
+  const path = join(secretsDir, name);
+  writeFileSync(path, content);
+  return path;
+}
+
+function runResolve(env: Record<string, string>): Record<string, string> {
+  const result = execFileSync("/bin/sh", ["-c", RESOLVE_SCRIPT], {
+    env: { ...env, PATH: process.env.PATH },
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  const parsed: Record<string, string> = {};
+  for (const line of result.trim().split("\n")) {
+    const eqIdx = line.indexOf("=");
+    if (eqIdx > 0) {
+      parsed[line.slice(0, eqIdx)] = line.slice(eqIdx + 1);
+    }
+  }
+  return parsed;
+}
+
+describe("Docker _FILE secret convention", () => {
+  it("reads secret from file into env var", () => {
+    const secretPath = writeSecret("password.txt", "super-secret-pw");
+    const result = runResolve({ DEFAULT_PASSWORD_FILE: secretPath });
+    expect(result.DEFAULT_PASSWORD).toBe("super-secret-pw");
+    expect(result.DEFAULT_PASSWORD_FILE).toBe("");
+  });
+
+  it("strips trailing newline from secret file", () => {
+    const secretPath = writeSecret("password-newline.txt", "my-secret\n");
+    const result = runResolve({ DEFAULT_PASSWORD_FILE: secretPath });
+    expect(result.DEFAULT_PASSWORD).toBe("my-secret");
+  });
+
+  it("preserves internal whitespace in secret", () => {
+    const secretPath = writeSecret("spaced.txt", "pass word with spaces\n");
+    const result = runResolve({ COOKIE_SECRET_FILE: secretPath });
+    expect(result.COOKIE_SECRET).toBe("pass word with spaces");
+  });
+
+  it("_FILE takes precedence when both are set", () => {
+    const secretPath = writeSecret("override.txt", "from-file");
+    const result = runResolve({
+      OIDC_CLIENT_SECRET: "from-env",
+      OIDC_CLIENT_SECRET_FILE: secretPath,
+    });
+    expect(result.OIDC_CLIENT_SECRET).toBe("from-file");
+    expect(result.OIDC_CLIENT_SECRET_FILE).toBe("");
+  });
+
+  it("leaves var unchanged when _FILE is not set", () => {
+    const result = runResolve({ S3_ACCESS_KEY_ID: "direct-value" });
+    expect(result.S3_ACCESS_KEY_ID).toBe("direct-value");
+  });
+
+  it("leaves var empty when neither is set", () => {
+    const result = runResolve({});
+    expect(result.DEFAULT_PASSWORD).toBe("");
+    expect(result.DEFAULT_PASSWORD_FILE).toBe("");
+  });
+
+  it("errors when _FILE points to nonexistent file", () => {
+    expect(() =>
+      runResolve({
+        S3_SECRET_ACCESS_KEY_FILE: "/nonexistent/secret.txt",
+      }),
+    ).toThrow();
+  });
+
+  it("errors when _FILE points to unreadable file", () => {
+    const secretPath = writeSecret("unreadable.txt", "secret");
+    chmodSync(secretPath, 0o000);
+    try {
+      expect(() => runResolve({ SNAPOTTER_LICENSE_KEY_FILE: secretPath })).toThrow();
+    } finally {
+      chmodSync(secretPath, 0o644);
+    }
+  });
+
+  it("works for all supported vars simultaneously", () => {
+    const env: Record<string, string> = {};
+    for (const v of SUPPORTED_VARS) {
+      env[`${v}_FILE`] = writeSecret(`${v.toLowerCase()}.txt`, `secret-for-${v}`);
+    }
+    const result = runResolve(env);
+    for (const v of SUPPORTED_VARS) {
+      expect(result[v]).toBe(`secret-for-${v}`);
+      expect(result[`${v}_FILE`]).toBe("");
+    }
+  });
+});