Merge #219: feat: [#217] Demo slice - Release and Run commands scaffolding

fd53b7f refactor: [#217] Rename run_configuration_tests to run_configure_release_run_tests (Jose Celano)
3ede934 feat: [#217] Add separate E2E validation modules for release and run commands (Jose Celano)
5c14832 docs: [#217] Update Docker-in-Docker ADR with implementation details (Jose Celano)
30a1c3f fix: [#217] Wrap std::env::set_var in unsafe block (Rust 1.81+) (Jose Celano)
862499c feat: [#217] Enable Docker-in-Docker for E2E tests to test run command (Jose Celano)
1643b44 docs: [#217] document Phase 9 manual E2E test issues and resolution (Jose Celano)
ed6f480 feat: [#217] wire RunCommandController to RunCommandHandler (Jose Celano)
1921015 feat: [#217] implement Phase 9 - StartServicesStep for run command (Jose Celano)
351e6fe refactor: [#217] Add symmetric logging to release and provision handlers (Jose Celano)
6ef21d2 refactor: [#217] Improve configure handler clarity (Jose Celano)
0ec82fd refactor: [#217] Extract load and validate methods in command handlers (Jose Celano)
419e35b fix(clippy): [#217] Fix clippy linting errors (Jose Celano)
92509c9 refactor(error-handling): [#217] Standardize EnvironmentNotFound error across all handlers (Jose Celano)
ca4ee88 refactor(release): [#217] Validate instance IP as precondition for release (Jose Celano)
043560c feat(release): [#217] Complete Phase 8 - Refactor release handler to three-level architecture (Jose Celano)
8a0291a docs: [#217] update phase 6 and 7 documentation with implementation status (Jose Celano)
bc32270 feat: [#217] implement phase 6 - release step prepares docker compose files (Jose Celano)
26528f9 test: [#217] add release and run commands to E2E test workflows (Jose Celano)
fb529ec feat: [#217] implement state transitions for release and run handlers (Jose Celano)
98aec5d feat: [#217] complete application layer handlers for release and run commands (Jose Celano)
7c113c0 feat: [#217] add release and run steps in application layer (Jose Celano)
2d766df feat: [#217] add release and run command handlers in application layer (Jose Celano)
0791846 feat: [#217] add release and run controllers (wired but empty) (Jose Celano)
e97483a refactor: [#217] rename e2e-config-tests to e2e-config-and-release-tests (Jose Celano)
ea55f4f feat: [#217] add release and run CLI commands (no-op) (Jose Celano)

Pull request description:

  ## Summary

  This PR implements the foundational scaffolding for the `release` and `run` commands using a minimal docker-compose deployment with nginx. The goal is to validate the full pipeline (release → run → verify) before adding complexity with the actual Torrust Tracker services.

  **Issue**: Closes #217

  ## Implementation Progress

  ### Phase Tracking

  | Phase | Description | Status |
  |-------|-------------|--------|
  | **Phase 1** | Presentation Layer - CLI Commands (No-Op) | ✅ Complete |
  | **Phase 2** | E2E Test Refactoring (Safety Net) | ✅ Complete |
  | **Phase 3** | Presentation Layer - Controllers | ✅ Complete |
  | **Phase 4** | Application Layer - Command Handlers (Skeleton) | ✅ Complete |
  | **Phase 5** | Application Layer - State Transitions | ✅ Complete |
  | **Phase 6** | Steps Layer - Prepare Compose Files | ✅ Complete |
  | **Phase 7** | Infrastructure Layer - Docker Compose Template Renderer | ✅ Complete |
  | **Phase 8** | Steps Layer - Transfer Files to VM | ✅ Complete |
  | **Phase 9** | Steps Layer - Start Services | ✅ Complete |
  | **Phase 10** | E2E Test Coverage | ✅ Complete |

  ### What's Implemented

  #### CLI Commands
  - `release` - Release application files to a configured environment
  - `run` - Run the application stack on a released environment

  #### State Transitions
  - `Configured` → `Releasing` → `Released` (release command)
  - `Released` → `Starting` → `Running` (run command)

  #### Infrastructure

  **Docker Compose Template Renderer**
  - `DockerComposeTemplateRenderer` following the same pattern as `AnsibleTemplateRenderer` and `TofuTemplateRenderer`
  - Embedded docker-compose.yml template with nginx:alpine demo service
  - Template extraction via `TemplateManager` (double-indirection pattern)

  **Release Handler - Three-Level Architecture (Phase 8)**
  - `ReleaseCommandHandler` refactored to follow Provision Handler patterns
  - `RenderDockerComposeTemplatesStep` - Renders templates locally
  - `DeployComposeFilesStep` - Deploys files to VM via Ansible playbook
  - `ReleaseTraceWriter` - Generates trace files for failure diagnostics
  - `ReleaseStep` enum and `ReleaseFailureContext` for step tracking
  - Ansible playbook `deploy-compose-files.yml` for file transfer

  **Run Handler - Three-Level Architecture (Phase 9)**
  - `RunCommandHandler` with full step architecture
  - `StartServicesStep` - Starts Docker Compose services on VM
  - `RunTraceWriter` - Generates trace files for failure diagnostics
  - `RunStep` enum and `RunFailureContext` for step tracking
  - Ansible playbook `start-services.yml.tera` for service management

  **E2E Test Coverage (Phase 10)**
  - `RunningServicesValidator` - Remote action to validate running services via SSH
  - Separate validation modules per command (SRP):
    - `run_configuration_validation` - Validates configure command (Docker installed)
    - `run_release_validation` - Validates release command (Compose files deployed)
    - `run_run_validation` - Validates run command (services running)
  - Full workflow tested: create → register → configure → release → run → destroy

  ### Files Changed

  **Application Layer**
  - `src/application/command_handlers/release/` - ReleaseCommandHandler (refactored)
  - `src/application/command_handlers/run/` - RunCommandHandler (fully implemented)
  - `src/application/steps/application/deploy_compose_files.rs` - DeployComposeFilesStep
  - `src/application/steps/application/start_services.rs` - StartServicesStep (NEW)
  - `src/application/steps/rendering/docker_compose_templates.rs` - RenderDockerComposeTemplatesStep

  **Domain Layer**
  - `src/domain/environment/state/release_failed.rs` - ReleaseStep enum, ReleaseFailureContext
  - `src/domain/environment/state/run_failed.rs` - RunStep enum, RunFailureContext (NEW)

  **Infrastructure Layer**
  - `src/infrastructure/external_tools/docker_compose/template/renderer/mod.rs` - DockerComposeTemplateRenderer
  - `src/infrastructure/remote_actions/running_services.rs` - RunningServicesValidator (NEW)
  - `src/infrastructure/trace/writer/commands/release.rs` - ReleaseTraceWriter
  - `src/infrastructure/trace/writer/commands/run.rs` - RunTraceWriter (NEW)

  **Presentation Layer**
  - `src/presentation/controllers/release/` - Release controller
  - `src/presentation/controllers/run/` - Run controller

  **Testing**
  - `src/testing/e2e/tasks/run_configuration_validation.rs` - Configure command validation
  - `src/testing/e2e/tasks/run_release_validation.rs` - Release command validation (NEW)
  - `src/testing/e2e/tasks/run_run_validation.rs` - Run command validation (NEW)
  - `src/bin/e2e_config_and_release_tests.rs` - Full workflow E2E tests

  **Templates**
  - `templates/docker-compose/docker-compose.yml` - nginx:alpine demo service
  - `templates/ansible/deploy-compose-files.yml` - File deployment playbook
  - `templates/ansible/start-services.yml.tera` - Service start playbook (NEW)

  ### Manual E2E Test

  ```bash
  # Full workflow verified:
  cargo run -- create environment --env-file envs/e2e-full.json
  cargo run -- provision e2e-full
  cargo run -- configure e2e-full
  cargo run -- release e2e-full
  # Verified: docker-compose.yml deployed to VM at /opt/torrust/
  cargo run -- run e2e-full
  # Verified: nginx service running
  cargo run -- destroy e2e-full
  ```

  ## All Phases Complete ✅

  This PR is ready for review. All phases have been implemented:
  - Full `release` and `run` command implementation
  - Complete E2E test coverage with separate validation per command
  - Three-level architecture (Commands → Steps → Actions) consistently applied

  ## Related Documentation

  See `docs/issues/217-demo-slice-release-run-commands.md` for detailed implementation plan.

ACKs for top commit:
  josecelano:
    ACK fd53b7f

Tree-SHA512: 0bb61a847cd332a9afdff102783b34c69059975d151de853d0d248882cbcea4ba252dddf3edbfc338ea806a727868e6a2cb838ef10b692bd0471e46608174985

Author: josecelano

.cargo/config.toml

@@ -2,7 +2,7 @@
 lint = "run --bin linter all"
 e2e-full = "run --bin e2e-tests-full"
 e2e-provision = "run --bin e2e-provision-tests"
-e2e-config = "run --bin e2e-config-tests"
+e2e-config = "run --bin e2e-config-and-release-tests"
 cov = "llvm-cov"
 cov-check = "llvm-cov --all-features --workspace --fail-under-lines 70"
 cov-lcov = "llvm-cov --lcov --output-path=./.coverage/lcov.info"

.github/workflows/test-e2e-config.yml

@@ -22,7 +22,7 @@ on:
   workflow_dispatch: # Allow manual triggering
 
 jobs:
-  e2e-config-tests:
+  e2e-config-and-release-tests:
     runs-on: ubuntu-latest
     timeout-minutes: 45 # Timeout for complete configuration testing with software installation
 
@@ -62,16 +62,16 @@ jobs:
           chmod 600 fixtures/testing_rsa
           ls -la fixtures/testing_rsa
 
-      - name: Build E2E configuration tests binary
+      - name: Build E2E configuration and release tests binary
         run: |
-          cargo build --bin e2e-config-tests --release
+          cargo build --bin e2e-config-and-release-tests --release
 
-      - name: Run E2E configuration test
+      - name: Run E2E configuration and release test
         run: |
-          # Run the E2E configuration test with debug logging for better debugging
-          echo "🚀 Starting E2E configuration test at $(date)"
-          cargo run --bin e2e-config-tests
-          echo "✅ E2E configuration test completed at $(date)"
+          # Run the E2E configuration and release test with debug logging for better debugging
+          echo "🚀 Starting E2E configuration and release test at $(date)"
+          cargo run --bin e2e-config-and-release-tests
+          echo "✅ E2E configuration and release test completed at $(date)"
         env:
           # Preserve environment variables for the E2E test
           RUST_LOG: debug

AGENTS.md

@@ -130,8 +130,8 @@ These principles should guide all development decisions, code reviews, and featu
 - **E2E Tests**:
   - `cargo run --bin e2e-tests-full` - Comprehensive tests (⚠️ **LOCAL ONLY** - cannot run on GitHub Actions due to network connectivity issues)
   - `cargo run --bin e2e-provision-and-destroy-tests` - Infrastructure provisioning and destruction tests (GitHub runner-compatible)
-  - `cargo run --bin e2e-config-tests` - Software installation and configuration tests (GitHub runner-compatible)
-  - Pre-commit hook runs the split tests (`e2e-provision-and-destroy-tests` + `e2e-config-tests`) for GitHub Copilot compatibility
+  - `cargo run --bin e2e-config-and-release-tests` - Software installation, configuration, release, and run workflow tests (GitHub runner-compatible)
+  - Pre-commit hook runs the split tests (`e2e-provision-and-destroy-tests` + `e2e-config-and-release-tests`) for GitHub Copilot compatibility
   - See [`docs/e2e-testing.md`](docs/e2e-testing.md) for detailed information about CI limitations
 
 Follow the project conventions and ensure all checks pass.

Cargo.toml

@@ -25,8 +25,8 @@ name = "e2e-tests-full"
 path = "src/bin/e2e_tests_full.rs"
 
 [[bin]]
-name = "e2e-config-tests"
-path = "src/bin/e2e_config_tests.rs"
+name = "e2e-config-and-release-tests"
+path = "src/bin/e2e_config_and_release_tests.rs"
 
 [[bin]]
 name = "e2e-provision-and-destroy-tests"

README.md

@@ -167,7 +167,7 @@ Use the E2E test binaries to run automated infrastructure tests with hardcoded e
 cargo run --bin e2e-tests-full
 
 # Run individual E2E test suites
-cargo run --bin e2e-config-tests      # Configuration generation and validation tests
+cargo run --bin e2e-config-and-release-tests      # Configuration, release, and run workflow tests
 cargo run --bin e2e-provision-and-destroy-tests   # Infrastructure provisioning tests
 
 # Keep the test environment after completion for inspection

docker/provisioned-instance/Dockerfile

@@ -33,10 +33,17 @@ RUN apt-get update && apt-get install -y \
     lsb-release \
     # APT transport for HTTPS repositories
     apt-transport-https \
+    # iptables for Docker networking
+    iptables \
     # Clean up package cache
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 
+# Install Docker using official installation script
+# This installs both Docker daemon and Docker Compose plugin
+RUN curl -fsSL https://get.docker.com | sh \
+    && rm -rf /var/lib/apt/lists/*
+
 # Configure SSH server
 RUN mkdir -p /var/run/sshd \
     # Configure SSH for password authentication initially (tests will set up keys later)
@@ -45,7 +52,7 @@ RUN mkdir -p /var/run/sshd \
     && sed -i 's/#PasswordAuthentication yes/PasswordAuthentication yes/' /etc/ssh/sshd_config
 
 # Create torrust user matching LXD VM configuration
-RUN useradd -m -s /bin/bash -G sudo torrust \
+RUN useradd -m -s /bin/bash -G sudo,docker torrust \
     # Set a simple password for initial SSH access (tests will set up keys later)
     && echo "torrust:torrust123" | chpasswd \
     # Configure passwordless sudo

docker/provisioned-instance/supervisord.conf

@@ -8,13 +8,21 @@ logfile_maxbytes=50MB
 logfile_backups=10
 loglevel=info
 
+[program:dockerd]
+command=/usr/bin/dockerd --host=unix:///var/run/docker.sock --storage-driver=vfs
+stdout_logfile=/var/log/supervisor/dockerd.log
+stderr_logfile=/var/log/supervisor/dockerd.log
+autorestart=true
+startretries=3
+priority=5
+
 [program:sshd]
 command=/usr/sbin/sshd -D
 stdout_logfile=/var/log/supervisor/sshd.log
 stderr_logfile=/var/log/supervisor/sshd.log
 autorestart=true
 startretries=3
-priority=1
+priority=10
 
 [unix_http_server]
 file=/var/run/supervisor.sock

docker/ssh-server/Dockerfile

@@ -28,7 +28,9 @@ RUN ssh-keygen -A
 # Create test user for SSH authentication
 RUN adduser -D -s /bin/sh testuser && \
     echo 'testuser:testpass' | chpasswd && \
-    addgroup testuser wheel
+    addgroup testuser wheel && \
+    # Enable passwordless sudo for wheel group (required for deployment testing)
+    echo '%wheel ALL=(ALL) NOPASSWD: ALL' >> /etc/sudoers
 
 # Configure SSH daemon
 RUN mkdir -p /run/sshd && \

docs/codebase-architecture.md

@@ -209,7 +209,7 @@ Application initialization and lifecycle management:
 **Binary Files:**
 
 - ✅ `src/bin/linter.rs` - Code quality linting binary
-- ✅ `src/bin/e2e-config-tests.rs` - E2E configuration tests
+- ✅ `src/bin/e2e-config-and-release-tests.rs` - E2E configuration and release tests
 - ✅ `src/bin/e2e-provision-and-destroy-tests.rs` - E2E provisioning and destruction tests
 - ✅ `src/bin/e2e-tests-full.rs` - Full E2E test suite
 

docs/contributing/commit-process.md

@@ -135,7 +135,7 @@ This script runs all mandatory checks:
 3. **Run tests**: `cargo test`
 4. **Test documentation builds**: `cargo doc --no-deps --bins --examples --workspace --all-features`
 5. **Run E2E provision and destroy tests**: `cargo run --bin e2e-provision-and-destroy-tests`
-6. **Run E2E configuration tests**: `cargo run --bin e2e-config-tests`
+6. **Run E2E configuration and release tests**: `cargo run --bin e2e-config-and-release-tests`
 
 **Note**: Code coverage is checked automatically in CI via GitHub Actions, not in the pre-commit script, to keep local commits fast and efficient.