# 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`](https://github.com/beatz174-bit/docker/blob/main/secrets/inventory.json).

## Scope and authority

- Canonical example template: [`secrets/.env.secrets.example`](https://github.com/beatz174-bit/docker/blob/main/secrets/.env.secrets.example)
- Runtime-loaded secret env file (local, non-committed): `../secrets/stack-secrets.env`
- Dynu DNS inventory env file (local, non-committed): `../secrets/dynu.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 Dynu env file (`dynu.env`)**
   - Holds `DYNU_*` values used by read-only Dynu DNS inventory scripts.
4. **Local Docker secret files (`*.txt`)**
   - Hold password/token material consumed via `*_FILE` style configuration.
5. **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`](https://github.com/beatz174-bit/docker/blob/main/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`](./deployment-prerequisites.md).

## Commit safety rules

Never commit:

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

## Related docs

- [`./deployment-prerequisites.md`](./deployment-prerequisites.md)
- [`./docker-environment.md`](./docker-environment.md)
- [`./source-of-truth.md`](./source-of-truth.md)