docker/docs/security-secrets.md

Security Secrets

Overview

This page explains how secret material is organized in this repository and where to find both human-readable and machine-readable references.

For machine-readable inventory metadata, use ../secrets/inventory.json.

Scope and authority

• Canonical example template: ../secrets/.env.secrets.example
• Runtime-loaded secret env file (local, non-committed): ../secrets/stack-secrets.env
• Docker secret files (local, non-committed): ../secrets/*.txt

Treat the example template as the canonical shape for expected environment variables.

Secret material types

1. Template variables in .env.secrets.example
   • Document expected variable names and usage expectations.
2. Local runtime env file (stack-secrets.env)
   • Holds local runtime secret values loaded during compose rendering.
3. Local Docker secret files (*.txt)
   • Hold password/token material consumed via *_FILE style configuration.
4. Externally managed secret inputs
   • Some values are managed outside shared templates and provided through file mounts or environment substitution.

Machine-readable inventory

• Primary automation source: ../secrets/inventory.json
• Human guidance source: this page

Automation should parse secrets/inventory.json directly rather than scraping Markdown tables.

Setup and deployment prerequisites

Before running compose operations, follow ./deployment-prerequisites.md.

Commit safety rules

Never commit:

• secrets/stack-secrets.env
• real secrets/*.txt secret files
• real Terraform .tfvars files containing credentials
• Terraform state files with sensitive runtime metadata

Related docs

• ./deployment-prerequisites.md
• ./docker-environment.md
• ./source-of-truth.md