Skip to content
This repository was archived by the owner on Oct 10, 2025. It is now read-only.

[#26] Document 12-factor deployment process and two-level environment variable structure #27

Merged
merged 3 commits into from
Jul 31, 2025
Merged

[#26] Document 12-factor deployment process and two-level environment variable structure #27

merged 3 commits into from
Jul 31, 2025

Conversation

josecelano
Copy link
Member

Summary

This PR addresses issue #26 by documenting our 12-factor deployment process and formalizing the two-level environment variable structure used throughout the project.

Changes Made

📚 12-Factor Deployment Process Documentation

  • Enhanced README.md with comprehensive 4-step deployment process overview
  • Updated cloud deployment guide with detailed workflow explanation aligned with twelve-factor methodology
  • Improved copilot instructions with ADR reference table and environment variable structure details

🔐 Two-Level Environment Variable Structure (ADR-007)

  • Created ADR-007 documenting the security-focused environment variable separation
  • Level 1: Main environment files (infrastructure/config/environments/) containing ALL deployment configuration
  • Level 2: Docker environment files (generated from templates) with filtered container-only variables
  • Security benefits: Reduced attack surface, principle of least privilege for containers

Key Documentation Updates

  1. README.md: Added clear 4-step deployment process (Configure → Provision → Deploy → Validate)
  2. Cloud Deployment Guide: Enhanced with detailed Build/Release/Run stage explanations
  3. Copilot Instructions: Added ADR reference table and environment variable structure guidance
  4. New ADR-007: Complete documentation of two-level environment variable approach

Benefits

  • 🔒 Security: Infrastructure secrets isolated from application containers
  • 📖 Clarity: Clear separation between infrastructure and application configuration
  • 🛠️ Maintainability: Contributors understand where to modify different types of variables
  • ✅ Compliance: Aligns with twelve-factor app configuration principles

Two-Level Environment Structure

Level 1 (Infrastructure):

  • Location: infrastructure/config/environments/local.env, production.env
  • Contains: SSL domains, backup settings, VM specifications, all secrets
  • Usage: Sourced by deployment scripts for complete deployment process

Level 2 (Containers):

  • Template: infrastructure/config/templates/docker-compose.env.tpl
  • Generated: application/.env → /var/lib/torrust/compose/.env on VM
  • Contains: Database connections, API tokens, runtime configuration only
  • Usage: docker compose --env-file /var/lib/torrust/compose/.env up -d

Testing

  • ✅ All markdown linting passes
  • ✅ Infrastructure unit tests pass
  • ✅ Documentation structure validated
  • ✅ Correct Docker Compose --env-file usage documented

Related Issues

Closes #26

Checklist

  • Add 12-factor deployment overview to main documentation
  • Create ADR for two-level environment variable structure
  • Update copilot instructions with ADR reference table
  • Enhance documentation to clarify infrastructure vs container variables
  • Fix Docker Compose environment configuration example
  • All linting and tests pass

@josecelano
docs: [#26] add 12-factor deployment process overview
3471409 
- Add comprehensive 4-step deployment process section to README.md
- Enhance cloud deployment guide with detailed workflow explanation
- Add ADR reference table to copilot instructions for contributor guidance
- Clarify separation between infrastructure provisioning and application deployment
- Document Build/Release/Run stages alignment with twelve-factor methodology
@josecelano
docs: [#26] create ADR-007 for two-level environment variable structure
207c404 
- Add comprehensive ADR documenting security-focused environment variable separation
- Level 1: Main environment files for complete deployment configuration
- Level 2: Docker environment files with filtered container-only variables
- Update ADR table in copilot instructions with new ADR-007 entry
- Enhance twelve-factor Release stage documentation with environment structure details
- Provide clear guidelines for infrastructure vs container variable management
@josecelano
docs: [#26] fix Docker Compose environment configuration example and …
7ede6e4 
…improve formatting

- Correct ADR-007 container configuration example to show actual --env-file usage
- Fix Docker Compose example from incorrect env_file property to correct command-line flag
- Improve ADR table formatting in copilot instructions for better readability
- Remove trailing spaces and minor formatting improvements
@josecelano josecelano requested a review from da2ce7 July 31, 2025 16:18
@josecelano
Copy link
Member Author

ACK 7ede6e4

@josecelano josecelano self-assigned this Jul 31, 2025
@josecelano josecelano added the Documentation Improves Instructions, Guides, and Notices label Jul 31, 2025
@josecelano josecelano merged commit b84c1e8 into main Jul 31, 2025
1 check passed
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

@da2ce7 da2ce7 Awaiting requested review from da2ce7

Assignees

@josecelano josecelano

Labels

Documentation Improves Instructions, Guides, and Notices

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

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

1 participant

@josecelano