← Back to DevBytes
Docker July 07, 2026 14 min read

Docker Secrets Management: Best Practices and Common Pitfalls

Understanding Docker Secrets Management

Docker secrets provide a secure mechanism for injecting sensitive configuration data—such as API keys, database passwords, TLS certificates, and tokens—into running containers without exposing them in image layers, environment variables, or command-line arguments. This feature is native to Docker Swarm mode and has become an essential tool in the container security landscape.

At its core, a Docker secret is an encrypted blob that exists on the Swarm manager nodes, transmitted securely over mutually authenticated TLS connections to only the services that explicitly request access. Once mounted, the secret appears as a plaintext file inside the container at /run/secrets/<secret-name>. This approach fundamentally changes how developers think about secrets: instead of baking credentials into images or passing them through insecure channels, secrets live outside the application and are delivered securely at runtime.

Why Secrets Management Matters

Consider a typical containerized application that connects to a PostgreSQL database. Without secrets management, developers often resort to one of these dangerous patterns:

Each of these patterns creates a significant attack surface. Docker secrets address these vulnerabilities by encrypting secrets at rest on manager nodes, encrypting them in transit over the Swarm control plane, and exposing them only as in-memory filesystem mounts within authorized containers. The secret never touches the container's disk, never appears in environment variables, and is automatically removed when the container stops.

How Docker Secrets Work: Architecture Deep Dive

🚀 Deploy your AI agent in 10 minutes

Managed Hermes hosting. Zero DevOps. 100M tokens/mo included.

Try it free →

Docker secrets operate exclusively within Swarm mode clusters. When you create a secret using the Docker CLI, the following chain of events occurs:

  1. The secret value is encrypted and stored in the Swarm raft log on manager nodes
  2. When a service is scheduled that requires the secret, the manager decrypts it and transmits it over a mutual TLS channel to the worker node
  3. The worker node mounts the secret as a tmpfs (temporary filesystem) at /run/secrets/
  4. The container reads the secret like any other file, but the data never persists to disk
  5. When the container exits, the tmpfs mount is destroyed

Prerequisites and Limitations

Before diving into implementation, understand these critical constraints:

Practical Implementation Guide

Creating Your First Docker Secret

Let's walk through a complete example of securing a Node.js application with Docker secrets. First, initialize a Swarm cluster:

# Initialize swarm mode on your local machine
docker swarm init

# Verify swarm status
docker info | grep Swarm

Now create secrets using both file-based and stdin-based approaches:

# Create a secret from a file (preferred for production)
echo "supersecretdbpassword123!" > db_password.txt
docker secret create db_password db_password.txt

# Create a secret directly from stdin
echo "sk-live-abc123def456ghi789" | docker secret create api_key -

# Create a secret using printf for precise control
printf "my-certificate-content-here" | docker secret create tls_cert -

# Verify secrets exist
docker secret ls

The output of docker secret ls shows only metadata — the actual secret values are never displayed:

ID                          NAME           CREATED             UPDATED
gx7z8k9p2m4n                db_password    2 minutes ago       2 minutes ago
wq5e6r7t8y9u                api_key        1 minute ago        1 minute ago

Mounting Secrets into Services

Now deploy a service that consumes these secrets. Create a docker-compose.yml file for a realistic application:

version: '3.8'

services:
  app:
    image: myapp:latest
    secrets:
      - db_password
      - api_key
    environment:
      - DB_PASSWORD_FILE=/run/secrets/db_password
      - API_KEY_FILE=/run/secrets/api_key
    deploy:
      replicas: 2
      restart_policy:
        condition: on-failure

  database:
    image: postgres:16
    secrets:
      - db_password
    environment:
      - POSTGRES_PASSWORD_FILE=/run/secrets/db_password
    volumes:
      - pgdata:/var/lib/postgresql/data

secrets:
  db_password:
    external: true
  api_key:
    external: true

volumes:
  pgdata:

Deploy the stack:

docker stack deploy -c docker-compose.yml myapp-stack

Inside the container, verify the secret is mounted:

# Exec into a running container in the service
docker exec -it $(docker ps --filter name=myapp-stack_app -q | head -1) sh

# Check the secrets directory
ls -la /run/secrets/
# Output:
# -rw-r--r-- 1 root root 24 db_password
# -rw-r--r-- 1 root root 29 api_key

# Read the secret (this works - the secret is plaintext inside the container)
cat /run/secrets/db_password
# Output: supersecretdbpassword123!

Application Code Integration

Your application must be designed to read secrets from files. Here's a robust Node.js example that handles secrets gracefully:

// config.js - Secrets-aware configuration loader
const fs = require('fs');
const path = require('path');

function loadSecret(secretName, envFallback = null) {
  const secretPath = path.join('/run/secrets', secretName);
  
  try {
    if (fs.existsSync(secretPath)) {
      const value = fs.readFileSync(secretPath, 'utf8').trim();
      console.log(`Loaded secret '${secretName}' from Docker secrets`);
      return value;
    }
  } catch (err) {
    console.warn(`Failed to read secret '${secretName}': ${err.message}`);
  }
  
  // Fallback to environment variable for local development
  if (envFallback && process.env[envFallback]) {
    console.log(`Using environment variable fallback for '${secretName}'`);
    return process.env[envFallback];
  }
  
  throw new Error(`Secret '${secretName}' not available. ` +
                  `Ensure Docker secret exists or set ${envFallback} env var.`);
}

// Database configuration
const dbConfig = {
  host: process.env.DB_HOST || 'database',
  port: process.env.DB_PORT || 5432,
  database: process.env.DB_NAME || 'myapp',
  user: process.env.DB_USER || 'app_user',
  password: loadSecret('db_password', 'DB_PASSWORD_FALLBACK'),
};

// External API configuration
const apiConfig = {
  endpoint: process.env.API_ENDPOINT || 'https://api.example.com',
  key: loadSecret('api_key', 'API_KEY_FALLBACK'),
};

module.exports = { dbConfig, apiConfig };

For Python applications, follow a similar pattern:

# config.py
import os
from pathlib import Path

def load_secret(secret_name: str, env_fallback: str = None) -> str:
    """
    Load a Docker secret from /run/secrets/ with environment variable fallback.
    """
    secret_path = Path('/run/secrets') / secret_name
    
    if secret_path.is_file():
        try:
            value = secret_path.read_text().strip()
            print(f"Loaded secret '{secret_name}' from Docker secrets mount")
            return value
        except OSError as e:
            print(f"Warning: Could not read secret '{secret_name}': {e}")
    
    if env_fallback and env_fallback in os.environ:
        print(f"Using environment variable fallback for '{secret_name}'")
        return os.environ[env_fallback]
    
    raise RuntimeError(
        f"Secret '{secret_name}' not found. "
        f"Ensure Docker secret is mounted or set {env_fallback} environment variable."
    )

# Usage
DATABASE_PASSWORD = load_secret('db_password', 'DB_PASSWORD_FALLBACK')
API_KEY = load_secret('api_key', 'API_KEY_FALLBACK')

Rotating Secrets in Production

Secret rotation is a critical operational task. Since secrets are immutable, rotation requires creating a new secret and updating the service. Here's a production-ready rotation script:

#!/bin/bash
# rotate-db-password.sh - Rotate database password with zero-downtime

set -euo pipefail

SECRET_NAME="db_password"
STACK_NAME="myapp-stack"
NEW_PASSWORD=$(openssl rand -base64 32)

echo "Rotating secret: ${SECRET_NAME}"

# Step 1: Create new secret version with timestamp
NEW_SECRET="${SECRET_NAME}_v$(date +%s)"
echo -n "${NEW_PASSWORD}" | docker secret create "${NEW_SECRET}" -

# Step 2: Update the service to use the new secret
# Important: Keep the old secret mounted during transition
docker service update \
  --secret-rm "${SECRET_NAME}" \
  --secret-add "source=${NEW_SECRET},target=${SECRET_NAME}" \
  "${STACK_NAME}_app"

# Step 3: Wait for service convergence
echo "Waiting for service to converge..."
docker service logs --follow "${STACK_NAME}_app" 2>&1 | head -n 5

# Step 4: Verify new secret is active
CONTAINER_ID=$(docker ps --filter "name=${STACK_NAME}_app" -q | head -1)
ACTUAL_SECRET=$(docker exec "${CONTAINER_ID}" cat /run/secrets/db_password 2>/dev/null || echo "ERROR")

if [ "${ACTUAL_SECRET}" == "${NEW_PASSWORD}" ]; then
    echo "Secret rotation successful!"
    # Step 5: Remove old secret after verification
    docker secret rm "${SECRET_NAME}" || true
    echo "Old secret removed."
else
    echo "CRITICAL: Secret verification failed! Rolling back..."
    docker service update --secret-rm "${SECRET_NAME}" --secret-add "${SECRET_NAME}" "${STACK_NAME}_app"
    exit 1
fi

# Step 6: Rename new secret to standard name (optional cleanup)
# Note: This requires recreating - simplified here
echo "Rotation complete. New secret: ${NEW_SECRET}"

Best Practices for Docker Secrets Management

1. Never Log Secrets or Include Them in Health Checks

A common pitfall is accidentally leaking secrets through application logs or health check commands. Docker health checks run inside the container and their output is visible in docker inspect:

# DANGEROUS: This health check leaks the secret in docker inspect output
healthcheck:
  test: ["CMD-SHELL", "pg_isready -U postgres -d myapp && echo 'Password is: $(cat /run/secrets/db_password)'"]
  interval: 30s

# SAFE: Health check that never references secrets
healthcheck:
  test: ["CMD-SHELL", "pg_isready -U postgres -d myapp || exit 1"]
  interval: 30s

Similarly, ensure your application logging framework never captures secret file contents:

// Dangerous logging pattern
console.log(`Connecting with password: ${dbConfig.password}`);  // NO!

// Safe pattern - log intent, never values
console.log(`Connecting to database ${dbConfig.host} as user ${dbConfig.user}`);
console.log('Using password from Docker secret (value hidden)');

2. Use Distinct Secrets Per Environment

Never share secrets between staging and production. Create environment-specific secrets and reference them appropriately:

# Production secrets
docker secret create prod_db_password ./secrets/prod/db_password.txt
docker secret create prod_api_key ./secrets/prod/api_key.txt

# Staging secrets
docker secret create staging_db_password ./secrets/staging/db_password.txt
docker secret create staging_api_key ./secrets/staging/api_key.txt

# Reference in compose files via environment variables
secrets:
  db_password:
    external:
      name: ${ENV_PREFIX}_db_password  # Resolves to prod_db_password or staging_db_password

3. Implement Proper Access Control

Grant secrets only to services that genuinely need them. Avoid blanket secret assignments:

# BAD: All secrets exposed to all services
services:
  web:
    secrets:
      - db_password
      - api_key
      - tls_cert
      - jwt_secret
  worker:
    secrets:
      - db_password
      - api_key
      - tls_cert
      - jwt_secret

# GOOD: Principle of least privilege
services:
  web:
    secrets:
      - tls_cert       # Only web needs TLS termination
      - api_key        # Web calls external APIs
  worker:
    secrets:
      - db_password    # Worker processes database
      - jwt_secret     # Worker validates tokens
  cache:
    secrets: []        # Redis doesn't need any secrets

4. Combine Secrets with Docker Configs for Non-Sensitive Data

Not everything needs to be a secret. Use Docker configs for non-sensitive configuration:

# Docker configs for non-sensitive configuration
docker config create nginx_conf ./nginx.conf
docker config create app_settings ./settings.json

# Docker secrets for sensitive data
docker secret create db_password ./db_password.txt
docker secret create private_key ./id_rsa

# In docker-compose.yml
configs:
  nginx_conf:
    external: true
  app_settings:
    external: true
secrets:
  db_password:
    external: true
  private_key:
    external: true

5. Build Secret-Aware Container Images

Design your Dockerfile to expect secrets at runtime, never at build time:

# DANGEROUS: Secrets baked into image
FROM node:20-alpine
ARG DB_PASSWORD
ENV DB_PASSWORD=${DB_PASSWORD}  # Persists in image layers!
COPY . .
RUN npm install && npm run build

# SAFE: Image expects secrets at runtime via mount
FROM node:20-alpine
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
# Application reads from /run/secrets/ at runtime
CMD ["node", "dist/server.js"]

Use multi-stage builds to ensure no secrets leak into final images:

# Multi-stage build with build secrets properly handled
FROM node:20-alpine AS builder

# Mount secrets only during build (Docker BuildKit required)
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN=$(cat /run/secrets/npm_token) \
    npm config set //registry.npmjs.org/:_authToken=${NPM_TOKEN} && \
    npm ci && \
    npm config delete //registry.npmjs.org/:_authToken

FROM node:20-alpine AS runtime
COPY --from=builder /app/node_modules /app/node_modules
COPY --from=builder /app/dist /app/dist
# No secrets in final image
CMD ["node", "/app/dist/server.js"]

6. Monitor and Audit Secret Access

Implement logging around secret access patterns without capturing secret values:

// audit-config.js - Audit secret usage without exposing values
const fs = require('fs');

function loadSecretWithAudit(secretName) {
  const secretPath = `/run/secrets/${secretName}`;
  
  // Log metadata only
  console.log({
    event: 'secret_access',
    secret_name: secretName,
    timestamp: new Date().toISOString(),
    file_exists: fs.existsSync(secretPath),
    file_size: fs.existsSync(secretPath) ? fs.statSync(secretPath).size : 0,
    // NEVER log the actual secret value
  });
  
  return fs.readFileSync(secretPath, 'utf8').trim();
}

7. Plan for Secrets Backup and Disaster Recovery

Docker secrets cannot be read back via the API, but you must maintain encrypted backups. Use a secrets management chain:

# Store secrets encrypted in a secure vault, not just in Docker
# Use HashiCorp Vault, AWS Secrets Manager, or similar

# Example: Sync from AWS Secrets Manager to Docker secrets
#!/bin/bash
aws secretsmanager get-secret-value \
  --secret-id production/db-password \
  --query SecretString \
  --output text | docker secret create db_password -

# Document your secrets inventory (names only, never values)
cat > secrets-inventory.md << 'EOF'
# Secrets Inventory - Production
- db_password: PostgreSQL database password (rotated monthly)
- api_key: External payment processor API key (rotated quarterly)  
- tls_cert: Wildcard TLS certificate for *.example.com (rotated annually)
- jwt_secret: JWT signing key (rotated every 6 months)
EOF

Common Pitfalls and How to Avoid Them

Pitfall 1: Trying to Use Secrets Without Swarm Mode

The most frequent mistake is attempting to use secrets with standalone containers. This fails because secrets are a Swarm service feature:

# This will FAIL - secrets only work with swarm services
docker run -d --secret db_password nginx  # Error!

# Correct approach: Deploy as a single-replica swarm service
docker service create --secret db_password --name nginx nginx:alpine

Pitfall 2: Assuming Secrets Are Encrypted at Rest Inside Containers

Secrets are plaintext files inside the container's tmpfs mount. They are encrypted on manager nodes and in transit, but any process with filesystem access inside the container can read them. Mitigate this with proper container security:

# Use read-only root filesystem where possible
services:
  secure-app:
    image: myapp:latest
    read_only: true
    secrets:
      - db_password
    # tmpfs for paths that need write access
    tmpfs:
      - /tmp
      - /var/run

Pitfall 3: Hardcoding Secret Mount Paths

While /run/secrets/ is the standard mount point, always use the environment variable pattern for flexibility:

// Rigid approach - tightly coupled to Docker
const password = fs.readFileSync('/run/secrets/db_password', 'utf8');

// Flexible approach - works with any secret injection method
const secretPath = process.env.DB_PASSWORD_FILE || '/run/secrets/db_password';
const password = fs.readFileSync(secretPath, 'utf8');

Pitfall 4: Secret Name Collisions in Multi-Environment Deployments

When deploying multiple stacks to the same Swarm, secret names must be unique or explicitly managed:

# Problem: Two stacks using the same secret name
docker secret create db_password ./pass1.txt
docker secret create db_password ./pass2.txt  # Error: already exists!

# Solution: Namespace secrets per stack/environment
docker secret create stack1_db_password ./pass1.txt
docker secret create stack2_db_password ./pass2.txt

# In compose file, map external names to internal targets
secrets:
  db_password:
    external:
      name: stack1_db_password
    target: /run/secrets/db_password  # Container sees this path

Pitfall 5: Ignoring Secret Rotation Complexity

Secrets must be rotated regularly, but the immutable nature of Docker secrets requires careful orchestration:

# Antipattern: Trying to update a secret in place
docker secret update db_password ./new_password.txt  # Not possible!

# Correct pattern: Versioned secrets with service updates
# Create v2 of secret
docker secret create db_password_v2_$(date +%Y%m%d) ./new_password.txt

# Update service to use v2, then remove v1
docker service update \
  --secret-rm db_password_v1_20240101 \
  --secret-add source=db_password_v2_20240301,target=db_password \
  myapp

# After verifying all replicas use v2, remove v1
docker secret rm db_password_v1_20240101

Pitfall 6: Exposing Secrets via Debug Endpoints or Error Messages

Application error handling can inadvertently expose secrets. Always sanitize error output:

// Dangerous: Stack trace might include secret values
app.get('/debug', (req, res) => {
  res.json({
    config: dbConfig,  // Exposes password in debug endpoint!
    env: process.env,  // May include fallback secrets!
  });
});

// Safe: Explicitly exclude sensitive fields
app.get('/health', (req, res) => {
  res.json({
    status: 'ok',
    database: {
      connected: true,
      host: dbConfig.host,
      // Never include password, even if masked
    },
  });
});

Pitfall 7: Not Testing Secret Failure Scenarios

Applications should gracefully handle missing secrets. Test these scenarios:

# Test service startup with missing secret
docker service create --name test-app myapp:latest  # No secret provided
# Observe: Does the app fail fast with a clear error message?

# Test secret file permissions
docker exec container-id ls -l /run/secrets/db_password
# Should show restrictive permissions (usually 0444 or 0400)

# Test that secrets survive container restarts
docker service update --force myapp-stack_app
# Secrets should be remounted automatically

Advanced Patterns

Pattern: Secrets Proxy for Legacy Applications

Some legacy applications cannot read files and only accept environment variables. Use an entrypoint script to bridge the gap:

#!/bin/bash
# entrypoint.sh - Convert Docker secrets to environment variables for legacy apps

set -e

# Read each secret and export as environment variable
if [ -d "/run/secrets" ]; then
  for secret_file in /run/secrets/*; do
    if [ -f "$secret_file" ]; then
      secret_name=$(basename "$secret_file")
      # Convert secret name to UPPER_CASE env var name
      env_var_name=$(echo "$secret_name" | tr '[:lower:]' '[:upper:]')
      export "$env_var_name"="$(cat "$secret_file")"
      echo "Exported secret '${secret_name}' as environment variable '${env_var_name}'"
    fi
  done
fi

# Launch the legacy application
exec "$@"
# Dockerfile for legacy app
FROM legacy-app:old
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
CMD ["/app/legacy-server"]

Pattern: Templating Configuration with Secrets

For applications that require secrets embedded in configuration files, use a templating entrypoint:

#!/bin/bash
# configure-and-launch.sh

# Read secrets
DB_PASSWORD=$(cat /run/secrets/db_password)
API_KEY=$(cat /run/secrets/api_key)

# Generate configuration file from template
cat /app/config.template.json | \
  sed "s/\${DB_PASSWORD}/${DB_PASSWORD}/g" | \
  sed "s/\${API_KEY}/${API_KEY}/g" \
  > /app/config.json

# Securely wipe variables from memory (best effort)
unset DB_PASSWORD API_KEY

# Launch application
exec /app/server --config /app/config.json

Conclusion

Docker secrets management represents a significant improvement over traditional secret handling patterns in containerized environments. By encrypting secrets at rest on manager nodes, securing them in transit via mutual TLS, and mounting them as ephemeral filesystems, Docker Swarm provides a robust foundation for protecting sensitive configuration data.

However, secrets management is not a silver bullet. It requires thoughtful application design—applications must read secrets from files, handle missing secrets gracefully, and never leak values through logs or debug endpoints. Operational maturity demands regular secret rotation, careful namespace planning, and integration with external secrets management systems for backup and disaster recovery.

The patterns and practices outlined in this tutorial—from basic secret creation to advanced rotation scripts, from application code integration to legacy app bridging—provide a comprehensive framework for implementing secrets management in real-world Docker deployments. Remember that security is a layered concern: Docker secrets protect data in transit and at rest on managers, but container security, application logging hygiene, and access control policies form the remaining layers of a complete defense strategy.

🚀 Need a reliable AI agent for your project?

Deploy Hermes Agent in 10 minutes. Managed hosting, zero DevOps.

Get Started — $23.99/mo
← Back to all articles