Setting this up takes about five minutes and will save you endless headaches.

When a Node.js or Python app crashes, it often creates a core dump or a heap snapshot. These memory dumps contain the exact string values of your .secrets file. If a crash report is sent to a third-party service (Sentry, Bugsnag), your secrets go with it.

To understand the .secrets file, we must first recall the old ways. In the ancient era of the early 2000s, developers stored credentials directly in configuration files:

This worked until the first major breach caused by a leaked configuration file. The problem was separation of concerns: application logic, deployment configuration, and secrets were all tangled together.

The .secrets pattern emerged from the Twelve-Factor App methodology (circa 2011). Factor III of that manifesto states: "Store config in the environment." It argued that codebase, config, and credentials should be strictly separated. A .secrets file became the local development vehicle for that principle—a way to simulate environment variables without polluting your system's global namespace.

If you find a project relying on .secrets, recommend:

my‑app/
├─ src/
│   └─ main.py
├─ .gitignore
├─ .secrets          ← **never added to git**
├─ Dockerfile
├─ docker-compose.yml
└─ README.md

.gitignore

# Secrets
.secrets
.secrets.*

docker‑compose.yml (using an env file)

version: "3.9"
services:
  web:
    build: .
    env_file:
      - .secrets          # injected into container at runtime
    ports:
      - "8000:8000"

Running locally

# 1️⃣ Ensure the file exists and is chmod 600
touch .secrets && chmod 600 .secrets
# 2️⃣ Add your key/value pairs
echo "DB_PASSWORD=SuperSecret123!" >> .secrets
# 3️⃣ Start the app (Docker compose will automatically read the file)
docker compose up

The .secrets file is rarely the source of truth in a professional setup. It is usually a transient artifact. The source of truth is a Secret Vault. The industry standard is HashiCorp Vault, but alternatives include AWS Secrets Manager, Azure Key Vault, and Doppler.

Here is the professional workflow for .secrets: