EVOLV/.agents/decisions/DECISION-20260323-compose-secrets-via-env.md

DECISION-20260323-compose-secrets-via-env

Context

• Task/request: harden the target-state stack example so credentials are not stored directly in temp/cloud.yml.
• Impacted files/contracts: temp/cloud.yml, deployment/operations practice for target-state infrastructure examples.
• Why a decision is required now: the repository contained inline credentials in a tracked compose file, which conflicts with the intended security posture and creates avoidable secret-leak risk.

Options

1. Keep credentials inline in the compose file

• Benefits: simplest to run as a standalone example.
• Risks: secrets leak into git history, reviews, copies, and local machines; encourages unsafe operational practice.
• Rollout notes: none, but the risk remains permanent once committed.

2. Move credentials to server-side environment variables and keep only placeholders in compose

• Benefits: aligns the manifest with a safer deployment pattern; keeps tracked config portable across environments; supports secret rotation without editing the compose file.
• Risks: operators must manage .env or equivalent secret injection correctly.
• Rollout notes: provide an example env file and document that the real .env stays on the server and out of version control.

Decision

• Selected option: Option 2.
• Decision owner: repository owner confirmed during task discussion.
• Date: 2026-03-23.
• Rationale: the target architecture should model the right operational pattern. Inline secrets in repository-tracked compose files are not acceptable for EVOLV's intended OT/IT deployment posture.

Consequences

• Compatibility impact: low; operators now need to supply environment variables when deploying temp/cloud.yml.
• Safety/security impact: improved secret hygiene and lower credential exposure risk.
• Data/operations impact: deployment requires an accompanying .env on the server or explicit --env-file usage.

Implementation Notes

• Required code/doc updates: replace inline secrets in temp/cloud.yml; add temp/cloud.env.example; keep the real .env untracked on the server.
• Validation evidence required: inspect compose file for ${...} placeholders and verify no real credentials remain in tracked files touched by this change.

Rollback / Migration

• Rollback strategy: reintroduce inline values, though this is not recommended.
• Migration/deprecation plan: create a server-local .env from temp/cloud.env.example, fill in real values, and run compose from that environment.