Docker Secrets Management Without Hardcoding Credentials
Inject secrets into containers using Docker secrets, env files, and external secret managers without hardcoding them in images.
Overview
Hardcoding secrets (passwords, API keys, tokens) in Docker images or Compose files is a critical security risk. Images get shared, cached, and inspected — anyone who can pull the image can pull the secrets out of it. What follows is how to get secrets into containers at runtime, without ever writing them into the image.
When to Use
- You need to pass database passwords, API keys, or TLS certificates to containers
- You want to avoid committing secrets to version control
- You use Docker Swarm or Compose in production
- You need to rotate secrets without rebuilding images
Solution
Docker Swarm secrets (most secure)
# Create a secret from a file
echo "my-super-secret-password" | docker secret create db_password -
# Create a secret from stdin
printf "AKIAIOSFODNN7EXAMPLE" | docker secret create aws_access_key -
# List secrets
docker secret ls
# Use in a Swarm service
docker service create \
--name api \
--secret db_password \
--secret aws_access_key \
-e DB_PASSWORD_FILE=/run/secrets/db_password \
-e AWS_KEY_FILE=/run/secrets/aws_access_key \
my-api:latest
Docker mounts secrets as files at /run/secrets/<secret_name>. They’re never exposed as environment variables and are encrypted in transit.
Reading secrets from files in your app
import os
def get_secret(name: str) -> str:
"""Read a secret from a file (Docker Swarm pattern)."""
file_path = os.environ.get(f"{name}_FILE")
if file_path:
with open(file_path, "r") as f:
return f.read().strip()
# Fallback to env var for local dev
return os.environ.get(name, "")
const fs = require("fs");
function getSecret(name) {
const filePath = process.env[`${name}_FILE`];
if (filePath) {
return fs.readFileSync(filePath, "utf8").trim();
}
return process.env[name] || "";
}
Docker Compose with secrets
# docker-compose.yml
services:
api:
build: .
secrets:
- db_password
- api_key
environment:
- DB_PASSWORD_FILE=/run/secrets/db_password
- API_KEY_FILE=/run/secrets/api_key
db:
image: postgres:16-alpine
environment:
POSTGRES_PASSWORD_FILE: /run/secrets/db_password
secrets:
- db_password
secrets:
db_password:
file: ./secrets/db_password.txt
api_key:
file: ./secrets/api_key.txt
.env file (development only)
# .env (NEVER commit this — add to .gitignore)
DB_PASSWORD=my-dev-password
API_KEY=dev-api-key-12345
JWT_SECRET=dev-jwt-secret
# docker-compose.dev.yml
services:
api:
build: .
env_file:
- .env
environment:
- NODE_ENV=development
# .gitignore
.env
.env.*
secrets/
External secret manager (HashiCorp Vault)
The Vault service here runs in dev mode — fine for local testing, useless for production. wait-for-vault.sh is just a retry loop until Vault answers; it’s included in the companion repo.
# docker-compose.yml
services:
api:
build: .
environment:
- VAULT_ADDR=https://vault.internal:8200
- VAULT_TOKEN_FILE=/run/secrets/vault_token
secrets:
- vault_token
command: ["./wait-for-vault.sh", "node", "server.js"]
vault:
image: hashicorp/vault:1.15
ports:
- "8200:8200"
environment:
VAULT_DEV_ROOT_TOKEN_ID: root # dev mode only — never ship this
cap_add:
- IPC_LOCK
secrets:
vault_token:
file: ./secrets/vault_token.txt
import os
import hvac
def get_vault_secret(path: str) -> dict:
"""Fetch a secret from HashiCorp Vault."""
client = hvac.Client(
url=os.environ["VAULT_ADDR"],
token=get_secret("VAULT_TOKEN")
)
result = client.secrets.kv.v2.read_secret_version(path=path)
return result["data"]["data"]
Build-time secrets with BuildKit
# Dockerfile
# syntax=docker/dockerfile:1.6
FROM node:20-alpine
# Mount secret during build only — not stored in image layers
RUN --mount=type=secret,id=npm_token \
npm config set //registry.npmjs.org/:_authToken=$(cat /run/secrets/npm_token) && \
npm ci --omit=dev && \
npm config delete //registry.npmjs.org/:_authToken
# Build with BuildKit secret
docker build --secret id=npm_token,source=$HOME/.npmrc -t my-api .
Runtime secrets with environment variables (less secure)
# docker-compose.prod.yml
services:
api:
build: .
environment:
- DB_PASSWORD=${DB_PASSWORD} # From --env-file or shell
# --env-file keeps secrets out of shell history and Compose files,
# but they still land in the container's env — visible via docker inspect
docker compose --env-file .env.prod up -d
Explanation
Swarm secrets sit at the top of that ranking: encrypted at rest and in transit, mounted as read-only files under /run/secrets/, and invisible to docker inspect. BuildKit mounts are just as safe but scoped to the build: the file exists only while the RUN instruction executes, so nothing leaks into image layers. External managers like Vault or AWS Secrets Manager go further — they add rotation, audit logs, and access policies — at the cost of running one more service.
At the risky end, .env files keep secrets in plaintext on disk, which is fine for development and nothing else. Plain environment variables are the weakest option: they’re visible in docker inspect, docker exec env, and /proc/<pid>/environ on the host, and they tend to leak into logs and crash dumps.
Two principles tie all of this together:
- Never bake secrets into image layers —
ENVandARGvalues survive indocker history. - With the
_FILEsuffix convention the app reads the secret from a file path rather than from the variable’s own value — that’s the whole trick behind Swarm and Compose file secrets. - Rotate secrets by updating them in the manager, not by rebuilding images.
Variants
| Method | Security | Complexity | Use When |
|---|---|---|---|
| Swarm secrets | High | Low | Docker Swarm production |
| BuildKit mount | High | Medium | Private registries during build |
| Vault / Secrets Manager | High | High | Enterprise, rotation needed |
| .env file | Low | Low | Development only |
| Environment variables | Low | Low | Non-sensitive config |
External Secret Managers
Swarm secrets cover the Docker-native case. If you need centralized rotation, audit trails, or secrets that live beyond a single host, an external manager earns its keep.
AWS Secrets Manager
import boto3
import json
def get_aws_secret(secret_name: str, region: str = "us-east-1") -> dict:
"""Fetch a secret from AWS Secrets Manager."""
client = boto3.client("secretsmanager", region_name=region)
response = client.get_secret_value(SecretId=secret_name)
return json.loads(response["SecretString"])
# Usage
db_creds = get_aws_secret("prod/db/credentials")
db_password = db_creds["password"]
# docker-compose.yml with AWS Secrets Manager
services:
api:
build: .
environment:
- AWS_REGION=us-east-1
- AWS_SECRET_NAME=prod/db/credentials
# AWS credentials via IAM role, not env vars
Kubernetes Secrets
If your containers run on Kubernetes instead of Swarm, the equivalent primitive is the Secret object — mounted as a read-only volume or exposed via secretKeyRef. See Mount Configs and Secrets into Kubernetes Pods for the full walkthrough.
# k8s-secret.yaml
apiVersion: v1
kind: Secret
metadata:
name: db-credentials
type: Opaque
stringData:
password: my-super-secret-password
username: dbadmin
# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
spec:
template:
spec:
containers:
- name: api
image: my-api:latest
env:
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: db-credentials
key: password
# Or mount as file
volumeMounts:
- name: secrets
mountPath: /run/secrets
readOnly: true
volumes:
- name: secrets
secret:
secretName: db-credentials
Rotating Secrets in Swarm
Secrets in Swarm are immutable — rotating one means creating a new secret and re-pointing the service. This script automates the swap:
#!/bin/bash
# rotate-secrets.sh
set -e
SECRET_NAME="db_password"
NEW_VALUE=$(openssl rand -base64 32)
# Create the new secret
echo "$NEW_VALUE" | docker secret create "${SECRET_NAME}_v2" -
# Re-point the service: drop the old mount, mount the new secret under the same name
docker service update \
--secret-rm "$SECRET_NAME" \
--secret-add "source=${SECRET_NAME}_v2,target=${SECRET_NAME}" \
api
# Wait for rollout
sleep 30
# Remove old secret
docker secret rm "$SECRET_NAME"
echo "Rotation complete for $SECRET_NAME"
Guidelines
- Keep secrets out of Dockerfiles (
ENV,ARG) and Compose files — those values end up in image history. - On Swarm, reach for
docker secret; for builds, use BuildKit’s--mount=type=secret. - Follow the
_FILEconvention so your app reads secrets from files, not env vars. - Gitignore
.envandsecrets/before they ever reach a commit. - For anything enterprise-grade — rotation, audit trails, secrets shared across platforms — use Vault or AWS Secrets Manager.
- Give each service only the secrets it actually needs.
docker secret lsand Vault’s audit log exist for a reason: review who has access.
Common Mistakes
ENVorARGfor secrets. They’re baked intodocker historyand into every copy of the image.- Committing
.envto Git. Once it’s in the history, changing the password isn’t enough — the file keeps leaking it. - Secrets as CLI arguments. They show up in
docker inspectand in the host’s process list. - Apps that only read env vars. Without the
_FILEconvention you can’t use file-mounted secrets at all. - One secret for every service. Least privilege applies to secrets too.
- Never rotating. A leaked secret should be replaceable in minutes, without downtime.
- Same secrets in dev and prod. Different environments need different secrets — a dev leak shouldn’t open production.
Performance Tips
- Cache secret lookups in memory. Avoid fetching the same secret on every request:
import time
_secret_cache = {}
def get_cached_secret(name: str, ttl: int = 300) -> str:
if name in _secret_cache:
cached_time, value = _secret_cache[name]
if time.time() - cached_time < ttl:
return value
value = get_secret(name)
_secret_cache[name] = (time.time(), value)
return value
- Use sidecar pattern for secret fetching. A sidecar container fetches secrets and writes them to a shared volume:
services:
secret-fetcher:
image: vault-sidecar:latest
volumes:
- secrets:/run/secrets
api:
image: my-api:latest
volumes:
- secrets:/run/secrets:ro
volumes:
secrets:
- Batch secret fetches from Vault. Reduce API calls by fetching all the paths you need in one pass at startup:
def get_multiple_secrets(paths: list[str]) -> dict:
results = {}
for path in paths:
results[path] = get_vault_secret(path)
return results
Further Reading
- Manage sensitive data with Docker secrets — official Swarm secrets docs.
- Build secrets with BuildKit —
--mount=type=secretreference. - Secrets top-level element in Compose — file-based secrets without Swarm.
- HashiCorp Vault documentation — external secret management with rotation and audit.
- Kubernetes Secrets — Secret objects, volumes, and env injection.
- Companion repo — the Compose, BuildKit, Vault, and rotation examples from this page as runnable files.
Frequently Asked Questions
Are Docker Compose secrets as secure as Swarm secrets?
No. Compose mounts secret files straight from the host filesystem and doesn't encrypt them at rest — Swarm secrets, by contrast, are encrypted and managed by the Swarm manager. Fine for development; for production, use Swarm.
Can I use Docker secrets without Swarm?
Yes — Docker Compose supports secrets via the secrets key with a file: source, which mounts the file straight into the container. It's less secure than Swarm secrets, but it still beats environment variables.
How do I rotate secrets without downtime?
In Swarm, create a new secret and re-point the service at it: docker service update --secret-rm db_password --secret-add source=db_password_v2,target=db_password api. The service comes back up already mounting the new secret. For zero-downtime, use rolling updates.
Why should I avoid environment variables for secrets?
Because they show up everywhere: docker inspect, docker exec env, even /proc/<pid>/environ on the host — and from there they leak into logs and crash dumps. Only the container's own process can read what gets mounted there.
Related Resources
Docker Network Isolation and Inter-Container Security
Secure inter-container communication with custom Docker networks, network segmentation, and access control policies.
RecipeContainer Security: Scan, Harden, and Sign Docker Images
Scan container images for CVEs and secrets with Trivy and Grype. Harden Dockerfiles, generate SBOMs, sign with Cosign, and gate deployments.
RecipeOverride Docker Compose Configs per Environment
How to use Docker Compose override files for environment-specific configurations, covering dev, test, staging, production, profiles, and secrets.
RecipeManage Application Secrets Securely
How to store, rotate, and inject API keys, database passwords, and certificates without hardcoding them in source code or environment files.
RecipeMount Configs and Secrets into Kubernetes Pods
How to mount ConfigMaps and Secrets into Kubernetes pods using env vars, volumes, projected volumes, and external secret managers.
DocSecrets Rotation Template
A template for scheduling and tracking the rotation of API keys, tokens, and certificates.