Document 12-factor deployment process and two-level environment variable structure

[josecelano]

Overview

We need to improve documentation to clarify our 12-factor deployment approach and the two-level environment variable structure.

Background

This project follows 12-factor app recommendations with a clear deployment process:

1. Create environment variables - Customize deployment variables
2. Provision infrastructure - Create VM with cloud-init system setup
3. Deploy application - Copy artifacts, generate certificates, run application (Release + Run stages)
4. Validation - Health checks and verification

Issues to Address

1. Missing 12-Factor Deployment Overview

We need a clear introduction to our deployment process in key documentation files:

• Main README.md
• .github/copilot-instructions.md
• docs/guides/cloud-deployment-guide.md

2. Two-Level Environment Variable Structure Needs Clarification

We have two distinct levels of environment variables that aren't clearly documented:

Level 1: Main Environment Variables

• Stored in infrastructure/config/environments/
• Example: infrastructure/config/environments/local.env
• Contains ALL configuration for the deployment process
• Used for infrastructure provisioning, SSL generation, backups, etc.

Level 2: Docker Compose Environment Variables

• Template: infrastructure/config/templates/docker-compose.env.tpl
• Final file: .env (used by docker compose)
• Contains ONLY variables needed by running containers
• Filtered subset for security and simplicity
• Excludes infrastructure-specific variables

3. ADR Documentation Gap

• Create new ADR documenting the two-level environment variable approach
• Update .github/copilot-instructions.md with ADR table/list

Tasks

• Add 12-factor deployment overview to main documentation
• Create ADR for two-level environment variable structure
• Update copilot instructions with ADR reference table
• Enhance existing documentation to clarify the distinction

Acceptance Criteria

• Clear 12-factor deployment process documented in key locations
• Two-level environment variable structure is well-documented
• New ADR created and referenced appropriately
• Documentation is consistent across all files