Docker Secrets in production: protecting secrets on a VPS

The real risk: your secrets travel inside your images

5 configuration mistakes that expose your secrets

• Plaintext env vars in docker-compose.yml — environment: DB_PASSWORD: hunter2 is readable by anyone who accesses the file or the image.
• Committed .env file — miss .gitignore once, and the secret is in git history forever (even after git rm, accessible via git log).
• ARG passed at build then copied into the image — ARGs are baked into layer metadata and readable via docker history.
• Secrets in logs — an application that logs its environment variables at startup (Spring Boot, Rails in debug mode, some Node servers) prints credentials in docker logs.
• Bind-mount volumes on /root or the project directory — a .env file mounted from the host remains accessible to any process in the container with root privileges.

Prerequisites

Method 1 — Docker Secrets in non-Swarm Compose (step by step)

1. 01

   Check the Compose version

   Docker Secrets work without Swarm since Docker Compose v2.24.0 (released January 11, 2024). Verify:

   docker compose version
   # Docker Compose version v2.27.1

   If you're below v2.24, update Compose before continuing (apt-get install docker-compose-plugin on Debian/Ubuntu).

2. 02

   Create the secret files

   Docker Compose secrets in non-Swarm mode are files on the host, mounted as tmpfs inside the container. Create them outside the project directory:

   mkdir -p /etc/myapp/secrets
   echo -n 'strong-db-password' > /etc/myapp/secrets/db_password
   echo -n 'stripe-api-key-xxxxx' > /etc/myapp/secrets/stripe_key
   chmod 600 /etc/myapp/secrets/*
   chown root:root /etc/myapp/secrets/*

   The -n flag of echo avoids a trailing newline — some applications read the entire file including the newline, which invalidates the key.

3. 03

   Declare secrets in docker-compose.yml

   services:
     app:
       image: myapp:latest
       secrets:
         - db_password
         - stripe_key
       environment:
         # indicate the PATH, not the value
         DB_PASSWORD_FILE: /run/secrets/db_password
         STRIPE_KEY_FILE: /run/secrets/stripe_key
   
   secrets:
     db_password:
       file: /etc/myapp/secrets/db_password
     stripe_key:
       file: /etc/myapp/secrets/stripe_key

   Note the use of the *_FILE convention: your application must read the DB_PASSWORD_FILE variable, open the indicated file and read its content. Official PostgreSQL, MySQL, Redis images and most Bitnami images natively support this convention — check your image's documentation.

4. 04

   Verify the mount inside the container

   After docker compose up -d, inspect the mount:

   docker compose exec app ls -la /run/secrets/
   # -r-------- 1 root root 20 Sep 20 08:12 db_password
   # -r-------- 1 root root 28 Sep 20 08:12 stripe_key
   
   docker inspect myapp_app_1 | grep -A5 Mounts
   # "Type": "tmpfs",
   # "Destination": "/run/secrets",

   The mount type is tmpfs: the content lives in RAM, never written to the container's disk. It disappears when the container stops.

5. 05

   What Docker Secrets does NOT do — understand before continuing

   Docker Secrets is not a hermetic vault. What it does not protect against:

   - The source file (/etc/myapp/secrets/db_password) remains on the host disk in plaintext — root on the VM always has access.
   - Any process in the container (PID 1 or a subprocess launched by the app) can read /run/secrets/*.
   - An env variable derived from the secret (DB_PASSWORD=$(cat /run/secrets/db_password) in an entrypoint) puts the secret back into the env, visible via docker inspect.

   Docker Secrets protects against leaks in image layers and in docker-compose.yml. It does not protect against a compromised process inside the container.

Docker Secrets vs .env.vault vs SOPS — which method for which context

Scroll the table

Supplementary configuration: rotation and encryption at rest

# 1. Write the new value
echo -n 'new-password' > /etc/myapp/secrets/db_password
# 2. Restart the affected service
docker compose restart app

# Generate an age key
age-keygen -o /root/.config/sops/age/keys.txt
# Encrypt the secret file
sops --encrypt --age $(age-keygen -y /root/.config/sops/age/keys.txt) \
  /etc/myapp/secrets/db_password > /etc/myapp/secrets/db_password.enc
# In your startup script, decrypt before docker compose up
sops --decrypt /etc/myapp/secrets/db_password.enc > /etc/myapp/secrets/db_password

Troubleshooting — common errors

Your secrets under control — and what's next