Skip to content

ADR-001: Secrets _FILE Migration Strategy

Status

Accepted

Context

Docker secrets provide a more secure way to pass sensitive data to containers by mounting files at /run/secrets/ instead of exposing values as environment variables (visible in docker inspect, process lists, and logs).

Many Docker images support a _FILE suffix convention (e.g., POSTGRES_PASSWORD_FILE) that reads the secret from a file path. However, not all images support this pattern — some only accept plaintext environment variables.

We needed a strategy for migrating secrets across ~20 service stacks with varying levels of _FILE support.

Decision

Migrate to Docker secrets (_FILE pattern) only where the container image natively supports it. Services without native _FILE support keep plaintext environment variables.

We do NOT: - Write custom entrypoint wrapper scripts to add _FILE support - Fork or patch upstream images - Use Docker Compose environment interpolation hacks

Consequences

  • ✅ No maintenance burden from custom entrypoints that break on image upgrades
  • ✅ Clear, predictable behavior — each service uses its documented configuration method
  • ✅ Migration is incremental — services can be migrated as upstream images add _FILE support
  • ⚠️ Some secrets remain as plaintext env vars (Keycloak KC_DB_PASSWORD, matrix-alertmanager tokens, Paperless OIDC secret embedded in JSON, Friendica exporter token) — visible via docker inspect on the host (requires root access, acceptable risk for self-hosted)
  • 🔗 See: architecture.md for the full migration status table