Merge #18: feat: [#14] Implement infrastructure/application deployment separation + integration testing fixes

aa968d0 feat: [#14] add SSH utilities and host key verification improvements (Jose Celano)
80df86f fix: [#14] eliminate sudo prompts in CI tests (Jose Celano)
a4a890c docs: [#14] improve documentation organization and markdownlint configuration (Jose Celano)
c4a1e7b feat: [#14] implement sudo cache management for infrastructure operations (Jose Celano)
52aacf4 refactor: [#14] centralize shell script logging and color utilities (Jose Celano)
9d30e4a docs: add GitHub Actions testing workflow status badge (Jose Celano)
eb5b45b refactor: remove unnecessary frontend_network from compose config (Jose Celano)
0bbf85e fix: [#12] improve deployment reliability with robust container health checks (Jose Celano)
537b87e test: [torrust#43] refactor E2E test and fix health checks (Jose Celano)
bed3bdb refactor(tests): split infrastructure script unit tests (Jose Celano)
21ad9ca docs: update pre-commit requirements to use make test-ci (Jose Celano)
357fdf2 refactor: reorganize tests into three-layer architecture (Jose Celano)
f6f7a93 fix: [#ci] initialize OpenTofu before validation in CI tests (Jose Celano)
645c589 docs: [#14] add automated test script reference to integration testing guide (Jose Celano)
f115545 ci: [#14] separate CI-compatible tests from virtualization-required tests (Jose Celano)
40a669e fix: [#14] make smoke testing mandatory and fix API authentication (Jose Celano)
027486a docs: [#14] clarify twelve-factor methodology and fix repo structure (Jose Celano)
a9a5bcb docs: [#14] consolidate twelve-factor documentation into single README (Jose Celano)
bc824ee docs: [#14] finalize documentation and deploy script updates (Jose Celano)
41ffd97 feat: [#14] implement integration testing workflow with local repository deployment (Jose Celano)
36bdb45 docs: remove staging environment from twelve-factor refactoring plan (Jose Celano)

Pull request description:

  # feat: [#14] Comprehensive twelve-factor deployment system with advanced developer experience

  This PR implements a complete twelve-factor application deployment system with sophisticated developer experience improvements, comprehensive testing infrastructure, and advanced automation capabilities.

  ## 🎯 Main Achievements

  ### 1. Twelve-Factor Application Deployment (Core Implementation)

  **Complete separation of infrastructure provisioning and application deployment:**

  ```bash
  # 1. Infrastructure provisioning (Platform setup)
  make infra-apply ENVIRONMENT=local

  # 2. Application deployment (Build + Release + Run stages)
  make app-deploy ENVIRONMENT=local

  # 3. Health validation (Comprehensive verification)
  make health-check ENVIRONMENT=local
  ```

  ### 2. Advanced Developer Experience System

  **SSH Host Key Management Automation:**
  - Automatic SSH known_hosts cleanup during VM provisioning
  - Dedicated SSH utilities (`infrastructure/scripts/ssh-utils.sh`)
  - New Makefile targets: `make ssh-clean`, `make ssh-prepare`
  - Eliminates common host key verification warnings

  **Intelligent Sudo Cache Management:**
  - Proactive sudo credential caching for infrastructure operations
  - Clear user prompts before operations requiring privileges
  - Prevents password prompts mixed with verbose OpenTofu output
  - Documented in ADR-005 with 7 alternatives considered

  ### 3. Centralized Shell Utilities & Code Quality

  **Major Refactoring Achievement:**
  - Created shared utility system (`scripts/shell-utils.sh`)
  - **Eliminated ~200 lines of duplicate code** across 12 scripts
  - Standardized logging, color output, and error handling
  - Tee logging support for debugging complex operations

  ## 🏗️ Architecture Enhancements

  ### New Infrastructure Scripts
  - `infrastructure/scripts/provision-infrastructure.sh` - Pure infrastructure provisioning
  - `infrastructure/scripts/deploy-app.sh` - Application deployment with local repository support
  - `infrastructure/scripts/health-check.sh` - 14-point comprehensive validation
  - `infrastructure/scripts/ssh-utils.sh` - SSH troubleshooting automation

  ### Three-Layer Testing Architecture
  ```
  1. CI Tests (test-ci)     - Syntax + config validation (no virtualization)
  2. Local Tests (test-local) - Infrastructure validation (requires KVM/libvirt)
  3. E2E Tests (test)       - Full deployment with health checks (5-8min)
  ```

  ### Enhanced Container Orchestration
  - Robust health checks for all Docker services
  - Improved deployment reliability with retry logic
  - Cleaned up unnecessary network configurations
  - MySQL database migration completion (production parity)

  ## 🔧 Integration Testing Fixes

  ### 1. Local Repository Deployment
  - **Fixed:** `deploy-app.sh` now uses `git archive` instead of GitHub clone
  - **Benefit:** Test local changes (including uncommitted) before pushing
  - **Impact:** 100% reliable local development workflow

  ### 2. SSH Authentication & Connectivity
  - **Fixed:** Comprehensive SSH key-based authentication in cloud-init
  - **Fixed:** Added `BatchMode=yes` for reliable automation
  - **Fixed:** Automatic SSH known_hosts management
  - **Result:** 100% reliable SSH connectivity and automation

  ### 3. Endpoint Validation & Database
  - **Fixed:** Health checks updated for current nginx proxy architecture
  - **Fixed:** MySQL connectivity and database validation
  - **Fixed:** API authentication with proper admin token handling
  - **Result:** All 14 health checks pass consistently

  ## 📊 Validation Results

  ```
  === HEALTH CHECK REPORT ===
  Environment:      local
  Total Tests:     14
  Passed:          14
  Failed:          0
  Success Rate:    100%

  === SMOKE TESTING ===
  ✅ UDP Trackers (6868, 6969): JSON responses with peer data
  ✅ HTTP Tracker (nginx proxy): Tracker statistics via port 80
  ✅ Health Check API: {"status": "Ok"} response
  ✅ Statistics API: Complete metrics via nginx proxy
  ✅ Prometheus Metrics: Formatted data on port 1212
  ```

  ## 🧪 Testing Infrastructure Improvements

  ### CI/CD Integration
  - **Added:** GitHub Actions status badge for visibility
  - **Fixed:** Non-interactive CI execution (eliminated sudo prompts)
  - **Enhanced:** Separate test targets for different environments
  - **Result:** Fast CI tests (30s syntax) + thorough local tests (5-8min E2E)

  ### Test Organization & Coverage
  - **Created:** Comprehensive test suite with 24+ test files
  - **Added:** Unit tests for all infrastructure scripts
  - **Enhanced:** Application deployment testing
  - **Improved:** Configuration validation testing

  ## 📚 Documentation & Architecture Decisions

  ### New Architecture Decision Records (ADRs)
  - **ADR-005:** Sudo Cache Management for Infrastructure Operations
  - **Enhanced:** ADR documentation system with guidelines and templates
  - **Added:** Dedicated ADR organization (`docs/adr/README.md`)

  ### Comprehensive Documentation
  - **Created:** SSH Host Key Verification troubleshooting guide
  - **Added:** Shell utilities migration summary with patterns
  - **Enhanced:** Test organization and strategy documentation
  - **Improved:** Markdownlint configuration with global table exclusions
  - **Updated:** Integration testing guide with automated workflow

  ## 🔄 Backward Compatibility & Migration

  **Legacy commands maintained with helpful guidance:**
  ```bash
  make apply    # Shows: "⚠️ DEPRECATED: Use 'make infra-apply + app-deploy'"
  make destroy  # Shows: "⚠️ DEPRECATED: Use 'make infra-destroy'"
  ```

  **Smooth migration path for existing workflows while encouraging twelve-factor adoption.**

  ## 📈 Impact & Metrics

  - **Files Changed:** 57 files
  - **Code Changes:** +10,020 insertions, -3,312 deletions
  - **Net Result:** ~6,700 lines of new functionality
  - **Code Quality:** ~200 lines of duplicate code eliminated
  - **Testing:** 100% health check success rate
  - **Developer Experience:** Automated SSH and sudo management
  - **Documentation:** 5 ADRs + comprehensive guides

  ## 🎯 Future Foundation

  This implementation establishes the complete foundation for the twelve-factor configuration management system. The infrastructure/application separation is operational and ready for:

  - Production Hetzner deployment
  - Environment-specific configuration management
  - Advanced monitoring and observability
  - Scalable multi-environment workflows

  ## ✅ Quality Assurance

  - **All linting passes:** YAML, Shell (ShellCheck), Markdown
  - **All tests pass:** CI tests (3min) + E2E tests (8min)
  - **100% deployment reliability:** Local repository + SSH automation
  - **Comprehensive validation:** 14-point health check system
  - **Documentation coverage:** Every major component documented

ACKs for top commit:
  josecelano:
    ACK aa968d0

Tree-SHA512: 65a7ec2bed0ade1a5565eb80c5291054623dcd421519332a191da8bc19b9a3050657f51a06da61fa4073b7642afb8dad0c08079e513a46fca432cae9b287ec34

Author: josecelano

.github/copilot-instructions.md

@@ -7,19 +7,24 @@ on:
     branches: [main, develop]
 
 jobs:
-  lint:
+  ci-tests:
     runs-on: ubuntu-latest
+    name: CI-Compatible Tests
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Install linting tools
+      - name: Install dependencies
         run: |
           sudo apt-get update
-          sudo apt-get install -y yamllint shellcheck
+          sudo apt-get install -y yamllint shellcheck docker-compose
           sudo npm install -g markdownlint-cli
 
-      - name: Run linting script
-        run: |
-          ./scripts/lint.sh
+          # Install OpenTofu
+          curl -fsSL https://get.opentofu.org/install-opentofu.sh -o install-opentofu.sh
+          chmod +x install-opentofu.sh
+          sudo ./install-opentofu.sh --install-method deb
+
+      - name: Run CI test suite
+        run: make test-ci

.github/workflows/testing.yml

@@ -1,7 +1,8 @@
 {
     "default": true,
     "MD013": {
-        "line_length": 100
+        "line_length": 100,
+        "tables": false
     },
     "MD031": true,
     "MD032": true,

.markdownlint.json

@@ -0,0 +1,38 @@
+# Markdownlint Configuration
+
+This file documents the markdownlint configuration for the project.
+
+## Line Length Handling
+
+The project enforces a 100-character line limit for markdown files (`MD013` rule).
+Tables are automatically excluded from this limit to maintain readability.
+
+### Table Line Length Configuration
+
+Tables are configured to ignore line length limits globally via the `.markdownlint.json` configuration:
+
+```json
+"MD013": {
+    "line_length": 100,
+    "tables": false
+}
+```
+
+This means:
+
+- **Regular text**: Must stay within 100 characters per line
+- **Tables**: Can exceed line length limits without linting errors
+- **Code blocks**: Follow normal line length rules
+
+### Alternative Approach
+
+If you need to disable line length for specific non-table content, you can still use
+markdownlint ignore blocks:
+
+```markdown
+<!-- markdownlint-disable MD013 -->
+
+Very long line content that needs to exceed the normal limit
+
+<!-- markdownlint-enable MD013 -->
+```