Merge #23: feat: [#21] Complete application installation automation with SSL automation

eb44dd9 docs: update integration testing guide with SSL automation and fix inconsistencies (Jose Celano)
35755fc fix: [#21] resolve SSL certificate key usage compatibility for browsers (Jose Celano)
d538027 docs: [#21] update cloud deployment guide to explain two-phase SSL approach (Jose Celano)
0d81001 docs: [#21] update documentation to reflect SSL automation completion (Jose Celano)
8d8cbd9 docs: document SSL certificate generation strategy (Jose Celano)
9af19e6 feat: [#21] implement complete HTTPS automation with self-signed certificates (Jose Celano)
331ba20 fix: [#21] resolve deployment script issues found during e2e testing (Jose Celano)
cb6815b Remove Pebble infrastructure and integrate self-signed certificates into standard deployment (Jose Celano)
f642485 fix: [#21] resolve e2e test failures and validate SSL automation infrastructure (Jose Celano)
2325952 docs: [#21] fix markdown formatting in SSL automation documentation (Jose Celano)
614eaae feat: [#21] Implement Pebble SSL testing environment and decide on pre-generated cert approach (Jose Celano)

Pull request description:

  ## Overview

  This PR implements **Phase 3 of the Hetzner migration**: Complete Application Installation Automation with SSL certificate automation. This achieves **90%+ automation** of the deployment process, significantly reducing manual setup steps required for production deployments.

  Resolves #21

  ## What's New

  ### 🔐 Complete SSL Automation Infrastructure

  - **Self-signed certificate generation** for local testing and development
  - **Automated nginx HTTPS configuration** with certificate integration
  - **SSL validation and testing utilities** for end-to-end verification
  - **Two-phase SSL approach**: Self-signed certificates with clear upgrade path to Let's Encrypt

  ### 🚀 Enhanced Deployment Workflow

  - **Integrated SSL setup** into `make app-deploy` workflow
  - **Automated certificate generation** during application deployment
  - **Browser-compatible certificates** with proper key usage extensions
  - **Comprehensive SSL testing** integrated into E2E test suite

  ### 📚 Documentation & Architecture

  - **ADR-006**: SSL Certificate Generation Strategy documented
  - **Updated guides**: Integration testing, cloud deployment, SSL testing
  - **Clear migration path** from self-signed to production Let's Encrypt certificates

  ## Key Features

  ### SSL Certificate Automation

  - ✅ **Automatic certificate generation** during deployment
  - ✅ **Browser compatibility** with proper certificate extensions
  - ✅ **Domain-specific certificates** for each environment
  - ✅ **Integrated nginx configuration** with HTTPS support
  - ✅ **SSL validation utilities** for testing and verification

  ### Enhanced Development Experience

  - ✅ **One-command deployment** with SSL included
  - ✅ **Local HTTPS testing** with self-signed certificates
  - ✅ **Comprehensive E2E testing** including SSL validation
  - ✅ **Clear upgrade path** to production certificates

  ### Infrastructure Improvements

  - ✅ **Modular SSL scripts** for certificate management
  - ✅ **Environment-specific configuration** for SSL setup
  - ✅ **Automated nginx template processing** with SSL extensions
  - ✅ **Shell utilities consolidation** across infrastructure and application layers

  ## Technical Implementation

  ### New SSL Scripts

  - `ssl-setup.sh` - Main SSL setup orchestrator
  - `ssl-generate.sh` - Certificate generation logic
  - `ssl-configure-nginx.sh` - Nginx HTTPS configuration
  - `ssl-validate-dns.sh` - DNS validation utilities
  - `ssl-generate-test-certs.sh` - Self-signed certificate generation

  ### Architecture Changes

  - **Unified shell utilities** between infrastructure and application layers
  - **Template-based nginx configuration** with SSL extension support
  - **Environment-aware SSL configuration** via template system
  - **Integration with twelve-factor deployment workflow**

  ## Testing & Validation

  ### End-to-End Testing

  - ✅ **SSL certificate generation** validated in E2E tests
  - ✅ **HTTPS endpoint testing** integrated into smoke tests
  - ✅ **Browser compatibility** verified through testing
  - ✅ **Certificate validation** automated in test suite

  ### Manual Testing Performed

  - ✅ Local deployment with SSL automation
  - ✅ Certificate generation and nginx configuration
  - ✅ HTTPS endpoint accessibility testing
  - ✅ Browser certificate acceptance validation

  ## Migration Impact

  ### Before This PR
  - Manual SSL certificate setup required
  - Multiple manual configuration steps for HTTPS
  - No automated SSL testing or validation
  - Complex nginx configuration required

  ### After This PR
  - ✅ **One-command SSL deployment**: `make app-deploy` includes SSL setup
  - ✅ **Automated certificate generation** with proper browser compatibility
  - ✅ **Integrated SSL testing** in E2E test suite
  - ✅ **Clear documentation** for SSL setup and troubleshooting

  ## Deployment Workflow

  The new SSL automation integrates seamlessly into the existing twelve-factor workflow:

  ```bash
  make infra-apply   # Infrastructure provisioning
  make app-deploy    # Application + SSL deployment (NEW: includes SSL automation)
  make app-health-check  # Health validation (NEW: includes SSL endpoint testing)
  ```

  ## Future Enhancements

  This implementation provides the foundation for:

  - **Let's Encrypt integration** for production environments
  - **Certificate renewal automation** with cron jobs
  - **Multi-domain certificate support** for complex deployments
  - **Certificate monitoring and alerting** integration

  ## Files Changed

  ### Core SSL Implementation
  - `application/share/bin/ssl-*.sh` - SSL automation scripts
  - `infrastructure/config/templates/nginx-*.conf.tpl` - HTTPS nginx templates
  - `infrastructure/scripts/deploy-app.sh` - SSL integration into deployment

  ### Documentation & Architecture
  - `docs/adr/006-ssl-certificate-generation-strategy.md` - Architecture decision
  - `docs/guides/ssl-testing-guide.md` - SSL testing documentation
  - `docs/guides/integration-testing-guide.md` - Updated with SSL automation
  - `docs/guides/cloud-deployment-guide.md` - SSL deployment guidance

  ### Testing & Validation
  - Enhanced E2E tests with SSL validation
  - Updated health check scripts with HTTPS support
  - Comprehensive SSL testing utilities

  ## Breaking Changes

  **None** - This is a backward-compatible enhancement that extends existing functionality without changing current behavior.

  ## Checklist

  - ✅ Implementation tested locally with E2E test suite
  - ✅ Documentation updated to reflect new SSL automation
  - ✅ Architecture decisions documented (ADR-006)
  - ✅ No breaking changes to existing workflows
  - ✅ SSL automation integrated into twelve-factor deployment
  - ✅ Browser compatibility validated through testing

ACKs for top commit:
  josecelano:
    ACK eb44dd9

Tree-SHA512: 0f05a6376457ed5902c1a9945431e346a965a9f10da58559a685b6d4cd4336e333ec7532458fde861f66d65ba0f8d8ee61c2e138dac0e0d8e0f814f862ab836c

Author: josecelano

application/compose.yaml

@@ -27,9 +27,12 @@ services:
     volumes:
       - /var/lib/torrust/proxy/webroot:/var/www/html
       - /var/lib/torrust/proxy/etc/nginx-conf:/etc/nginx/conf.d
+      - /var/lib/torrust/proxy/certs:/etc/ssl/certs
+      - /var/lib/torrust/proxy/private:/etc/ssl/private
       - /var/lib/torrust/certbot/etc:/etc/letsencrypt
+      - /var/lib/torrust/certbot/webroot:/var/lib/torrust/certbot/webroot
       - /var/lib/torrust/certbot/lib:/var/lib/letsencrypt
-      - /var/lib/torrust/dhparam:/etc/ssl/certs
+      - /var/lib/torrust/dhparam:/etc/ssl/dhparam
     logging:
       options:
         max-size: "10m"

application/docs/deployment.md

@@ -53,7 +53,58 @@ If you need to manually deploy on the server:
    docker compose --env-file /var/lib/torrust/compose/.env up -d
    ```
 
-## 3. Verification and Smoke Testing
+## 3. SSL Certificate Management
+
+### Certificate Generation Strategy
+
+The deployment process generates SSL certificates on each deployment rather than
+reusing certificates. This approach provides several advantages:
+
+#### Why Generate Certificates Per Deployment?
+
+1. **Production Flexibility**: Different environments use different domains:
+
+   - Local testing: `test.local`
+   - Staging: `staging.example.com`
+   - Production: `tracker.torrust-demo.com`
+
+2. **Certificate Validity**: Self-signed certificates are domain-specific and must
+   exactly match the domain being used in each deployment environment.
+
+3. **Security Best Practices**: Fresh certificates for each deployment ensure no
+   stale or leaked credentials are reused.
+
+4. **Workflow Consistency**: The same deployment process works across all
+   environments without manual certificate management or copying certificates
+   between systems.
+
+5. **Zero Configuration**: No need to maintain a certificate store or handle
+   certificate distribution between development and production environments.
+
+#### Certificate Types by Environment
+
+- **Local/Testing**: Self-signed certificates with 10-year validity (for convenience in testing)
+- **Production**: Let's Encrypt certificates (automatically renewed)
+
+#### Implementation Details
+
+The certificate generation happens during the application deployment phase
+(`make app-deploy`) and includes:
+
+1. **Self-signed certificates**: Generated using OpenSSL with domain-specific
+   Subject Alternative Names (SAN)
+2. **Certificate placement**: Stored in `/var/lib/torrust/proxy/certs/` and
+   `/var/lib/torrust/proxy/private/` on the target server
+3. **Container mounting**: Certificates are mounted into nginx container at runtime
+4. **Automatic configuration**: nginx configuration is automatically templated
+   with the correct certificate paths
+
+While it would be possible to reuse certificates for local testing (since we
+always use `test.local`), this approach ensures that the deployment workflow is
+identical between local testing and production, reducing the chance of
+environment-specific issues.
+
+## 4. Verification and Smoke Testing
 
 After deployment, verify that all services are running correctly.
 

application/share/bin/shell-utils.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# Application-specific shell utilities for Torrust Tracker Demo
+# Common logging functions for application scripts
+#
+# Usage:
+#   # Source this file in your script:
+#   source "$(dirname "${BASH_SOURCE[0]}")/shell-utils.sh"
+#
+#   # Use logging functions:
+#   log_info "This is an info message"
+#   log_success "Operation completed successfully"
+#   log_warning "This is a warning"
+#   log_error "This is an error"
+#   log_section "Major Section Title"
+
+# Application shell utilities - can be sourced multiple times safely
+export APP_SHELL_UTILS_LOADED=1
+
+# Colors for output
+export RED='\033[0;31m'
+export GREEN='\033[0;32m'
+export YELLOW='\033[1;33m'
+export BLUE='\033[0;34m'
+export CYAN='\033[0;36m'
+export MAGENTA='\033[0;35m'
+export WHITE='\033[1;37m'
+export NC='\033[0m' # No Color
+
+# Core logging function
+log() {
+    local message="$1"
+    echo -e "${message}"
+}
+
+# Logging functions with standardized prefixes and colors
+log_info() {
+    log "${BLUE}[INFO]${NC} $1"
+}
+
+log_success() {
+    log "${GREEN}[SUCCESS]${NC} $1"
+}
+
+log_warning() {
+    log "${YELLOW}[WARNING]${NC} $1"
+}
+
+log_error() {
+    log "${RED}[ERROR]${NC} $1"
+}
+
+log_debug() {
+    if [[ "${DEBUG:-false}" == "true" ]]; then
+        log "${CYAN}[DEBUG]${NC} $1"
+    fi
+}
+
+# Section header logging - displays a prominent section separator
+log_section() {
+    log ""
+    log "${BLUE}===============================================${NC}"
+    log "${BLUE}$1${NC}"
+    log "${BLUE}===============================================${NC}"
+}
+
+# Check if command exists
+command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}