Docker Compose — Compose Secrets

Docker Compose secrets provide a secure way to pass sensitive data (passwords, API keys, certificates) to containers without exposing them as environment variables.

Why Secrets?

Method	Visible in docker inspect?	Visible in env?	Secure?
environment:	Yes	Yes	No
env_file:	Yes	Yes	No
secrets:	No	No	Yes

Defining Secrets

compose.yml:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt

secrets/db_password.txt:

mysecretpassword

How Secrets Work

secrets/db_password.txt
        │
        ▼
┌─── Container ──────────┐
│  /run/secrets/          │
│    └── db_password      │ ← Mounted as file (read-only)
│                         │
│  Contents:              │
│    mysecretpassword     │
└─────────────────────────┘

Secrets are mounted as files under /run/secrets/<name>. Many official images support *_FILE environment variables that read from a file path.

Reading Secrets in Your App

Node.js example:

const fs = require('fs');
const password = fs.readFileSync('/run/secrets/db_password', 'utf8').trim();

Python example:

with open('/run/secrets/db_password') as f:
    password = f.read().strip()

Multiple Secrets

services:
  api:
    image: myapi:latest
    secrets:
      - db_password
      - api_key
      - ssl_cert

secrets:
  db_password:
    file: ./secrets/db_password.txt
  api_key:
    file: ./secrets/api_key.txt
  ssl_cert:
    file: ./certs/server.crt

Environment Secrets (Compose v2.23+)

secrets:
  api_key:
    environment: MY_API_KEY    # Read from host env variable

Custom Mount Path

services:
  api:
    secrets:
      - source: ssl_cert
        target: /etc/ssl/server.crt
        uid: "1000"
        gid: "1000"
        mode: 0440

Best Practices

1. Never commit secrets to version control
2. Add secrets/ to .gitignore
3. Use *_FILE env vars when available
4. Set restrictive file permissions (mode: 0400)

Summary

Feature	Detail
Mount path	/run/secrets/<name>
Source	File or environment variable
Visibility	Not in docker inspect or env
Official images	Support *_FILE env vars
Custom target	target: for custom path

---

Quick Reference

Item	Detail
secrets:	Top-level key defines secrets
file:	Secret from a local file
environment:	Secret from host env (v2.23+)
Mount	/run/secrets/ (read-only)
*_FILE vars	Official image pattern for secrets
Security	Add secrets/ to .gitignore